docs/4 - Building the toolchain.txt
author "Yann E. MORIN" <yann.morin.1998@free.fr>
Wed Feb 08 00:44:52 2012 +0100 (2012-02-08)
branch1.14
changeset 2871 1e090655c6ab
parent 2563 e17f35b05539
child 2908 dcdb309b7967
permissions -rw-r--r--
1.14: update version to 1.14.1
     1 File.........: 4 - Building 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 Building the toolchain  /
     7 _______________________/
     8 
     9 
    10 To build the toolchain, simply type:
    11   ct-ng build
    12 
    13 This will use the above configuration to retrieve, extract and patch the
    14 components, build, install and eventually test your newly built toolchain.
    15 
    16 You are then free to add the toolchain /bin directory in your PATH to use
    17 it at will.
    18 
    19 In any case, you can get some terse help. Just type:
    20   ct-ng help
    21 or:
    22   man 1 ct-ng
    23 
    24 
    25 Stopping and restarting a build |
    26 --------------------------------+
    27 
    28 If you want to stop the build after a step you are debugging, you can pass the
    29 variable STOP to make:
    30   ct-ng build STOP=some_step
    31 
    32 Conversely, if you want to restart a build at a specific step you are
    33 debugging, you can pass the RESTART variable to make:
    34   ct-ng build RESTART=some_step
    35 
    36 Alternatively, you can call make with the name of a step to just do that step:
    37   ct-ng libc_headers
    38 is equivalent to:
    39   ct-ng build RESTART=libc_headers STOP=libc_headers
    40 
    41 The shortcuts +step_name and step_name+ allow to respectively stop or restart
    42 at that step. Thus:
    43   ct-ng +libc_headers              and:    ct-ng libc_headers+
    44 are equivalent to:
    45   ct-ng build STOP=libc_headers    and:    ct-ng build RESTART=libc_headers
    46 
    47 To obtain the list of acceptable steps, please call:
    48   ct-ng list-steps
    49 
    50 Note that in order to restart a build, you'll have to say 'Y' to the config
    51 option CT_DEBUG_CT_SAVE_STEPS, and that the previous build effectively went
    52 that far.
    53 
    54 
    55 Building all toolchains at once |
    56 --------------------------------+
    57 
    58 You can build all samples; simply call:
    59   ct-ng build-all
    60 
    61 
    62 Overriding the number of // jobs |
    63 ---------------------------------+
    64 
    65 If you want to override the number of jobs to run in // (the -j option to
    66 make), you can either re-enter the menuconfig, or simply add it on the command
    67 line, as such:
    68   ct-ng build.4
    69 
    70 which tells crosstool-NG to override the number of // jobs to 4.
    71 
    72 You can see the actions that support overriding the number of // jobs in
    73 the help menu. Those are the ones with [.#] after them (eg. build[.#] or
    74 build-all[.#], and so on...).
    75 
    76 
    77 Note on // jobs |
    78 ----------------+
    79 
    80 The crosstool-NG script 'ct-ng' is a Makefile-script. It does *not* execute
    81 in parallel (there is not much to gain). When speaking of // jobs, we are
    82 refering to the number of // jobs when making the *components*. That is, we
    83 speak of the number of // jobs used to build gcc, glibc, and so on...
    84 
    85 
    86 Tools wrapper |
    87 --------------+
    88 
    89 Starting with gcc-4.3 come two new dependencies: GMP and MPFR. With gcc-4.4,
    90 come three new ones: PPL, CLooG/ppl and MPC. With gcc-4.5 again comes a new
    91 dependency on libelf. These are libraries that enable advanced features to
    92 gcc. Additionally, some of those libraries can be used by binutils and gdb.
    93 Unfortunately, not all systems on which crosstool-NG runs have all of those
    94 libraries. And for those that do, the versions of those libraries may be
    95 older than the version required by gcc (and binutils and gdb). To date,
    96 Debian stable (aka Lenny) is lagging behind on some, and is missing the
    97 others.
    98 
    99 This is why crosstool-NG builds its own set of libraries as part of the
   100 toolchain.
   101 
   102 The companion libraries can be built either as static libraries, or as shared
   103 libraries. The default is to build static libraries, and is the safe way.
   104 If you decide to use static companion libraries, then you can stop reading
   105 this section.
   106 
   107 But if you prefer to have shared libraries, then read on...
   108 
   109 Building shared companion libraries poses no problem at build time, as
   110 crosstool-NG correctly points gcc (and binutils and gdb) to the correct
   111 place where our own version of the libraries are installed. But it poses
   112 a problem when gcc et al. are run: the place where the libraries are is most
   113 probably not known to the host dynamic linker. Still worse, if the host system
   114 has its own versions, then ld.so would load the wrong libraries!
   115 
   116 So we have to force the dynamic linker to load the correct version. We do this
   117 by using the LD_LIBRARY_PATH variable, that informs the dynamic linker where
   118 to look for shared libraries prior to searching its standard places. But we
   119 can't impose that burden on all the system (because it'd be a nightmare to
   120 configure, and because two toolchains on the same system may use different
   121 versions of the libraries); so we have to do it on a per-toolchain basis.
   122 
   123 So we rename all binaries of the toolchain (by adding a dot '.' as their first
   124 character), and add a small program, the so-called "tools wrapper", that
   125 correctly sets LD_LIBRARY_PATH prior to running the real tool.
   126 
   127 First, the wrapper was written as a POSIX-compliant shell script. That shell
   128 script is very simple, if not trivial, and works great. The only drawback is
   129 that it does not work on host systems that lack a shell, for example the
   130 MingW32 environment. To solve the issue, the wrapper has been re-written in C,
   131 and compiled at build time. This C wrapper is much more complex than the shell
   132 script, and although it seems to be working, it's been only lightly tested.
   133 Some of the expected short-comings with this C wrapper are;
   134  - multi-byte file names may not be handled correctly
   135  - it's really big for what it does
   136 
   137 So, the default wrapper installed with your toolchain is the shell script.
   138 If you know that your system is missing a shell, then you shall use the C
   139 wrapper (and report back whether it works, or does not work, for you).
   140 
   141 A final word on the subject: do not build shared libraries. Build them
   142 static, and you'll be safe.