docs/overview.txt
author "Yann E. MORIN" <yann.morin.1998@anciens.enib.fr>
Wed Jun 25 09:04:38 2008 +0000 (2008-06-25)
changeset 619 399b85eeb5be
parent 476 29b33ee36ef6
child 620 af527ad27444
permissions -rw-r--r--
Update samples.

/trunk/samples/armeb-unknown-linux-uclibc/crosstool.config | 5 3 2 0 +++--
/trunk/samples/arm-unknown-linux-gnueabi/crosstool.config | 5 3 2 0 +++--
/trunk/samples/arm-unknown-linux-gnueabi/reported.by | 2 1 1 0 +-
/trunk/samples/mips-unknown-linux-uclibc/crosstool.config | 5 3 2 0 +++--
/trunk/samples/arm-unknown-linux-uclibcgnueabi/crosstool.config | 5 3 2 0 +++--
/trunk/samples/ia64-unknown-linux-gnu/crosstool.config | 7 3 4 0 +++----
/trunk/samples/armeb-unknown-linux-gnu/crosstool.config | 5 3 2 0 +++--
/trunk/samples/x86_64-unknown-linux-uclibc/crosstool.config | 5 3 2 0 +++--
/trunk/samples/arm-unknown-linux-uclibc/crosstool.config | 5 3 2 0 +++--
/trunk/samples/i586-geode-linux-uclibc/crosstool.config | 5 3 2 0 +++--
/trunk/samples/armeb-unknown-linux-uclibcgnueabi/crosstool.config | 5 3 2 0 +++--
/trunk/samples/i686-nptl-linux-gnu/crosstool.config | 5 3 2 0 +++--
/trunk/samples/alphaev56-unknown-linux-gnu/crosstool.config | 5 3 2 0 +++--
13 files changed, 37 insertions(+), 27 deletions(-)
yann@1
     1
File.........: overview.txt
yann@197
     2
Content......: Overview of how crosstool-NG works.
yann@92
     3
Copyrigth....: (C) 2007 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
yann@192
     4
License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
yann@92
     5
yann@1
     6
________________
yann@1
     7
               /
yann@1
     8
Introduction  /
yann@1
     9
_____________/
yann@1
    10
yann@1
    11
crosstool-NG aims at building toolchains. Toolchains are an essential component
yann@1
    12
in a software development project. It will compile, assemble and link the code
rpjday@436
    13
that is being developed. Some pieces of the toolchain will eventually end up
yann@1
    14
in the resulting binary/ies: static libraries are but an example.
yann@1
    15
yann@1
    16
So, a toolchain is a very sensitive piece of software, as any bug in one of the
yann@1
    17
components, or a poorly configured component, can lead to execution problems,
yann@1
    18
ranging from poor performance, to applications ending unexpectedly, to
yann@1
    19
mis-behaving software (which more than often is hard to detect), to hardware
rpjday@436
    20
damage, or even to human risks (which is more than regrettable).
yann@1
    21
yann@1
    22
Toolchains are made of different piece of software, each being quite complex
yann@1
    23
and requiring specially crafted options to build and work seamlessly. This
yann@1
    24
is usually not that easy, even in the not-so-trivial case of native toolchains.
yann@1
    25
The work reaches a higher degree of complexity when it comes to cross-
yann@40
    26
compilation, where it can become quite a nightmare...
yann@1
    27
yann@40
    28
Some cross-toolchains exist on the internet, and can be used for general
yann@1
    29
development, but they have a number of limitations:
yann@1
    30
  - they can be general purpose, in that they are configured for the majority:
yann@1
    31
    no optimisation for your specific target,
yann@1
    32
  - they can be prepared for a specific target and thus are not easy to use,
yann@1
    33
    nor optimised for, or even supporting your target,
rpjday@436
    34
  - they often are using aging components (compiler, C library, etc...) not
yann@1
    35
    supporting special features of your shiny new processor;
yann@1
    36
On the other side, these toolchain offer some advantages:
yann@1
    37
  - they are ready to use and quite easy to install and setup,
yann@1
    38
  - they are proven if used by a wide community.
yann@1
    39
yann@1
    40
But once you want to get all the juice out of your specific hardware, you will
yann@197
    41
want to build your own toolchain. This is where crosstool-NG comes into play.
yann@1
    42
