docs/5 - Using the toolchain.txt
author "Yann E. MORIN" <yann.morin.1998@anciens.enib.fr>
Wed Sep 07 01:22:37 2011 +0200 (2011-09-07)
changeset 2653 e5fc5c9ea78a
parent 2563 e17f35b05539
child 2753 710fa859bfe6
child 2912 6467c949c91c
permissions -rw-r--r--
scripts: fix sysroot prefix dir

The sysroot prefix dir was broken in #4960f5d9f829 due to a mishap
when making the out-of-sysroot lib/ symlink: the './' was mistakenly
changed into a single '.' .

Although Jonathan suggested restoring the missing '/' to restore it to
normal operation, I prefered using an explicit pushd/popd to be extra
sure of the symlink location and target, along with a fix in the sysroot
relative directory calculation.

Reported-by: Jonathan Grundon <JGrundon@xos.com>
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@anciens.enib.fr>
     1 File.........: 5 - Using the toolchain.txt
     2 Copyright....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
     3 License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
     4 
     5 
     6 Using the toolchain  /
     7 ____________________/
     8 
     9 
    10 Using the toolchain is as simple as adding the toolchain's bin directory in
    11 your PATH, such as:
    12   export PATH="${PATH}:/your/toolchain/path/bin"
    13 
    14 and then using the target tuple to tell the build systems to use your
    15 toolchain:
    16   ./configure --target=your-target-tuple
    17 or
    18   make CC=your-target-tuple-gcc
    19 or
    20   make CROSS_COMPILE=your-target-tuple-
    21 and so on...
    22 
    23 It is strongly advised not to use the toolchain sysroot directory as an
    24 install directory for your programs/packages. If you do so, you will not be
    25 able to use your toolchain for another project. It is even strongly advised
    26 that your toolchain is chmod-ed to read-only once successfully build, so that
    27 you don't go polluting your toolchain with your programs/packages' files.
    28 
    29 Thus, when you build a program/package, install it in a separate directory,
    30 eg. /your/root. This directory is the /image/ of what would be in the root file
    31 system of your target, and will contain all that your programs/packages have
    32 installed.
    33 
    34 
    35 The 'populate' script |
    36 ----------------------+
    37 
    38 When your root directory is ready, it is still missing some important bits: the
    39 toolchain's libraries. To populate your root directory with those libs, just
    40 run:
    41   your-target-tuple-populate -s /your/root -d /your/root-populated
    42 
    43 This will copy /your/root into /your/root-populated, and put the needed and only
    44 the needed libraries there. Thus you don't pollute /your/root with any cruft that
    45 would no longer be needed should you have to remove stuff. /your/root always
    46 contains only those things you install in it.
    47 
    48 You can then use /your/root-populated to build up your file system image, a
    49 tarball, or to NFS-mount it from your target, or whatever you need.
    50 
    51 The populate script accepts the following options:
    52 
    53  -s src_dir
    54     Use 'src_dir' as the un-populated root directory.
    55 
    56  -d dst_dir
    57     Put the populated root directory in 'dst_dir'.
    58 
    59  -l lib1 [...]
    60     Always add specified libraries.
    61 
    62  -L file
    63     Always add libraries listed in 'file'.
    64 
    65  -f
    66     Remove 'dst_dir' if it previously existed; continue even if any library
    67     specified with -l or -L is missing.
    68 
    69  -v
    70     Be verbose, and tell what's going on (you can see exactly where libs are
    71     coming from).
    72 
    73  -h
    74     Print the help.
    75 
    76 See 'your-target-tuple-populate -h' for more information on the options.
    77 
    78 Here is how populate works:
    79 
    80   1) performs some sanity checks:
    81      - src_dir and dst_dir are specified
    82      - src_dir exists
    83      - unless forced, dst_dir does not exist
    84      - src_dir != dst_dir
    85 
    86   2) copy src_dir to dst_dir
    87 
    88   3) add forced libraries to dst_dir
    89      - build the list from -l and -L options
    90      - get forced libraries from the sysroot (see below for heuristics)
    91        - abort on the first missing library, unless -f is specified
    92 
    93   4) add all missing libraries to dst_dir
    94      - scan dst_dir for every ELF files that are 'executable' or
    95        'shared object'
    96      - list the "NEEDED Shared library" fields
    97        - check if the library is already in dst_dir/lib or dst_dir/usr/lib
    98        - if not, get the library from the sysroot
    99          - if it's in sysroot/lib, copy it to dst_dir/lib
   100          - if it's in sysroot/usr/lib, copy it to dst_dir/usr/lib
   101          - in both cases, use the SONAME of the library to create the file
   102            in dst_dir
   103          - if it was not found in the sysroot, this is an error.