docs/5 - Using the toolchain.txt
author "Yann E. MORIN" <yann.morin.1998@anciens.enib.fr>
Sat Sep 24 21:47:47 2011 +0200 (2011-09-24)
branch1.11
changeset 2679 9fd11a562b78
parent 2076 b58109b7b321
child 2563 e17f35b05539
permissions -rw-r--r--
1.11: close branch

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