rpjday@436
    43
There are also a number of tools that build toolchains for specific needs,
rpjday@436
    44
which are not really scalable. Examples are:
rpjday@436
    45
  - buildroot (buildroot.uclibc.org) whose main purpose is to build root file
yann@1
    46
    systems, hence the name. But once you have your toolchain with buildroot,
yann@1
    47
    part of it is installed in the root-to-be, so if you want to build a whole
yann@1
    48
    new root, you either have to save the existing one as a template and
yann@1
    49
    restore it later, or restart again from scratch. This is not convenient,
yann@1
    50
  - ptxdist (www.pengutronix.de/software/ptxdist), whose purpose is very
yann@1
    51
    similar to buildroot,
rpjday@436
    52
  - other projects (openembedded.org for example), which is again used to
yann@1
    53
    build root file systems.
yann@1
    54
rpjday@436
    55
crosstool-NG is really targeted at building toolchains, and only toolchains.
yann@1
    56
It is then up to you to use it the way you want.
yann@1
    57
yann@1
    58
___________
yann@1
    59
          /
yann@1
    60
History  /
yann@1
    61
________/
yann@1
    62
rpjday@436
    63
crosstool was first 'conceived' by Dan Kegel, who offered it to the community
yann@1
    64
as a set of scripts, a repository of patches, and some pre-configured, general
yann@1
    65
purpose setup files to be used to configure crosstool. This is available at
yann@203
    66
http://www.kegel.com/crosstool, and the subversion repository is hosted on
yann@203
    67
google at http://code.google.com/p/crosstool/.
yann@1
    68
yann@1
    69
I once managed to add support for uClibc-based toolchains, but it did not make
yann@437
    70
into mainline, mostly because I didn't have time to port the patch forward to
yann@1
    71
the new versions, due in part to the big effort it was taking.
yann@1
    72
yann@1
    73
So I decided to clean up crosstool in the state it was, re-order the things
yann@437
    74
in place, add appropriate support for what I needed, that is uClibc support
yann@437
    75
and a menu-driven configuration, named the new implementation crosstool-NG,
yann@437
    76
(standing for crosstool Next Generation, as many other comunity projects do,
yann@437
    77
and as a wink at the TV series "Star Trek: The Next Generation" ;-) ) and
yann@437
    78
made it available to the community, in case it was of interest to any one.
yann@1
    79
yann@294
    80
___________________________
yann@294
    81
                          /
yann@294
    82
Installing crosstool-NG  /
yann@294
    83
________________________/
yann@294
    84
yann@294
    85
There are two ways you can use crosstool-NG:
yann@294
    86
 - build and install it, then get rid of the sources like you'd do for most
yann@294
    87
   programs,
yann@294
    88
 - or only build it and run from the source directory.
yann@294
    89
yann@294
    90
The former should be used if you got crosstool-NG from a packaged tarball, see
rpjday@436
    91
"Install method", below, while the latter is most useful for developpers that
yann@294
    92
checked the code out from SVN, and want to submit patches, see "The Hacker's
yann@294
    93
way", below.
yann@294
    94
yann@294
    95
Install method |
yann@294
    96
---------------+
yann@294
    97
yann@294
    98
If you go for the install, then you just follow the classical, but yet easy
yann@294
    99
./configure way:
yann@294
   100
  ./configure --prefix=/some/place
yann@294
   101
  make
yann@294
   102
  make install
yann@294
   103
  export PATH="${PATH}:/some/place/bin"
yann@294
   104
yann@294
   105
You can then get rid of crosstool-NG source. Next create a directory to serve
yann@294
   106
as a working place, cd in there and run:
yann@294
   107
  ct-ng help
yann@294
   108
yann@294
   109
See below for complete usage.
yann@294
   110
yann@294
   111
The Hacker's way |
yann@294
   112
-----------------+
yann@294
   113
yann@294
   114
If you go the hacker's way, then the usage is a bit different, although very
yann@294
   115
simple:
yann@294
   116
  ./configure --local
yann@294
   117
  make
yann@294
   118
yann@294
   119
Now, *do not* remove crosstool-NG sources. They are needed to run crosstool-NG!
yann@294
   120
Stay in the directory holding the sources, and run:
yann@294
   121
  ./ct-ng help
