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.