docs/overview.txt
author "Yann E. MORIN" <yann.morin.1998@anciens.enib.fr>
Tue Apr 17 22:22:46 2007 +0000 (2007-04-17)
changeset 40 8601bce18905
parent 1 eeea35fbf182
child 92 1159b1384a78
permissions -rw-r--r--
Once in a while I write some documentation... Not often enough...
yann@1
     1
File.........: overview.txt
yann@1
     2
Content......: Overview of how ct-ng works.
yann@1
     3
Copyrigth....: (C) 2006 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
yann@1
     4
License......: see COPYING in the root of this package
yann@1
     5
________________
yann@1
     6
               /
yann@1
     7
Introduction  /
yann@1
     8
_____________/
yann@1
     9
yann@1
    10
crosstool-NG aims at building toolchains. Toolchains are an essential component
yann@1
    11
in a software development project. It will compile, assemble and link the code
yann@1
    12
that is being developped. Some pieces of the toolchain will eventually end up
yann@1
    13
in the resulting binary/ies: static libraries are but an example.
yann@1
    14
yann@1
    15
So, a toolchain is a very sensitive piece of software, as any bug in one of the
yann@1
    16
components, or a poorly configured component, can lead to execution problems,
yann@1
    17
ranging from poor performance, to applications ending unexpectedly, to
yann@1
    18
mis-behaving software (which more than often is hard to detect), to hardware
yann@1
    19
damage, or even to human risks (which is more than regretable).
yann@1
    20
yann@1
    21
Toolchains are made of different piece of software, each being quite complex
yann@1
    22
and requiring specially crafted options to build and work seamlessly. This
yann@1
    23
is usually not that easy, even in the not-so-trivial case of native toolchains.
yann@1
    24
The work reaches a higher degree of complexity when it comes to cross-
yann@40
    25
compilation, where it can become quite a nightmare...
yann@1
    26
yann@40
    27
Some cross-toolchains exist on the internet, and can be used for general
yann@1
    28
development, but they have a number of limitations:
yann@1
    29
  - they can be general purpose, in that they are configured for the majority:
yann@1
    30
    no optimisation for your specific target,
yann@1
    31
  - they can be prepared for a specific target and thus are not easy to use,
yann@1
    32
    nor optimised for, or even supporting your target,
yann@1
    33
  - they often are using ageing components (compiler, C library, etc...) not
yann@1
    34
    supporting special features of your shiny new processor;
yann@1
    35
On the other side, these toolchain offer some advantages:
yann@1
    36
  - they are ready to use and quite easy to install and setup,
yann@1
    37
  - they are proven if used by a wide community.
yann@1
    38
yann@1
    39
But once you want to get all the juice out of your specific hardware, you will
yann@1
    40
want to build your own toolchain. This is where crosstool-ng comes into play.
yann@1
    41
yann@1
    42
There are also a number of tools that builds toolchains for specific needs,
yann@1
    43
which is not really scalable. Examples are:
yann@1
    44
  - buildroot (buildroot.uclibc.org) whose main puprpose is to build root file
yann@1
    45
    systems, hence the name. But once you have your toolchain with buildroot,
yann@1
    46
    part of it is installed in the root-to-be, so if you want to build a whole
yann@1
    47
    new root, you either have to save the existing one as a template and
yann@1
    48
    restore it later, or restart again from scratch. This is not convenient,
yann@1
    49
  - ptxdist (www.pengutronix.de/software/ptxdist), whose purpose is very
yann@1
    50
    similar to buildroot,
yann@1
    51
  - other projects (openembeded.org for example), which is again used to
yann@1
    52
    build root file systems.
yann@1
    53
yann@1
    54
crosstool-NG is really targetted at building toolchains, and only toolchains.
yann@1
    55
It is then up to you to use it the way you want.
yann@1
    56
yann@1
    57
___________
yann@1
    58
          /
yann@1
    59
History  /
yann@1
    60
________/
yann@1
    61
yann@1
    62
crosstool was first 'conceived' by Dan Kegel, which offered it to the community,
yann@1
    63
as a set of scripts, a repository of patches, and some pre-configured, general
yann@1
    64
purpose setup files to be used to configure crosstool. This is available at
yann@1
    65
www.kegel.com/crosstool, and the subversion repository is hosted on google at
yann@1
    66
http://code.google.com/p/crosstool/.
yann@1
    67
yann@1
    68
At the time of writing, crosstool only supports building with one C library,
yann@1
    69
namely glibc, and one C compiler, gcc; it is cripled with historical support
yann@1
    70
for legacy components, and is some kind of a mess to upgrade.
yann@1
    71
yann@1
    72
I once managed to add support for uClibc-based toolchains, but it did not make
yann@1
    73
into mainline, mostly because I don't have time to port the patch forward to
yann@1
    74
