docs/overview.txt
changeset 1493 0dce3a3986a1
parent 1491 ae44a02d67fb
child 1513 0a405ac9d9ce
     1.1 --- a/docs/overview.txt	Sun Aug 30 00:30:45 2009 +0200
     1.2 +++ b/docs/overview.txt	Sun Aug 30 00:27:12 2009 +0200
     1.3 @@ -25,6 +25,7 @@
     1.4    Testing all toolchains at once
     1.5    Overriding the number of // jobs
     1.6    Note on // jobs
     1.7 +  Tools wrapper
     1.8  Using the toolchain
     1.9  Toolchain types
    1.10  Internals
    1.11 @@ -382,6 +383,52 @@
    1.12  refering to the number of // jobs when making the *components*. That is, we
    1.13  speak of the number of // jobs used to build gcc, glibc, and so on...
    1.14  
    1.15 +Tools wrapper |
    1.16 +--------------+
    1.17 +
    1.18 +Starting with gcc-4.3 come two new dependencies: GMP and MPFR. With gcc-4.4,
    1.19 +come three new ones: GMP, PPL and CLooG/ppl. These are libraries that enable
    1.20 +advanced features to gcc. Additionally, some of the libraries can be used by
    1.21 +binutils and gdb. Unfortunately, not all systems on which crosstool-NG runs
    1.22 +have all of those libraries. And for those that do, the versions of those
    1.23 +libraries may be older than the version required by gcc.
    1.24 +
    1.25 +This is why crosstool-NG builds its own set of libraries as part of the
    1.26 +toolchain.
    1.27 +
    1.28 +The libraries are built as shared libraries, because building them as static
    1.29 +libraries has some short-comings. This poses no problem at build time, as
    1.30 +crosstool-NG correctly points gcc (and binutiols and gdb) to the correct
    1.31 +place where our own version of the libraries are installed. But it poses
    1.32 +a problem when gcc et al. are run: the place where the libraries are is most
    1.33 +probably not known to the host dynamic linker. Still worse, if the host system
    1.34 +has its own versions, then ld.so would load the wrong library!
    1.35 +
    1.36 +So we have to force the dynamic linker to load the correct version. We do this
    1.37 +by using the LD_LIBRARY_PATH variable, that informs the dynamic linker where
    1.38 +to look for shared libraries prior to searching its standard places. But we
    1.39 +can't impose that burden on all the system (because it'd be a nightmare to
    1.40 +configure, and because two tolchains on the same system may use different
    1.41 +versions of the libraries); so we have to do it on a per-toolchain basis.
    1.42 +
    1.43 +So we rename all binaries of the toolchain (by adding a dot '.' as their first
    1.44 +character), and add a small program, the so-called "tools wrapper", that
    1.45 +correctly sets LD_LIBRARY_PATH prior to running the real tool.
    1.46 +
    1.47 +First, the wrapper was written as a POSIX-compliant shell script. That shell
    1.48 +script is very simple, if not trivial, and works great. The only drawback is
    1.49 +that it does not work on host systems that lack a shell, for example the
    1.50 +MingW32 environment. To solve the issue, the wrapper has been re-written in C,
    1.51 +and compiled at build time. This C wrapper is much more complex than the shell
    1.52 +script, and although it sems to be working, it's been only lightly tested.
    1.53 +Some of the expected short-comings with this C wrapper are;
    1.54 + - multi-byte file names may not be handled correctly
    1.55 + - it's really big for what it does
    1.56 +
    1.57 +So, the default wrapper installed with your toolchain is the shell script.
    1.58 +If you know that your system is missing a shell, then you shall use the C
    1.59 +wrapper (and report back whether it works, or does not work, for you).
    1.60 +
    1.61  
    1.62  _______________________
    1.63                        /