1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/5 - Using the toolchain.txt	Thu Aug 26 23:36:54 2010 +0200
     1.3 @@ -0,0 +1,103 @@
     1.4 +File.........: 5 - Using the toolchain.txt
     1.5 +Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
     1.6 +License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
     1.7 +
     1.8 +
     1.9 +Using the toolchain  /
    1.10 +____________________/
    1.11 +
    1.12 +
    1.13 +Using the toolchain is as simple as adding the toolchain's bin directory in
    1.14 +your PATH, such as:
    1.15 +  export PATH="${PATH}:/your/toolchain/path/bin"
    1.16 +
    1.17 +and then using the target tuple to tell the build systems to use your
    1.18 +toolchain:
    1.19 +  ./configure --target=your-target-tuple
    1.20 +or
    1.21 +  make CC=your-target-tuple-gcc
    1.22 +or
    1.23 +  make CROSS_COMPILE=your-target-tuple-
    1.24 +and so on...
    1.25 +
    1.26 +It is strongly advised not to use the toolchain sys-root directory as an
    1.27 +install directory for your programs/packages. If you do so, you will not be
    1.28 +able to use your toolchain for another project. It is even strongly advised
    1.29 +that your toolchain is chmod-ed to read-only once successfully build, so that
    1.30 +you don't go polluting your toolchain with your programs/packages' files.
    1.31 +
    1.32 +Thus, when you build a program/package, install it in a separate directory,
    1.33 +eg. /your/root. This directory is the /image/ of what would be in the root file
    1.34 +system of your target, and will contain all that your programs/packages have
    1.35 +installed.
    1.36 +
    1.37 +
    1.38 +The 'populate' script |
    1.39 +----------------------+
    1.40 +
    1.41 +When your root directory is ready, it is still missing some important bits: the
    1.42 +toolchain's libraries. To populate your root directory with those libs, just
    1.43 +run:
    1.44 +  your-target-tuple-populate -s /your/root -d /your/root-populated
    1.45 +
    1.46 +This will copy /your/root into /your/root-populated, and put the needed and only
    1.47 +the needed libraries there. Thus you don't polute /your/root with any cruft that
    1.48 +would no longer be needed should you have to remove stuff. /your/root always
    1.49 +contains only those things you install in it.
    1.50 +
    1.51 +You can then use /your/root-populated to build up your file system image, a
    1.52 +tarball, or to NFS-mount it from your target, or whatever you need.
    1.53 +
    1.54 +The populate script accepts the following options:
    1.55 +
    1.56 + -s src_dir
    1.57 +    Use 'src_dir' as the un-populated root directory.
    1.58 +
    1.59 + -d dst_dir
    1.60 +    Put the populated root directory in 'dst_dir'.
    1.61 +
    1.62 + -l lib1 [...]
    1.63 +    Always add specified libraries.
    1.64 +
    1.65 + -L file
    1.66 +    Always add libraries listed in 'file'.
    1.67 +
    1.68 + -f
    1.69 +    Remove 'dst_dir' if it previously existed; continue even if any library
    1.70 +    specified with -l or -L is missing.
    1.71 +
    1.72 + -v
    1.73 +    Be verbose, and tell what's going on (you can see exactly where libs are
    1.74 +    coming from).
    1.75 +
    1.76 + -h
    1.77 +    Print the help.
    1.78 +
    1.79 +See 'your-target-tuple-populate -h' for more information on the options.
    1.80 +
    1.81 +Here is how populate works:
    1.82 +
    1.83 +  1) performs some sanity checks:
    1.84 +     - src_dir and dst_dir are specified
    1.85 +     - src_dir exists
    1.86 +     - unless forced, dst_dir does not exist
    1.87 +     - src_dir != dst_dir
    1.88 +
    1.89 +  2) copy src_dir to dst_dir
    1.90 +
    1.91 +  3) add forced libraries to dst_dir
    1.92 +     - build the list from -l and -L options
    1.93 +     - get forced libraries from the sysroot (see below for heuristics)
    1.94 +       - abort on the first missing library, unless -f is specified
    1.95 +
    1.96 +  4) add all missing libraries to dst_dir
    1.97 +     - scan dst_dir for every ELF files that are 'executable' or
    1.98 +       'shared object'
    1.99 +     - list the "NEEDED Shared library" fields
   1.100 +       - check if the library is already in dst_dir/lib or dst_dir/usr/lib
   1.101 +       - if not, get the library from the sysroot
   1.102 +         - if it's in sysroot/lib, copy it to dst_dir/lib
   1.103 +         - if it's in sysroot/usr/lib, copy it to dst_dir/usr/lib
   1.104 +         - in both cases, use the SONAME of the library to create the file
   1.105 +           in dst_dir
   1.106 +         - if it was not found in the sysroot, this is an error.