the new versions, due in part to the big effort it was taking.
yann@1
    75
yann@1
    76
So I decided to clean up crosstool in the state it was, re-order the things
yann@1
    77
in place, and add appropriate support for what I needed, that is uClibc
yann@1
    78
support.
yann@1
    79
yann@1
    80
The only option left to me was rewrite crosstool from scratch. I decided to go
yann@1
    81
this way, and name the new implementation ct-ng, standing for crosstool Next
yann@1
    82
Generation, as many other comunity projects do, and as a wink at the TV series
yann@1
    83
"Star Trek: The Next Generation". ;-)
yann@1
    84
yann@1
    85
_____________
yann@1
    86
            /
yann@1
    87
Operation  /
yann@1
    88
__________/
yann@1
    89
yann@1
    90
ct-ng is configured by a configurator presenting a menu-stuctured set of
yann@1
    91
options. These options let you specify the way you want your toolchain built,
yann@1
    92
where you want it installed, what architecture and specific processor it
yann@1
    93
will support, the version of the components you want to use, etc... The
yann@1
    94
value for those options are then stored in a configuration file.
yann@1
    95
yann@1
    96
You then simply run make. It will use this configuration file to retrieve,
yann@1
    97
extract and patch the components, build, install and test your newly built
yann@1
    98
toolchain.
yann@1
    99
yann@1
   100
You are then free to add the toolchain /bin directory in your PATH to use
yann@1
   101
it at will.
yann@1
   102
yann@40
   103
yann@40
   104
___________________
yann@40
   105
                  /
yann@40
   106
Toolchain types  /
yann@40
   107
________________/
yann@40
   108
yann@40
   109
There are four kinds of toolchains you could encounter.
yann@40
   110
yann@40
   111
First off, you must understand the following: when it comes to compilers there
yann@40
   112
are up to four machines involved:
yann@40
   113
  1) the machine configuring the toolchain components: the config machine
yann@40
   114
  2) the machine building the toolchain components:    the build machine
yann@40
   115
  3) the machine running the toolchain:                the host machine
yann@40
   116
  4) the machine the toolchain is building for:        the target machine
yann@40
   117
yann@40
   118
We can most of the time assume that the config machine and the build machine
yann@40
   119
are the same. Most of the time, this will be true. The only time it isn't
yann@40
   120
is if you're using distributed compilation (such as distcc). Let's forget
yann@40
   121
this for the sake of simplicity.
yann@40
   122
yann@40
   123
So we're left with three machines:
yann@40
   124
 - build
yann@40
   125
 - host
yann@40
   126
 - target
yann@40
   127
yann@40
   128
Any toolchain will involve those three machines. You can be as pretty sure of
yann@40
   129
this as "2 and 2 are 4". Here is how they come into play:
yann@40
   130
yann@40
   131
1) build == host == target
yann@40
   132
    This is a plain native toolchain, targetting the exact same machine as the
yann@40
   133
    one it is built on, and running again on this exact same machine. You have
yann@40
   134
    to build such a toolchain when you want to use an updated component, such
yann@40
   135
    as a newer gcc for example.
yann@40
   136
    ct-ng calls it "native".
yann@40
   137
yann@40
   138
2) build == host != target
yann@40
   139
    This is a classic cross-toolchain, which is expected to be run on the same
yann@40
   140
    machine it is compiled on, and generate code to run on a second machine,
yann@40
   141
    the target.
yann@40
   142
    ct-ng calls it "cross".
yann@40
   143
yann@40
   144
3) build != host == target
yann@40
   145
    Such a toolchain is also a native toolchain, as it targets the same machine
yann@40
   146
    as it runs on. But it is build on another machine. You want such a
yann@40
   147
    toolchain when porting to a new architecture, or if the build machine is
yann@40
   148
    much faster than the host machine.
yann@40
   149
    ct-ng calls it "cross-native".
yann@40
   150
yann@40
   151
4) build != host != target
yann@40
   152
    This one is called a canadian-toolchain (*), is is tricky. The three
yann@40
   153
    machines in play are different. You might want such a toolchain if you
yann@40
   154
    have a fast build machine, but the users will use it on another machine,
yann@40
   155
    and will produce code to run on a third machine.
yann@40
   156
    ct-ng calls it "canadian".
yann@40
   157
yann@40
   158
ct-ng can build all these kinds of toolchains (or is aiming at it, anyway!)
yann@40
   159
yann@40
   160
(*) The term Canadian Cross came about because at the time that these issues
yann@40
   161
    were all being hashed out, Canada had three national political parties.
yann@40
   162
    http://en.wikipedia.org/wiki/Cross_compiler
yann@40
   163
yann@1
   164
_____________
yann@1
   165
            /
yann@1
   166
Internals  /
yann@1
   167
__________/
yann@1
   168
yann@1
   169
<To be completed>