1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/4 - Building the toolchain.txt	Sat Aug 14 16:37:11 2010 +0200
     1.3 @@ -0,0 +1,142 @@
     1.4 +File.........: 4 - Building 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 +Building the toolchain  /
    1.10 +_______________________/
    1.11 +
    1.12 +
    1.13 +To build the toolchain, simply type:
    1.14 +  ct-ng build
    1.15 +
    1.16 +This will use the above configuration to retrieve, extract and patch the
    1.17 +components, build, install and eventually test your newly built toolchain.
    1.18 +
    1.19 +You are then free to add the toolchain /bin directory in your PATH to use
    1.20 +it at will.
    1.21 +
    1.22 +In any case, you can get some terse help. Just type:
    1.23 +  ct-ng help
    1.24 +or:
    1.25 +  man 1 ct-ng
    1.26 +
    1.27 +
    1.28 +Stopping and restarting a build |
    1.29 +--------------------------------+
    1.30 +
    1.31 +If you want to stop the build after a step you are debugging, you can pass the
    1.32 +variable STOP to make:
    1.33 +  ct-ng build STOP=some_step
    1.34 +
    1.35 +Conversely, if you want to restart a build at a specific step you are
    1.36 +debugging, you can pass the RESTART variable to make:
    1.37 +  ct-ng build RESTART=some_step
    1.38 +
    1.39 +Alternatively, you can call make with the name of a step to just do that step:
    1.40 +  ct-ng libc_headers
    1.41 +is equivalent to:
    1.42 +  ct-ng build RESTART=libc_headers STOP=libc_headers
    1.43 +
    1.44 +The shortcuts +step_name and step_name+ allow to respectively stop or restart
    1.45 +at that step. Thus:
    1.46 +  ct-ng +libc_headers              and:    ct-ng libc_headers+
    1.47 +are equivalent to:
    1.48 +  ct-ng build STOP=libc_headers    and:    ct-ng build RESTART=libc_headers
    1.49 +
    1.50 +To obtain the list of acceptable steps, please call:
    1.51 +  ct-ng list-steps
    1.52 +
    1.53 +Note that in order to restart a build, you'll have to say 'Y' to the config
    1.54 +option CT_DEBUG_CT_SAVE_STEPS, and that the previous build effectively went
    1.55 +that far.
    1.56 +
    1.57 +
    1.58 +Building all toolchains at once |
    1.59 +--------------------------------+
    1.60 +
    1.61 +You can build all samples; simply call:
    1.62 +  ct-ng build-all
    1.63 +
    1.64 +
    1.65 +Overriding the number of // jobs |
    1.66 +---------------------------------+
    1.67 +
    1.68 +If you want to override the number of jobs to run in // (the -j option to
    1.69 +make), you can either re-enter the menuconfig, or simply add it on the command
    1.70 +line, as such:
    1.71 +  ct-ng build.4
    1.72 +
    1.73 +which tells crosstool-NG to override the number of // jobs to 4.
    1.74 +
    1.75 +You can see the actions that support overriding the number of // jobs in
    1.76 +the help menu. Those are the ones with [.#] after them (eg. build[.#] or
    1.77 +build-all[.#], and so on...).
    1.78 +
    1.79 +
    1.80 +Note on // jobs |
    1.81 +----------------+
    1.82 +
    1.83 +The crosstool-NG script 'ct-ng' is a Makefile-script. It does *not* execute
    1.84 +in parallel (there is not much to gain). When speaking of // jobs, we are
    1.85 +refering to the number of // jobs when making the *components*. That is, we
    1.86 +speak of the number of // jobs used to build gcc, glibc, and so on...
    1.87 +
    1.88 +
    1.89 +Tools wrapper |
    1.90 +--------------+
    1.91 +
    1.92 +Starting with gcc-4.3 come two new dependencies: GMP and MPFR. With gcc-4.4,
    1.93 +come three new ones: PPL, CLooG/ppl and MPC. With gcc-4.5 again comes a new
    1.94 +dependency on libelf. These are libraries that enable advanced features to
    1.95 +gcc. Additionally, some of those libraries can be used by binutils and gdb.
    1.96 +Unfortunately, not all systems on which crosstool-NG runs have all of those
    1.97 +libraries. And for those that do, the versions of those libraries may be
    1.98 +older than the version required by gcc (and binutils and gdb). To date,
    1.99 +Debian stable (aka Lenny) is lagging behind on some, and is missing the
   1.100 +others.
   1.101 +
   1.102 +This is why crosstool-NG builds its own set of libraries as part of the
   1.103 +toolchain.
   1.104 +
   1.105 +The companion libraries can be built either as static libraries, or as shared
   1.106 +libraries. The default is to build static libraries, and is the safe way.
   1.107 +If you decide to use static companion libraries, then you can stop reading
   1.108 +this section.
   1.109 +
   1.110 +But if you prefer to have shared libraries, then read on...
   1.111 +
   1.112 +Building shared companion libraries poses no problem at build time, as
   1.113 +crosstool-NG correctly points gcc (and binutils and gdb) to the correct
   1.114 +place where our own version of the libraries are installed. But it poses
   1.115 +a problem when gcc et al. are run: the place where the libraries are is most
   1.116 +probably not known to the host dynamic linker. Still worse, if the host system
   1.117 +has its own versions, then ld.so would load the wrong libraries!
   1.118 +
   1.119 +So we have to force the dynamic linker to load the correct version. We do this
   1.120 +by using the LD_LIBRARY_PATH variable, that informs the dynamic linker where
   1.121 +to look for shared libraries prior to searching its standard places. But we
   1.122 +can't impose that burden on all the system (because it'd be a nightmare to
   1.123 +configure, and because two toolchains on the same system may use different
   1.124 +versions of the libraries); so we have to do it on a per-toolchain basis.
   1.125 +
   1.126 +So we rename all binaries of the toolchain (by adding a dot '.' as their first
   1.127 +character), and add a small program, the so-called "tools wrapper", that
   1.128 +correctly sets LD_LIBRARY_PATH prior to running the real tool.
   1.129 +
   1.130 +First, the wrapper was written as a POSIX-compliant shell script. That shell
   1.131 +script is very simple, if not trivial, and works great. The only drawback is
   1.132 +that it does not work on host systems that lack a shell, for example the
   1.133 +MingW32 environment. To solve the issue, the wrapper has been re-written in C,
   1.134 +and compiled at build time. This C wrapper is much more complex than the shell
   1.135 +script, and although it sems to be working, it's been only lightly tested.
   1.136 +Some of the expected short-comings with this C wrapper are;
   1.137 + - multi-byte file names may not be handled correctly
   1.138 + - it's really big for what it does
   1.139 +
   1.140 +So, the default wrapper installed with your toolchain is the shell script.
   1.141 +If you know that your system is missing a shell, then you shall use the C
   1.142 +wrapper (and report back whether it works, or does not work, for you).
   1.143 +
   1.144 +A final word on the subject: do not build shared libraries. Build them
   1.145 +static, and you'll be safe.