docs/5 - Using the toolchain.txt
author Trevor Woerner <twoerner@gmail.com>
Wed Nov 16 16:06:42 2011 -0500 (2011-11-16)
changeset 2753 710fa859bfe6
parent 2564 5d4e91c0343e
child 2764 986e90e1ca27
permissions -rw-r--r--
docs: --target versus --host

In the very beginnings, eons ago, autotools also got confused by this
whole build vs. host vs. target, and got it wrong. Now they fixed it,
but they want to keep backward compatibility, so the --target is still
recongised, although ./configure will complain if you do so. It is
better to use --host.

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