yann@294
   122
yann@294
   123
See below for complete usage.
yann@294
   124
yann@294
   125
Now, provided you checked-out the code, you can send me your interesting changes
yann@294
   126
by running:
yann@294
   127
  svn diff
yann@294
   128
yann@294
   129
and mailing me the result! :-P
yann@294
   130
yann@456
   131
Contributed code |
yann@456
   132
-----------------+
yann@456
   133
yann@456
   134
Some people contibuted code that couldn't get merged for various reasons. This
yann@456
   135
code is available as patches in the contrib/ sub-directory. These patches are
yann@456
   136
to be applied to the source of crosstool-NG, prior to installing.
yann@456
   137
yann@168
   138
____________________________
yann@168
   139
                           /
yann@168
   140
Configuring crosstool-NG  /
yann@168
   141
_________________________/
yann@168
   142
yann@277
   143
crosstool-NG is configured by a configurator presenting a menu-stuctured set of
yann@277
   144
options. These options let you specify the way you want your toolchain built,
yann@277
   145
where you want it installed, what architecture and specific processor it
yann@277
   146
will support, the version of the components you want to use, etc... The
yann@277
   147
value for those options are then stored in a configuration file.
yann@277
   148
yann@476
   149
The configurator works the same way you configure your Linux kernel. It is
yann@277
   150
assumed you now how to handle this.
yann@168
   151
yann@168
   152
To enter the menu, type:
yann@192
   153
  ct-ng menuconfig
yann@168
   154
yann@203
   155
Almost every config item has a help entry. Read them carefully.
yann@168
   156
yann@168
   157
String and number options can refer to environment variables. In such a case,
yann@192
   158
you must use the shell syntax: ${VAR}. You shall neither single- nor double-
yann@294
   159
quote the string/number options.
yann@168
   160
yann@192
   161
There are three environment variables that are computed by crosstool-NG, and
yann@168
   162
that you can use:
yann@168
   163
yann@168
   164
CT_TARGET:
yann@335
   165
  It represents the target tuple you are building for. You can use it for
yann@168
   166
  example in the installation/prefix directory, such as:
yann@168
   167
    /opt/x-tools/${CT_TARGET}
yann@168
   168
yann@168
   169
CT_TOP_DIR:
yann@182
   170
  The top directory where crosstool-NG is running. You shouldn't need it in
yann@182
   171
  most cases. There is one case where you may need it: if you have local
yann@182
   172
  patches and you store them in your running directory, you can refer to them
yann@168
   173
  by using CT_TOP_DIR, such as:
yann@168
   174
    ${CT_TOP_DIR}/patches.myproject
yann@168
   175
yann@168
   176
CT_VERSION:
yann@192
   177
  The version of crosstool-NG you are using. Not much use for you, but it's
yann@168
   178
  there if you need it.
yann@168
   179
yann@168
   180
Interesting config options |
yann@476
   181
---------------------------+
yann@168
   182
yann@168
   183
CT_LOCAL_TARBALLS_DIR:
yann@277
   184
  If you already have some tarballs in a direcotry, enter it here. That will
yann@197
   185
  speed up the retrieving phase, where crosstool-NG would otherwise download
yann@168
   186
  those tarballs.
yann@168
   187
yann@168
   188
CT_PREFIX_DIR:
yann@168
   189
  This is where the toolchain will be installed in (and for now, where it
yann@437
   190
  will run from). Common use is to add the target tuple in the directory
yann@277
   191
  path, such as (see above):
yann@277
   192
    /opt/x-tools/${CT_TARGET}
yann@168
   193
yann@168
   194
CT_TARGET_VENDOR:
yann@168
   195
  An identifier for your toolchain, will take place in the vendor part of the
yann@335
   196
  target tuple. It shall *not* contain spaces or dashes. Usually, keep it
yann@168
   197
  to a one-word string, or use underscores to separate words if you need.
yann@168
   198
  Avoid dots, commas, and special characters.
yann@168
   199
yann@168
   200
CT_TARGET_ALIAS:
yann@168
   201
  An alias for the toolchian. It will be used as a prefix to the toolchain
yann@168
   202
  tools. For example, you will have ${CT_TARGET_ALIAS}-gcc
yann@168
   203
yann@246
   204
