1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/4 - Building the toolchain.txt Sun Jul 10 00:02:05 2011 +0200
1.3 @@ -0,0 +1,142 @@
1.4 +File.........: 4 - Building the toolchain.txt
1.5 +Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
1.6 +License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
1.7 +
1.8 +
1.9 +Building the toolchain /
1.10 +_______________________/
1.11 +
1.12 +
1.13 +To build the toolchain, simply type:
1.14 + ct-ng build
1.15 +
1.16 +This will use the above configuration to retrieve, extract and patch the
1.17 +components, build, install and eventually test your newly built toolchain.
1.18 +
1.19 +You are then free to add the toolchain /bin directory in your PATH to use
1.20 +it at will.
1.21 +
1.22 +In any case, you can get some terse help. Just type:
1.23 + ct-ng help
1.24 +or:
1.25 + man 1 ct-ng
1.26 +
1.27 +
1.28 +Stopping and restarting a build |
1.29 +--------------------------------+
1.30 +
1.31 +If you want to stop the build after a step you are debugging, you can pass the
1.32 +variable STOP to make:
1.33 + ct-ng build STOP=some_step
1.34 +
1.35 +Conversely, if you want to restart a build at a specific step you are
1.36 +debugging, you can pass the RESTART variable to make:
1.37 + ct-ng build RESTART=some_step
1.38 +
1.39 +Alternatively, you can call make with the name of a step to just do that step:
1.40 + ct-ng libc_headers
1.41 +is equivalent to:
1.42 + ct-ng build RESTART=libc_headers STOP=libc_headers
1.43 +
1.44 +The shortcuts +step_name and step_name+ allow to respectively stop or restart
1.45 +at that step. Thus:
1.46 + ct-ng +libc_headers and: ct-ng libc_headers+
1.47 +are equivalent to:
1.48 + ct-ng build STOP=libc_headers and: ct-ng build RESTART=libc_headers
1.49 +
1.50 +To obtain the list of acceptable steps, please call:
1.51 + ct-ng list-steps
1.52 +
1.53 +Note that in order to restart a build, you'll have to say 'Y' to the config
1.54 +option CT_DEBUG_CT_SAVE_STEPS, and that the previous build effectively went
1.55 +that far.
1.56 +
1.57 +
1.58 +Building all toolchains at once |
1.59 +--------------------------------+
1.60 +
1.61 +You can build all samples; simply call:
1.62 + ct-ng build-all
1.63 +
1.64 +
1.65 +Overriding the number of // jobs |
1.66 +---------------------------------+
1.67 +
1.68 +If you want to override the number of jobs to run in // (the -j option to
1.69 +make), you can either re-enter the menuconfig, or simply add it on the command
1.70 +line, as such:
1.71 + ct-ng build.4
1.72 +
1.73 +which tells crosstool-NG to override the number of // jobs to 4.
1.74 +
1.75 +You can see the actions that support overriding the number of // jobs in
1.76 +the help menu. Those are the ones with [.#] after them (eg. build[.#] or
1.77 +build-all[.#], and so on...).
1.78 +
1.79 +
1.80 +Note on // jobs |
1.81 +----------------+
1.82 +
1.83 +The crosstool-NG script 'ct-ng' is a Makefile-script. It does *not* execute
1.84 +in parallel (there is not much to gain). When speaking of // jobs, we are
1.85 +refering to the number of // jobs when making the *components*. That is, we
1.86 +speak of the number of // jobs used to build gcc, glibc, and so on...
1.87 +
1.88 +
1.89 +Tools wrapper |
1.90 +--------------+
1.91 +
1.92 +Starting with gcc-4.3 come two new dependencies: GMP and MPFR. With gcc-4.4,
1.93 +come three new ones: PPL, CLooG/ppl and MPC. With gcc-4.5 again comes a new
1.94 +dependency on libelf. These are libraries that enable advanced features to
1.95 +gcc. Additionally, some of those libraries can be used by binutils and gdb.
1.96 +Unfortunately, not all systems on which crosstool-NG runs have all of those
1.97 +libraries. And for those that do, the versions of those libraries may be
1.98 +older than the version required by gcc (and binutils and gdb). To date,
1.99 +Debian stable (aka Lenny) is lagging behind on some, and is missing the
1.100 +others.
1.101 +
1.102 +This is why crosstool-NG builds its own set of libraries as part of the
1.103 +toolchain.
1.104 +
1.105 +The companion libraries can be built either as static libraries, or as shared
1.106 +libraries. The default is to build static libraries, and is the safe way.
1.107 +If you decide to use static companion libraries, then you can stop reading
1.108 +this section.
1.109 +
1.110 +But if you prefer to have shared libraries, then read on...
1.111 +
1.112 +Building shared companion libraries poses no problem at build time, as
1.113 +crosstool-NG correctly points gcc (and binutils and gdb) to the correct
1.114 +place where our own version of the libraries are installed. But it poses
1.115 +a problem when gcc et al. are run: the place where the libraries are is most
1.116 +probably not known to the host dynamic linker. Still worse, if the host system
1.117 +has its own versions, then ld.so would load the wrong libraries!
1.118 +
1.119 +So we have to force the dynamic linker to load the correct version. We do this
1.120 +by using the LD_LIBRARY_PATH variable, that informs the dynamic linker where
1.121 +to look for shared libraries prior to searching its standard places. But we
1.122 +can't impose that burden on all the system (because it'd be a nightmare to
1.123 +configure, and because two toolchains on the same system may use different
1.124 +versions of the libraries); so we have to do it on a per-toolchain basis.
1.125 +
1.126 +So we rename all binaries of the toolchain (by adding a dot '.' as their first
1.127 +character), and add a small program, the so-called "tools wrapper", that
1.128 +correctly sets LD_LIBRARY_PATH prior to running the real tool.
1.129 +
1.130 +First, the wrapper was written as a POSIX-compliant shell script. That shell
1.131 +script is very simple, if not trivial, and works great. The only drawback is
1.132 +that it does not work on host systems that lack a shell, for example the
1.133 +MingW32 environment. To solve the issue, the wrapper has been re-written in C,
1.134 +and compiled at build time. This C wrapper is much more complex than the shell
1.135 +script, and although it sems to be working, it's been only lightly tested.
1.136 +Some of the expected short-comings with this C wrapper are;
1.137 + - multi-byte file names may not be handled correctly
1.138 + - it's really big for what it does
1.139 +
1.140 +So, the default wrapper installed with your toolchain is the shell script.
1.141 +If you know that your system is missing a shell, then you shall use the C
1.142 +wrapper (and report back whether it works, or does not work, for you).
1.143 +
1.144 +A final word on the subject: do not build shared libraries. Build them
1.145 +static, and you'll be safe.