docs/4 - Building the toolchain.txt
author "Yann E. MORIN" <yann.morin.1998@free.fr>
Tue Mar 11 22:11:43 2014 +0100 (2014-03-11)
changeset 3293 e11a8a2e225d
parent 2564 5d4e91c0343e
permissions -rw-r--r--
comptools: do not force build of make-3.81 unless really needed

On systems with make-3.82, we forcibly force the build and the use
of make-3.81

But some newer tools break when building with make-3.81. For example,
eglibc-3.18 breaks.

Introduce a new blind options that tools may select if they require
make-3.81. If the system does not have make-3.81, and this option is
selected, then we force the build of make-3.81. Otherwise, we leave
it to the user to decide on his own.

Note that no component selects this option for now. It will come in
later patches as we find them.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
yann@2076
     1
File.........: 4 - Building the toolchain.txt
yann@2908
     2
Copyright....: (C) 2010 Yann E. MORIN <yann.morin.1998@free.fr>
yann@2076
     3
License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
yann@2076
     4
yann@2076
     5
yann@2076
     6
Building the toolchain  /
yann@2076
     7
_______________________/
yann@2076
     8
yann@2076
     9
yann@2076
    10
To build the toolchain, simply type:
yann@2076
    11
  ct-ng build
yann@2076
    12
yann@2076
    13
This will use the above configuration to retrieve, extract and patch the
yann@2076
    14
components, build, install and eventually test your newly built toolchain.
yann@2076
    15
yann@2076
    16
You are then free to add the toolchain /bin directory in your PATH to use
yann@2076
    17
it at will.
yann@2076
    18
yann@2076
    19
In any case, you can get some terse help. Just type:
yann@2076
    20
  ct-ng help
yann@2076
    21
or:
yann@2076
    22
  man 1 ct-ng
yann@2076
    23
yann@2076
    24
yann@2076
    25
Stopping and restarting a build |
yann@2076
    26
--------------------------------+
yann@2076
    27
yann@2076
    28
If you want to stop the build after a step you are debugging, you can pass the
yann@2076
    29
variable STOP to make:
yann@2076
    30
  ct-ng build STOP=some_step
yann@2076
    31
yann@2076
    32
Conversely, if you want to restart a build at a specific step you are
yann@2076
    33
debugging, you can pass the RESTART variable to make:
yann@2076
    34
  ct-ng build RESTART=some_step
yann@2076
    35
yann@2076
    36
Alternatively, you can call make with the name of a step to just do that step:
yann@2076
    37
  ct-ng libc_headers
yann@2076
    38
is equivalent to:
yann@2076
    39
  ct-ng build RESTART=libc_headers STOP=libc_headers
yann@2076
    40
yann@2076
    41
The shortcuts +step_name and step_name+ allow to respectively stop or restart
yann@2076
    42
at that step. Thus:
yann@2076
    43
  ct-ng +libc_headers              and:    ct-ng libc_headers+
yann@2076
    44
are equivalent to:
yann@2076
    45
  ct-ng build STOP=libc_headers    and:    ct-ng build RESTART=libc_headers
yann@2076
    46
yann@2076
    47
To obtain the list of acceptable steps, please call:
yann@2076
    48
  ct-ng list-steps
yann@2076
    49
yann@2076
    50
Note that in order to restart a build, you'll have to say 'Y' to the config
yann@2076
    51
option CT_DEBUG_CT_SAVE_STEPS, and that the previous build effectively went
yann@2076
    52
that far.
yann@2076
    53
yann@2076
    54
yann@2076
    55
Building all toolchains at once |
yann@2076
    56
--------------------------------+
yann@2076
    57
yann@2076
    58
You can build all samples; simply call:
yann@2076
    59
  ct-ng build-all
yann@2076
    60
yann@2076
    61
yann@2076
    62
Overriding the number of // jobs |
yann@2076
    63
---------------------------------+
yann@2076
    64
yann@2076
    65
If you want to override the number of jobs to run in // (the -j option to
yann@2076
    66
make), you can either re-enter the menuconfig, or simply add it on the command
yann@2076
    67
line, as such:
yann@2076
    68
  ct-ng build.4
yann@2076
    69
yann@2076
    70
which tells crosstool-NG to override the number of // jobs to 4.
yann@2076
    71
yann@2076
    72
You can see the actions that support overriding the number of // jobs in
yann@2076
    73