Also, if you think you don't see enough versions, you can try to enable one of
yann@246
   205
those:
yann@246
   206
yann@246
   207
CT_OBSOLETE:
yann@246
   208
  Show obsolete versions or tools. Most of the time, you don't want to base
yann@246
   209
  your toolchain on too old a version (of gcc, for example). But at times, it
yann@246
   210
  can come handy to use such an old version for regression tests. Those old
yann@294
   211
  versions are hidden behind CT_OBSOLETE.
yann@246
   212
yann@246
   213
CT_EXPERIMENTAL:
yann@246
   214
  Show experimental versions or tools. Again, you might not want to base your
yann@246
   215
  toolchain on too recent tools (eg. gcc) for production. But if you need a
yann@246
   216
  feature present only in a recent version, or a new tool, you can find them
yann@246
   217
  hidden behind CT_EXPERIMENTAL.
yann@246
   218
yann@246
   219
CT_BROKEN:
yann@246
   220
  Show broken versions or tools. Some usefull tools are currently broken: they
yann@246
   221
  won't compile, run, or worse, cause defects when running. But if you are
yann@246
   222
  brave enough, you can try and debug them. They are hidden behind CT_BROKEN,
yann@476
   223
  which itself is hidden behind CT_EXPERIMENTAL.
yann@246
   224
yann@276
   225
Re-building an existing toolchain |
yann@276
   226
----------------------------------+
yann@276
   227
yann@276
   228
If you have an existing toolchain, you can re-use the options used to build it
yann@276
   229
to create a new toolchain. That needs a very little bit of effort on your side
yann@276
   230
but is quite easy. The options to build a toolchain are saved in the build log
yann@276
   231
file that is saved within the toolchain. crosstool-NG can extract those options
yann@276
   232
to recreate a new configuration:
yann@276
   233
  ct-ng extractconfig </path/to/your/build.log
yann@276
   234
yann@276
   235
will extract those options, prompt you for the new ones, which you can later
yann@276
   236
edit with menuconfig.
yann@276
   237
yann@276
   238
Of course, if your build log was compressed, you'd have to use something like:
yann@276
   239
  bzcat /path/to/your/build.log.bz2 |ct-ng extractconfig
yann@276
   240
yann@168
   241
________________________
yann@168
   242
                       /
yann@168
   243
Running crosstool-NG  /
yann@168
   244
_____________________/
yann@1
   245
yann@168
   246
To build the toolchain, simply type:
yann@203
   247
  ct-ng build
yann@135
   248
yann@135
   249
This will use the above configuration to retrieve, extract and patch the
yann@135
   250
components, build, install and eventually test your newly built toolchain.
yann@1
   251
yann@1
   252
You are then free to add the toolchain /bin directory in your PATH to use
yann@1
   253
it at will.
yann@1
   254
yann@135
   255
In any case, you can get some terse help. Just type:
yann@192
   256
  ct-ng help
yann@203
   257
or:
yann@203
   258
  man 1 ct-ng
yann@135
   259
rpjday@436
   260
Stopping and restarting a build |
yann@476
   261
--------------------------------+
yann@135
   262
yann@135
   263
If you want to stop the build after a step you are debugging, you can pass the
yann@135
   264
variable STOP to make:
yann@192
   265
  ct-ng STOP=some_step
yann@135
   266
yann@135
   267
Conversely, if you want to restart a build at a specific step you are
yann@135
   268
debugging, you can pass the RESTART variable to make:
yann@192
   269
  ct-ng RESTART=some_step
yann@135
   270
yann@136
   271
Alternatively, you can call make with the name of a step to just do that step:
yann@192
   272
  ct-ng libc_headers
yann@136
   273
is equivalent to:
yann@192
   274
  ct-ng RESTART=libs_headers STOP=libc_headers
yann@136
   275
yann@304
   276
The shortcuts +step_name and step_name+ allow to respectively stop or restart
yann@136
   277
at that step. Thus:
yann@304
   278
  ct-ng +libc_headers        and:    ct-ng libc_headers+
yann@136
   279
are equivalent to:
yann@192
   280
  ct-ng STOP=libc_headers    and:    ct-ng RESTART=libc_headers
yann@136
   281
yann@181
   282
