path: root/docs/4 - Building the toolchain.txt
diff options
authorYann E. MORIN" <>2010-08-14 14:37:11 (GMT)
committerYann E. MORIN" <>2010-08-14 14:37:11 (GMT)
commita211f4100d3e0196807dbd3b4f1839c41f79f5b1 (patch)
treed29a9ed57c0946e22afaed850658e4075c6ab1d9 /docs/4 - Building the toolchain.txt
parentebaebdacf45166a587e4e4d2d5e7b2f7a08965e2 (diff)
docs: split into multiple files
The overview.txt file has evolved into more than just an overview. Split it into chapters, and include the misc tutorials. Signed-off-by: "Yann E. MORIN" <>
Diffstat (limited to 'docs/4 - Building the toolchain.txt')
-rw-r--r--docs/4 - Building the toolchain.txt142
1 files changed, 142 insertions, 0 deletions
diff --git a/docs/4 - Building the toolchain.txt b/docs/4 - Building the toolchain.txt
new file mode 100644
index 0000000..9c10e81
--- /dev/null
+++ b/docs/4 - Building the toolchain.txt
@@ -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
+ 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
+This is why crosstool-NG builds its own set of libraries as part of the
+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 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.