the help menu. Those are the ones with [.#] after them (eg. build[.#] or
yann@2076
    74
build-all[.#], and so on...).
yann@2076
    75
yann@2076
    76
yann@2076
    77
Note on // jobs |
yann@2076
    78
----------------+
yann@2076
    79
yann@2076
    80
The crosstool-NG script 'ct-ng' is a Makefile-script. It does *not* execute
yann@2076
    81
in parallel (there is not much to gain). When speaking of // jobs, we are
yann@2076
    82
refering to the number of // jobs when making the *components*. That is, we
yann@2076
    83
speak of the number of // jobs used to build gcc, glibc, and so on...
yann@2076
    84
yann@2076
    85
yann@2076
    86
Tools wrapper |
yann@2076
    87
--------------+
yann@2076
    88
yann@2076
    89
Starting with gcc-4.3 come two new dependencies: GMP and MPFR. With gcc-4.4,
yann@2076
    90
come three new ones: PPL, CLooG/ppl and MPC. With gcc-4.5 again comes a new
yann@2076
    91
dependency on libelf. These are libraries that enable advanced features to
yann@2076
    92
gcc. Additionally, some of those libraries can be used by binutils and gdb.
yann@2076
    93
Unfortunately, not all systems on which crosstool-NG runs have all of those
yann@2076
    94
libraries. And for those that do, the versions of those libraries may be
yann@2076
    95
older than the version required by gcc (and binutils and gdb). To date,
yann@2076
    96
Debian stable (aka Lenny) is lagging behind on some, and is missing the
yann@2076
    97
others.
yann@2076
    98
yann@2076
    99
This is why crosstool-NG builds its own set of libraries as part of the
yann@2076
   100
toolchain.
yann@2076
   101
yann@2076
   102
The companion libraries can be built either as static libraries, or as shared
yann@2076
   103
libraries. The default is to build static libraries, and is the safe way.
yann@2076
   104
If you decide to use static companion libraries, then you can stop reading
yann@2076
   105
this section.
yann@2076
   106
yann@2076
   107
But if you prefer to have shared libraries, then read on...
yann@2076
   108
yann@2076
   109
Building shared companion libraries poses no problem at build time, as
yann@2076
   110
crosstool-NG correctly points gcc (and binutils and gdb) to the correct
yann@2076
   111
place where our own version of the libraries are installed. But it poses
yann@2076
   112
a problem when gcc et al. are run: the place where the libraries are is most
yann@2076
   113
probably not known to the host dynamic linker. Still worse, if the host system
yann@2076
   114
has its own versions, then ld.so would load the wrong libraries!
yann@2076
   115
yann@2076
   116
So we have to force the dynamic linker to load the correct version. We do this
yann@2076
   117
by using the LD_LIBRARY_PATH variable, that informs the dynamic linker where
yann@2076
   118
to look for shared libraries prior to searching its standard places. But we
yann@2076
   119
can't impose that burden on all the system (because it'd be a nightmare to
yann@2076
   120
configure, and because two toolchains on the same system may use different
yann@2076
   121
versions of the libraries); so we have to do it on a per-toolchain basis.
yann@2076
   122
yann@2076
   123
So we rename all binaries of the toolchain (by adding a dot '.' as their first
yann@2076
   124
character), and add a small program, the so-called "tools wrapper", that
yann@2076
   125
correctly sets LD_LIBRARY_PATH prior to running the real tool.
yann@2076
   126
yann@2076
   127
First, the wrapper was written as a POSIX-compliant shell script. That shell
yann@2076
   128
script is very simple, if not trivial, and works great. The only drawback is
yann@2076
   129
that it does not work on host systems that lack a shell, for example the
yann@2076
   130
MingW32 environment. To solve the issue, the wrapper has been re-written in C,
yann@2076
   131
and compiled at build time. This C wrapper is much more complex than the shell
antony@2564
   132
script, and although it seems to be working, it's been only lightly tested.
yann@2076
   133
Some of the expected short-comings with this C wrapper are;
yann@2076
   134
 - multi-byte file names may not be handled correctly
yann@2076
   135
 - it's really big for what it does
yann@2076
   136
yann@2076
   137
So, the default wrapper installed with your toolchain is the shell script.
yann@2076
   138
If you know that your system is missing a shell, then you shall use the C
yann@2076
   139
wrapper (and report back whether it works, or does not work, for you).
yann@2076
   140
yann@2076
   141
A final word on the subject: do not build shared libraries. Build them
yann@2076
   142
static, and you'll be safe.