To obtain the list of acceptable steps, please call:
yann@544
   283
  ct-ng list-steps
yann@181
   284
yann@168
   285
Note that in order to restart a build, you'll have to say 'Y' to the config
yann@168
   286
option CT_DEBUG_CT_SAVE_STEPS, and that the previous build effectively went
yann@168
   287
that far.
yann@92
   288
yann@168
   289
Testing all toolchains at once |
yann@476
   290
-------------------------------+
yann@92
   291
yann@168
   292
You can test-build all samples; simply call:
yann@192
   293
  ct-ng regtest
yann@40
   294
yann@335
   295
Overriding the number of // jobs |
yann@476
   296
---------------------------------+
yann@335
   297
yann@335
   298
If you want to override the number of jobs to run in // (the -j option to
yann@335
   299
make), you can either re-enter the menuconfig, or simply add it on the command
yann@335
   300
line, as such:
yann@335
   301
  ct-ng build.4
yann@335
   302
yann@335
   303
which tells crosstool-NG to override the number of // jobs to 4.
yann@335
   304
yann@335
   305
You can see the actions that support overriding the number of // jobs in
yann@335
   306
the help menu. Those are the ones with [.#] after them (eg. build[.#] or
yann@335
   307
regtest[.#], and so on...).
yann@335
   308
yann@227
   309
_______________________
yann@227
   310
                      /
yann@227
   311
Using the toolchain  /
yann@227
   312
____________________/
yann@227
   313
yann@227
   314
Using the toolchain is as simple as adding the toolchain's bin directory in
yann@227
   315
your PATH, such as:
yann@227
   316
  export PATH="${PATH}:/your/toolchain/path/bin"
yann@227
   317
yann@335
   318
and then using the target tuple to tell the build systems to use your
yann@227
   319
toolchain:
yann@335
   320
  ./configure --target=your-target-tuple
yann@294
   321
or
yann@335
   322
  make CC=your-target-tuple-gcc
yann@294
   323
or
yann@335
   324
  make CROSS_COMPILE=your-target-tuple-
yann@294
   325
and so on...
yann@227
   326
yann@476
   327
It is strongly advised not to use the toolchain sys-root directory as an
yann@476
   328
install directory for your programms/packages. If you do so, you will not be
yann@476
   329
able to use your toolchain for another project. It is even strongly advised
yann@476
   330
that your toolchain is chmod-ed to read-only once successfully build, so that
yann@476
   331
you don't go polluting your toolchain with your programms/packages' files.
yann@476
   332
yann@476
   333
Thus, when you build a program/package, install it in a separate directory,
yann@476
   334
eg. /your/root. This directory is the /image/ of what would be in the root file
yann@476
   335
system of your target, and will contain all that your programms/packages have
yann@476
   336
installed.
yann@476
   337
yann@227
   338
When your root directory is ready, it is still missing some important bits: the
yann@227
   339
toolchain's libraries. To populate your root directory with those libs, just
yann@227
   340
run:
yann@335
   341
  your-target-tuple-populate -s /your/root -d /your/root-populated
yann@227
   342
yann@227
   343
This will copy /your/root into /your/root-populated, and put the needed and only
yann@227
   344
the needed libraries there. Thus you don't polute /your/root with any cruft that
yann@227
   345
would no longer be needed should you have to remove stuff. /your/root always
yann@227
   346
contains only those things you install in it.
yann@227
   347
yann@227
   348
You can then use /your/root-populated to build up your file system image, a
yann@227
   349
tarball, or to NFS-mount it from your target, or whatever you need.
yann@227
   350
yann@294
   351
populate accepts the following options:
yann@294
   352
yann@294
   353
 -s [src_dir]
yann@294
   354
    Use 'src_dir' as the 'source', un-populated root directory
yann@294
   355
yann@294
   356
 -d [dst_dir]
yann@294
   357
    Put the 'destination', populated root directory in 'dst_dir'
yann@294
   358
yann@294
   359
 -f
yann@294
   360
    Remove 'dst_dir' if it previously existed
yann@294
   361
yann@294
   362
 -v
yann@294
   363
    Be verbose, and tell what's going on (you can see exactly where libs are
yann@294
   364
    coming from).
yann@294
   365
yann@294
   366
 -h
yann@294
   367
    Print the help
yann@294
   368
yann@40
   369
___________________
yann@40
   370
                  /
yann@40
   371
Toolchain types  /
yann@40
   372
________________/
yann@40
   373
yann@40
   374
There are four kinds of toolchains you could encounter.
yann@40
   375
yann@40
   376
First off, you must understand the following: when it comes to compilers there
yann@40
   377
are up to four machines involved:
yann@40
   378
  1) the machine configuring the toolchain components: the config machine
