diff -r 000000000000 -r b58109b7b321 docs/4 - Building the toolchain.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/4 - Building the toolchain.txt Sat Aug 14 16:37:11 2010 +0200 @@ -0,0 +1,142 @@ +File.........: 4 - Building the toolchain.txt +Copyrigth....: (C) 2010 Yann E. MORIN +License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5 + + +Building the toolchain / +_______________________/ + + +To build the toolchain, simply type: + ct-ng build + +This will use the above configuration to retrieve, extract and patch the +components, build, install and eventually test your newly built toolchain. + +You are then free to add the toolchain /bin directory in your PATH to use +it at will. + +In any case, you can get some terse help. Just type: + ct-ng help +or: + man 1 ct-ng + + +Stopping and restarting a build | +--------------------------------+ + +If you want to stop the build after a step you are debugging, you can pass the +variable STOP to make: + ct-ng build STOP=some_step + +Conversely, if you want to restart a build at a specific step you are +debugging, you can pass the RESTART variable to make: + ct-ng build RESTART=some_step + +Alternatively, you can call make with the name of a step to just do that step: + ct-ng libc_headers +is equivalent to: + ct-ng build RESTART=libc_headers STOP=libc_headers + +The shortcuts +step_name and step_name+ allow to respectively stop or restart +at that step. Thus: + ct-ng +libc_headers and: ct-ng libc_headers+ +are equivalent to: + ct-ng build STOP=libc_headers and: ct-ng build RESTART=libc_headers + +To obtain the list of acceptable steps, please call: + ct-ng list-steps + +Note that in order to restart a build, you'll have to say 'Y' to the config +option CT_DEBUG_CT_SAVE_STEPS, and that the previous build effectively went +that far. + + +Building all toolchains at once | +--------------------------------+ + +You can build all samples; simply call: + ct-ng build-all + + +Overriding the number of // jobs | +---------------------------------+ + +If you want to override the number of jobs to run in // (the -j option to +make), you can either re-enter the menuconfig, or simply add it on the command +line, as such: + ct-ng build.4 + +which tells crosstool-NG to override the number of // jobs to 4. + +You can see the actions that support overriding the number of // jobs in +the help menu. Those are the ones with [.#] after them (eg. build[.#] or +build-all[.#], and so on...). + + +Note on // jobs | +----------------+ + +The crosstool-NG script 'ct-ng' is a Makefile-script. It does *not* execute +in parallel (there is not much to gain). When speaking of // jobs, we are +refering to the number of // jobs when making the *components*. That is, we +speak of the number of // jobs used to build gcc, glibc, and so on... + + +Tools wrapper | +--------------+ + +Starting with gcc-4.3 come two new dependencies: GMP and MPFR. With gcc-4.4, +come three new ones: PPL, CLooG/ppl and MPC. With gcc-4.5 again comes a new +dependency on libelf. These are libraries that enable advanced features to +gcc. Additionally, some of those libraries can be used by binutils and gdb. +Unfortunately, not all systems on which crosstool-NG runs have all of those +libraries. And for those that do, the versions of those libraries may be +older than the version required by gcc (and binutils and gdb). To date, +Debian stable (aka Lenny) is lagging behind on some, and is missing the +others. + +This is why crosstool-NG builds its own set of libraries as part of the +toolchain. + +The companion libraries can be built either as static libraries, or as shared +libraries. The default is to build static libraries, and is the safe way. +If you decide to use static companion libraries, then you can stop reading +this section. + +But if you prefer to have shared libraries, then read on... + +Building shared companion libraries poses no problem at build time, as +crosstool-NG correctly points gcc (and binutils and gdb) to the correct +place where our own version of the libraries are installed. But it poses +a problem when gcc et al. are run: the place where the libraries are is most +probably not known to the host dynamic linker. Still worse, if the host system +has its own versions, then ld.so would load the wrong libraries! + +So we have to force the dynamic linker to load the correct version. We do this +by using the LD_LIBRARY_PATH variable, that informs the dynamic linker where +to look for shared libraries prior to searching its standard places. But we +can't impose that burden on all the system (because it'd be a nightmare to +configure, and because two toolchains on the same system may use different +versions of the libraries); so we have to do it on a per-toolchain basis. + +So we rename all binaries of the toolchain (by adding a dot '.' as their first +character), and add a small program, the so-called "tools wrapper", that +correctly sets LD_LIBRARY_PATH prior to running the real tool. + +First, the wrapper was written as a POSIX-compliant shell script. That shell +script is very simple, if not trivial, and works great. The only drawback is +that it does not work on host systems that lack a shell, for example the +MingW32 environment. To solve the issue, the wrapper has been re-written in C, +and compiled at build time. This C wrapper is much more complex than the shell +script, and although it sems to be working, it's been only lightly tested. +Some of the expected short-comings with this C wrapper are; + - multi-byte file names may not be handled correctly + - it's really big for what it does + +So, the default wrapper installed with your toolchain is the shell script. +If you know that your system is missing a shell, then you shall use the C +wrapper (and report back whether it works, or does not work, for you). + +A final word on the subject: do not build shared libraries. Build them +static, and you'll be safe.