File.........: 4 - Building the toolchain.txt
Copyright....: (C) 2010 Yann E. MORIN <yann.morin.1998@free.fr>
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 seems 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.