yann@40
   379
  2) the machine building the toolchain components:    the build machine
yann@40
   380
  3) the machine running the toolchain:                the host machine
yann@203
   381
  4) the machine the toolchain is generating code for: the target machine
yann@40
   382
yann@40
   383
We can most of the time assume that the config machine and the build machine
yann@40
   384
are the same. Most of the time, this will be true. The only time it isn't
yann@40
   385
is if you're using distributed compilation (such as distcc). Let's forget
yann@40
   386
this for the sake of simplicity.
yann@40
   387
yann@40
   388
So we're left with three machines:
yann@40
   389
 - build
yann@40
   390
 - host
yann@40
   391
 - target
yann@40
   392
yann@40
   393
Any toolchain will involve those three machines. You can be as pretty sure of
yann@40
   394
this as "2 and 2 are 4". Here is how they come into play:
yann@40
   395
yann@40
   396
1) build == host == target
yann@40
   397
    This is a plain native toolchain, targetting the exact same machine as the
yann@40
   398
    one it is built on, and running again on this exact same machine. You have
yann@40
   399
    to build such a toolchain when you want to use an updated component, such
yann@40
   400
    as a newer gcc for example.
yann@197
   401
    crosstool-NG calls it "native".
yann@40
   402
yann@40
   403
2) build == host != target
yann@40
   404
    This is a classic cross-toolchain, which is expected to be run on the same
yann@40
   405
    machine it is compiled on, and generate code to run on a second machine,
yann@40
   406
    the target.
yann@197
   407
    crosstool-NG calls it "cross".
yann@40
   408
yann@40
   409
3) build != host == target
yann@40
   410
    Such a toolchain is also a native toolchain, as it targets the same machine
yann@40
   411
    as it runs on. But it is build on another machine. You want such a
yann@40
   412
    toolchain when porting to a new architecture, or if the build machine is
yann@40
   413
    much faster than the host machine.
yann@197
   414
    crosstool-NG calls it "cross-native".
yann@40
   415
yann@40
   416
4) build != host != target
yann@92
   417
    This one is called a canadian-toolchain (*), and is tricky. The three
yann@40
   418
    machines in play are different. You might want such a toolchain if you
yann@40
   419
    have a fast build machine, but the users will use it on another machine,
yann@40
   420
    and will produce code to run on a third machine.
yann@197
   421
    crosstool-NG calls it "canadian".
yann@40
   422
yann@197
   423
crosstool-NG can build all these kinds of toolchains (or is aiming at it,
yann@197
   424
anyway!)
yann@40
   425
yann@40
   426
(*) The term Canadian Cross came about because at the time that these issues
yann@40
   427
    were all being hashed out, Canada had three national political parties.
yann@40
   428
    http://en.wikipedia.org/wiki/Cross_compiler
yann@40
   429
yann@1
   430
_____________
yann@1
   431
            /
yann@1
   432
Internals  /
yann@1
   433
__________/
yann@1
   434
yann@92
   435
Internally, crosstool-NG is script-based. To ease usage, the frontend is
yann@92
   436
Makefile-based.
yann@92
   437
yann@92
   438
Makefile front-end |
yann@476
   439
-------------------+
yann@92
   440
yann@203
   441
The entry point to crosstool-NG is the Makefile script "ct-ng". Calling this
yann@203
   442
script with an action will act exactly as if the Makefile was in the current
yann@203
   443
working directory and make was called with the action as rule. Thus:
yann@203
   444
  ct-ng menuconfig
yann@294
   445
yann@203
   446
is equivalent to having the Makefile in CWD, and calling:
yann@203
   447
  make menuconfig
yann@203
   448
yann@203
   449
Having ct-ng as it is avoids copying the Makefile everywhere, and acts as a
yann@203
   450
traditional command.
yann@203
   451
yann@203
   452
