1.1 --- a/docs/overview.txt	Sun Apr 15 16:45:11 2007 +0000
     1.2 +++ b/docs/overview.txt	Tue Apr 17 22:22:46 2007 +0000
     1.3 @@ -22,9 +22,9 @@
     1.4  and requiring specially crafted options to build and work seamlessly. This
     1.5  is usually not that easy, even in the not-so-trivial case of native toolchains.
     1.6  The work reaches a higher degree of complexity when it comes to cross-
     1.7 -compilation, where it can becomes quite a nightmare...
     1.8 +compilation, where it can become quite a nightmare...
     1.9  
    1.10 -Some cross-toolchain exits on the internet, and can be used for general
    1.11 +Some cross-toolchains exist on the internet, and can be used for general
    1.12  development, but they have a number of limitations:
    1.13    - they can be general purpose, in that they are configured for the majority:
    1.14      no optimisation for your specific target,
    1.15 @@ -100,6 +100,67 @@
    1.16  You are then free to add the toolchain /bin directory in your PATH to use
    1.17  it at will.
    1.18  
    1.19 +
    1.20 +___________________
    1.21 +                  /
    1.22 +Toolchain types  /
    1.23 +________________/
    1.24 +
    1.25 +There are four kinds of toolchains you could encounter.
    1.26 +
    1.27 +First off, you must understand the following: when it comes to compilers there
    1.28 +are up to four machines involved:
    1.29 +  1) the machine configuring the toolchain components: the config machine
    1.30 +  2) the machine building the toolchain components:    the build machine
    1.31 +  3) the machine running the toolchain:                the host machine
    1.32 +  4) the machine the toolchain is building for:        the target machine
    1.33 +
    1.34 +We can most of the time assume that the config machine and the build machine
    1.35 +are the same. Most of the time, this will be true. The only time it isn't
    1.36 +is if you're using distributed compilation (such as distcc). Let's forget
    1.37 +this for the sake of simplicity.
    1.38 +
    1.39 +So we're left with three machines:
    1.40 + - build
    1.41 + - host
    1.42 + - target
    1.43 +
    1.44 +Any toolchain will involve those three machines. You can be as pretty sure of
    1.45 +this as "2 and 2 are 4". Here is how they come into play:
    1.46 +
    1.47 +1) build == host == target
    1.48 +    This is a plain native toolchain, targetting the exact same machine as the
    1.49 +    one it is built on, and running again on this exact same machine. You have
    1.50 +    to build such a toolchain when you want to use an updated component, such
    1.51 +    as a newer gcc for example.
    1.52 +    ct-ng calls it "native".
    1.53 +
    1.54 +2) build == host != target
    1.55 +    This is a classic cross-toolchain, which is expected to be run on the same
    1.56 +    machine it is compiled on, and generate code to run on a second machine,
    1.57 +    the target.
    1.58 +    ct-ng calls it "cross".
    1.59 +
    1.60 +3) build != host == target
    1.61 +    Such a toolchain is also a native toolchain, as it targets the same machine
    1.62 +    as it runs on. But it is build on another machine. You want such a
    1.63 +    toolchain when porting to a new architecture, or if the build machine is
    1.64 +    much faster than the host machine.
    1.65 +    ct-ng calls it "cross-native".
    1.66 +
    1.67 +4) build != host != target
    1.68 +    This one is called a canadian-toolchain (*), is is tricky. The three
    1.69 +    machines in play are different. You might want such a toolchain if you
    1.70 +    have a fast build machine, but the users will use it on another machine,
    1.71 +    and will produce code to run on a third machine.
    1.72 +    ct-ng calls it "canadian".
    1.73 +
    1.74 +ct-ng can build all these kinds of toolchains (or is aiming at it, anyway!)
    1.75 +
    1.76 +(*) The term Canadian Cross came about because at the time that these issues
    1.77 +    were all being hashed out, Canada had three national political parties.
    1.78 +    http://en.wikipedia.org/wiki/Cross_compiler
    1.79 +
    1.80  _____________
    1.81              /
    1.82  Internals  /