ct-ng loads sub- Makefiles from the library directory $(CT_LIB_DIR), as set up
yann@203
   453
at configuration time with ./configure.
yann@203
   454
yann@437
   455
ct-ng also searches for config files, sub-tools, samples, scripts and patches in
yann@203
   456
that library directory.
yann@92
   457
yann@294
   458
Because of a stupid make behavior/bug I was unable to track down, implicit make
yann@294
   459
rules are disabled: installing with --local would triger those rules, and mconf
yann@294
   460
was unbuildable.
yann@294
   461
yann@182
   462
Kconfig parser |
yann@476
   463
---------------+
yann@92
   464
yann@92
   465
The kconfig language is a hacked version, vampirised from the toybox project
yann@182
   466
by Rob LANDLEY (http://www.landley.net/code/toybox/), itself coming from the
yann@294
   467
Linux kernel (http://www.kernel.org/), and (heavily) adapted to my needs.
yann@92
   468
yann@203
   469
The kconfig parsers (conf and mconf) are not installed pre-built, but as
yann@203
   470
source files. Thus you can have the directory where crosstool-NG is installed,
yann@203
   471
exported (via NFS or whatever) and have clients with different architectures
yann@203
   472
use the same crosstool-NG installation, and most notably, the same set of
yann@203
   473
patches.
yann@203
   474
yann@381
   475
Architecture-specific |
yann@476
   476
----------------------+
yann@381
   477
yann@381
   478
An architecture is defined by:
yann@381
   479
yann@381
   480
 - a human-readable name, in lower case letters, with numbers as appropriate.
yann@381
   481
   The underscore is allowed. Eg.: arm, x86_64
yann@381
   482
 - a boolean kconfig option named after the architecture (in capital letters
yann@381
   483
   if possible) prefixed with "ARCH_". Eg.: ARCH_ARM, ARCH_x86_64
yann@381
   484
 - a directory in "arch/" named after the architecture, with the same letters
yann@381
   485
   as above. Eg.: arch/arm, arch/x86_64
yann@381
   486
   This directory contains:
yann@381
   487
   - a configuration file in kconfig syntax, named "config.in", which may be
yann@381
   488
     empty. Eg.: arch/arm/config.in
yann@381
   489
   - a function script in bash-3.0 syntax, named "functions", which shall
yann@381
   490
     follow the API defined below. Eg.: arch/arm/functions
yann@381
   491
yann@381
   492
The "functions" file API:
yann@383
   493
 > the function "CT_DoArchValues"
yann@381
   494
   + parameters: none
yann@381
   495
   + environment:
yann@381
   496
      - all variables from the ".config" file,
yann@381
   497
      - the two variables "target_endian_eb" and "target_endian_el" which are
yann@383
   498
        the endianness suffixes
yann@381
   499
   + return value: 0 upon success, !0 upon failure
yann@381
   500
   + provides:
yann@391
   501
     - mandatory
yann@383
   502
     - the environment variable CT_TARGET_ARCH
yann@389
   503
     - contains:
yann@389
   504
       the architecture part of the target tuple.
yann@389
   505
       Eg.: "armeb" for big endian ARM
yann@389
   506
            "i386" for an i386
yann@389
   507
   + provides:
yann@391
   508
     - optional
yann@389
   509
     - the environment variable CT_TARGET_SYS
yann@456
   510
     - contains:
yann@383
   511
       the sytem part of the target tuple.
yann@383
   512
       Eg.: "gnu" for glibc on most architectures
yann@383
   513
            "gnueabi" for glibc on an ARM EABI
yann@383
   514
     - defaults to:
yann@383
   515
       - for glibc-based toolchain: "gnu"
yann@383
   516
       - for uClibc-based toolchain: "uclibc"
yann@383
   517
   + provides:
yann@383
   518
     - optional
yann@391
   519
     - the environment variable CT_KERNEL_ARCH
yann@383
   520
     - contains:
yann@391
   521
       the architecture name as understandable by the Linux kernel build
yann@391
   522
       system.
yann@391
   523
       Eg.: "arm" for an ARM
yann@391
   524
            "powerpc" for a PowerPC
yann@391
   525
            "i386" for an x86
yann@383
   526
     - defaults to:
yann@391
   527
       ${CT_ARCH}
yann@391
   528
   + provides:
yann@391
   529
     - optional
yann@391
   530
     - the environment variables to configure the cross-gcc
yann@391
   531
       - CT_ARCH_WITH_ARCH
yann@391
   532
       - CT_ARCH_WITH_ABI
yann@391
   533
       - CT_ARCH_WITH_CPU
yann@391
   534
       - CT_ARCH_WITH_TUNE
yann@391
   535
       - CT_ARCH_WITH_FPU
yann@391
   536
       - CT_ARCH_WITH_FLOAT
yann@391
   537
     - contain (defaults):
yann@391
   538
       - CT_ARCH_WITH_ARCH    : the gcc ./configure switch to select architecture level         ( "--with-arch=${CT_ARCH_ARCH}"       )
yann@456
   539
       - CT_ARCH_WITH_ABI     : the gcc ./configure switch to select ABI level                  ( "--with-abi=${CT_ARCH_ABI}"         )
yann@456
   540
       - CT_ARCH_WITH_CPU     : the gcc ./configure switch to select CPU instruction set        ( "--with-cpu=${CT_ARCH_CPU}"         )
yann@456
   541
       - CT_ARCH_WITH_TUNE    : the gcc ./configure switch to select scheduling                 ( "--with-tune=${CT_ARCH_TUNE}"       )
yann@456
   542
       - CT_ARCH_WITH_FPU     : the gcc ./configure switch to select FPU type                   ( "--with-fpu=${CT_ARCH_FPU}"         )
yann@391
   543
       - CT_ARCH_WITH_FLOAT   : the gcc ./configure switch to select floating point arithmetics ( "--with-float=soft" or /empty/      )
yann@391
   544
   + provides:
yann@391
   545
     - optional
yann@391
   546
     - the environment variables to pass to the cross-gcc to build target binaries
yann@391
   547
       - CT_ARCH_ARCH_CFLAG
yann@391
   548
       - CT_ARCH_ABI_CFLAG
yann@391
   549
       - CT_ARCH_CPU_CFLAG
yann@391
   550
       - CT_ARCH_TUNE_CFLAG
yann@391
   551
       - CT_ARCH_FPU_CFLAG
yann@391
   552
       - CT_ARCH_FLOAT_CFLAG
yann@391
   553
       - CT_ARCH_ENDIAN_CFLAG
yann@391
   554
     - contain (defaults):
yann@391
   555
       - CT_ARCH_ARCH_CFLAG   : the gcc switch to select architecture level                     ( "-march=${CT_ARCH_ARCH}"            )
yann@456
   556
       - CT_ARCH_ABI_CFLAG    : the gcc switch to select ABI level                              ( "-mabi=${CT_ARCH_ABI}"              )
yann@391
   557
       - CT_ARCH_CPU_CFLAG    : the gcc switch to select CPU instruction set                    ( "-mcpu=${CT_ARCH_CPU}"              )
yann@391
   558
       - CT_ARCH_TUNE_CFLAG   : the gcc switch to select scheduling                             ( "-mtune=${CT_ARCH_TUNE}"            )
yann@391
   559
       - CT_ARCH_FPU_CFLAG    : the gcc switch to select FPU type                               ( "-mfpu=${CT_ARCH_FPU}"              )
yann@391
   560
       - CT_ARCH_FLOAT_CFLAG  : the gcc switch to choose floating point arithmetics             ( "-msoft-float" or /empty/           )
yann@391
   561
       - CT_ARCH_ENDIAN_CFLAG : the gcc switch to choose big or little endian                   ( "-mbig-endian" or "-mlittle-endian" )
yann@391
   562
     - default to:
yann@391
   563
       see above.
yann@391
   564
     
yann@476
   565
Adding a new version of a conponent |
yann@476
   566
------------------------------------+
yann@476
   567
yann@476
   568
When a new component, such as the Linux kernel, gcc or any other is released,
yann@476
   569
adding the new version to crosstool-NG is quite easy. There is a script that
yann@476
   570
will do all that for you:
yann@476
   571
  tools/addToolVersion.sh
yann@476
   572
yann@476
   573
Run it with no option to get some help.
yann@381
   574
yann@203
   575
Build scripts |
yann@476
   576
--------------+
yann@203
   577
yann@203
   578
To Be Written later...