docs/overview.txt
author "Yann E. MORIN" <yann.morin.1998@anciens.enib.fr>
Sun Jan 17 23:06:02 2010 +0100 (2010-01-17)
changeset 1740 c57458bb354d
parent 1643 19205498184e
child 1745 41c2a6716511
permissions -rw-r--r--
configure: do not require hg when configuring in an hg clone

When configuring in an hg clone, we need hg to compute the version string.
It can happen that users do not have Mercurial (eg. if they got a snapshot
rather that they did a full clone). In this case, we can still run, of
course, so simply fill the version string with a sufficiently explicit
value, that does not require hg. The date is a good candidate.
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@628
     6
____________________
yann@628
     7
                   /
yann@628
     8
Table Of Content  /
yann@628
     9
_________________/
yann@628
    10
yann@628
    11
yann@628
    12
Introduction
yann@628
    13
History
yann@1581
    14
Referring to crosstool-NG
yann@628
    15
Installing crosstool-NG
yann@628
    16
  Install method
yann@628
    17
  The hacker's way
yann@1048
    18
  Preparing for packaging
yann@837
    19
  Shell completion
yann@628
    20
  Contributed code
yann@628
    21
Configuring crosstool-NG
yann@628
    22
  Interesting config options
yann@628
    23
  Re-building an existing toolchain
yann@628
    24
Running crosstool-NG
yann@628
    25
  Stopping and restarting a build
yann@628
    26
  Testing all toolchains at once
yann@628
    27
  Overriding the number of // jobs
yann@1491
    28
  Note on // jobs
yann@1493
    29
  Tools wrapper
yann@628
    30
Using the toolchain
yann@1554
    31
  The 'populate' script
yann@628
    32
Toolchain types
yann@1551
    33
  Seemingly-native toolchains
yann@1575
    34
Contributing
yann@1575
    35
  Sending a bug report
yann@1575
    36
  Sending patches
yann@628
    37
Internals
yann@628
    38
  Makefile front-end
yann@628
    39
  Kconfig parser
yann@628
    40
  Architecture-specific
yann@628
    41
  Adding a new version of a component
yann@628
    42
  Build scripts
yann@628
    43
yann@1580
    44
yann@1
    45
________________
yann@1
    46
               /
yann@1
    47
Introduction  /
yann@1
    48
_____________/
yann@1
    49
yann@1
    50
crosstool-NG aims at building toolchains. Toolchains are an essential component
yann@1
    51
in a software development project. It will compile, assemble and link the code
rpjday@436
    52
that is being developed. Some pieces of the toolchain will eventually end up
yann@1
    53
in the resulting binary/ies: static libraries are but an example.
yann@1
    54
yann@1
    55
So, a toolchain is a very sensitive piece of software, as any bug in one of the
yann@1
    56
components, or a poorly configured component, can lead to execution problems,
yann@1
    57
ranging from poor performance, to applications ending unexpectedly, to
yann@1
    58
mis-behaving software (which more than often is hard to detect), to hardware
rpjday@436
    59
damage, or even to human risks (which is more than regrettable).
yann@1
    60
yann@1
    61
Toolchains are made of different piece of software, each being quite complex
yann@1
    62
and requiring specially crafted options to build and work seamlessly. This
yann@1
    63
is usually not that easy, even in the not-so-trivial case of native toolchains.
yann@1
    64
The work reaches a higher degree of complexity when it comes to cross-
yann@40
    65
compilation, where it can become quite a nightmare...
yann@1
    66
yann@40
    67
Some cross-toolchains exist on the internet, and can be used for general
yann@1
    68
development, but they have a number of limitations:
yann@1
    69
  - they can be general purpose, in that they are configured for the majority:
yann@1
    70
    no optimisation for your specific target,
yann@1
    71
  - they can be prepared for a specific target and thus are not easy to use,
yann@1
    72
    nor optimised for, or even supporting your target,
rpjday@436
    73
  - they often are using aging components (compiler, C library, etc...) not
yann@1
    74
    supporting special features of your shiny new processor;
yann@1
    75
On the other side, these toolchain offer some advantages:
yann@1
    76
  - they are ready to use and quite easy to install and setup,
yann@1
    77
  - they are proven if used by a wide community.
yann@1
    78
yann@1
    79
But once you want to get all the juice out of your specific hardware, you will
yann@197
    80
want to build your own toolchain. This is where crosstool-NG comes into play.
yann@1
    81
rpjday@436
    82
There are also a number of tools that build toolchains for specific needs,
rpjday@436
    83
which are not really scalable. Examples are:
rpjday@436
    84
  - buildroot (buildroot.uclibc.org) whose main purpose is to build root file
yann@1
    85
    systems, hence the name. But once you have your toolchain with buildroot,
yann@1
    86
    part of it is installed in the root-to-be, so if you want to build a whole
yann@1
    87
    new root, you either have to save the existing one as a template and
yann@1
    88
    restore it later, or restart again from scratch. This is not convenient,
yann@1
    89
  - ptxdist (www.pengutronix.de/software/ptxdist), whose purpose is very
yann@1
    90
    similar to buildroot,
yann@702
    91
  - other projects (openembedded.org for example), which are again used to
yann@1
    92
    build root file systems.
yann@1
    93
rpjday@436
    94
crosstool-NG is really targeted at building toolchains, and only toolchains.
yann@1
    95
It is then up to you to use it the way you want.
yann@1
    96
yann@1580
    97
yann@1
    98
___________
yann@1
    99
          /
yann@1
   100
History  /
yann@1
   101
________/
yann@1
   102
rpjday@436
   103
crosstool was first 'conceived' by Dan Kegel, who offered it to the community
yann@1
   104
as a set of scripts, a repository of patches, and some pre-configured, general
yann@1
   105
purpose setup files to be used to configure crosstool. This is available at
yann@203
   106
http://www.kegel.com/crosstool, and the subversion repository is hosted on
yann@203
   107
google at http://code.google.com/p/crosstool/.
yann@1
   108
yann@1
   109
I once managed to add support for uClibc-based toolchains, but it did not make
yann@437
   110
into mainline, mostly because I didn't have time to port the patch forward to
yann@1
   111
the new versions, due in part to the big effort it was taking.
yann@1
   112
yann@1
   113
So I decided to clean up crosstool in the state it was, re-order the things
yann@437
   114
in place, add appropriate support for what I needed, that is uClibc support
yann@437
   115
and a menu-driven configuration, named the new implementation crosstool-NG,
yann@437
   116
(standing for crosstool Next Generation, as many other comunity projects do,
yann@437
   117
and as a wink at the TV series "Star Trek: The Next Generation" ;-) ) and
yann@437
   118
made it available to the community, in case it was of interest to any one.
yann@1
   119
yann@1580
   120
yann@1581
   121
_____________________________
yann@1581
   122
                            /
yann@1581
   123
Referring to crosstool-NG  /
yann@1581
   124
__________________________/
yann@1581
   125
yann@1581
   126
yann@1581
   127
The long name of the project is crosstool-NG:
yann@1581
   128
  * no leading uppercase (except as first word in a sentence)
yann@1581
   129
  * crosstool and NG separated with a hyphen (dash)
yann@1581
   130
  * NG in uppercase
yann@1581
   131
yann@1581
   132
Crosstool-NG can also be referred to by its short name CT-NG:
yann@1581
   133
  * all in uppercase
yann@1581
   134
  * CT and NG separated with a hyphen (dash)
yann@1581
   135
yann@1581
   136
The long name is preferred over the short name, except in mail subjects, where
yann@1581
   137
the short name is a better fit.
yann@1581
   138
yann@1581
   139
When referring to a specific version of crosstool-NG, append the version number
yann@1581
   140
either as:
yann@1581
   141
  * crosstool-NG X.Y.Z
yann@1581
   142
    - the long name, a space, and the version string
yann@1581
   143
  * crosstool-ng-X.Y.Z
yann@1581
   144
    - the long name in lowercase, a hyphen (dash), and the version string
yann@1581
   145
    - this is used to name the release tarballs
yann@1581
   146
  * crosstool-ng-X.Y.Z+hg_id
yann@1581
   147
    - the long name in lowercase, a hyphen, the version string, and the Hg id
yann@1581
   148
      (as returned by: ct-ng version)
yann@1581
   149
    - this is used to differentiate between releases and snapshots
yann@1581
   150
yann@1581
   151
The frontend to crosstool-NG is the command ct-ng:
yann@1581
   152
  * all in lowercase
yann@1581
   153
  * ct and ng separated by a hyphen (dash)
yann@1581
   154
yann@1581
   155
yann@294
   156
___________________________
yann@294
   157
                          /
yann@294
   158
Installing crosstool-NG  /
yann@294
   159
________________________/
yann@294
   160
yann@294
   161
There are two ways you can use crosstool-NG:
yann@294
   162
 - build and install it, then get rid of the sources like you'd do for most
yann@294
   163
   programs,
yann@294
   164
 - or only build it and run from the source directory.
yann@294
   165
yann@294
   166
The former should be used if you got crosstool-NG from a packaged tarball, see
rpjday@436
   167
"Install method", below, while the latter is most useful for developpers that
yann@1576
   168
use a clone of the repository, and want to submit patches, see "The Hacker's
yann@294
   169
way", below.
yann@294
   170
yann@294
   171
Install method |
yann@294
   172
---------------+
yann@294
   173
yann@294
   174
If you go for the install, then you just follow the classical, but yet easy
yann@294
   175
./configure way:
yann@294
   176
  ./configure --prefix=/some/place
yann@294
   177
  make
yann@294
   178
  make install
yann@294
   179
  export PATH="${PATH}:/some/place/bin"
yann@294
   180
yann@294
   181
You can then get rid of crosstool-NG source. Next create a directory to serve
yann@294
   182
as a working place, cd in there and run:
yann@294
   183
  ct-ng help
yann@294
   184
yann@294
   185
See below for complete usage.
yann@294
   186
yann@294
   187
The Hacker's way |
yann@294
   188
-----------------+
yann@294
   189
yann@294
   190
If you go the hacker's way, then the usage is a bit different, although very
yann@294
   191
simple:
yann@294
   192
  ./configure --local
yann@294
   193
  make
yann@294
   194
yann@294
   195
Now, *do not* remove crosstool-NG sources. They are needed to run crosstool-NG!
yann@294
   196
Stay in the directory holding the sources, and run:
yann@294
   197
  ./ct-ng help
yann@294
   198
yann@294
   199
See below for complete usage.
yann@294
   200
yann@1554
   201
Now, provided you used a clone of the repository, you can send me your changes.
yann@1575
   202
See the section titled CONTRIBUTING, below, for how to submit changees.
yann@294
   203
yann@1048
   204
Preparing for packaging |
yann@1048
   205
------------------------+
yann@1048
   206
yann@1048
   207
If you plan on packaging crosstool-NG, you surely don't want to install it
yann@1048
   208
in your root file system. The install procedure of crosstool-NG honors the
yann@1048
   209
DESTDIR variable:
yann@1048
   210
yann@1048
   211
  ./configure --prefix=/usr
yann@1048
   212
  make
rpjday@1291
   213
  make DESTDIR=/packaging/place install
yann@1048
   214
yann@837
   215
Shell completion |
yann@837
   216
-----------------+
yann@837
   217
yann@837
   218
crosstool-NG comes with a shell script fragment that defines bash-compatible
yann@837
   219
completion. That shell fragment is currently not installed automatically, but
yann@837
   220
this is planned.
yann@837
   221
yann@837
   222
To install the shell script fragment, you have two options:
yann@837
   223
 - install system-wide, most probably by copying ct-ng.comp into
yann@837
   224
   /etc/bash_completion.d/
yann@837
   225
 - install for a single user, by copying ct-ng.comp into ${HOME}/ and
yann@837
   226
   sourcing this file from your ${HOME}/.bashrc
yann@837
   227
yann@456
   228
Contributed code |
yann@456
   229
-----------------+
yann@456
   230
yann@456
   231
Some people contibuted code that couldn't get merged for various reasons. This
yann@1574
   232
code is available as lzma-compressed patches, in the contrib/ sub-directory.
yann@1574
   233
These patches are to be applied to the source of crosstool-NG, prior to
yann@1574
   234
installing, using something like the following:
yann@1574
   235
  lzcat contrib/foobar.patch.lzma |patch -p1
yann@620
   236
yann@620
   237
There is no guarantee that a particuliar contribution applies to the current
yann@620
   238
version of crosstool-ng, or that it will work at all. Use contributions at
yann@620
   239
your own risk.
yann@620
   240
yann@1580
   241
yann@168
   242
____________________________
yann@168
   243
                           /
yann@168
   244
Configuring crosstool-NG  /
yann@168
   245
_________________________/
yann@168
   246
yann@620
   247
crosstool-NG is configured with a configurator presenting a menu-stuctured set
yann@620
   248
of options. These options let you specify the way you want your toolchain
yann@620
   249
built, where you want it installed, what architecture and specific processor it
yann@277
   250
will support, the version of the components you want to use, etc... The
yann@277
   251
value for those options are then stored in a configuration file.
yann@277
   252
yann@476
   253
The configurator works the same way you configure your Linux kernel. It is
yann@277
   254
assumed you now how to handle this.
yann@168
   255
yann@168
   256
To enter the menu, type:
yann@192
   257
  ct-ng menuconfig
yann@168
   258
yann@203
   259
Almost every config item has a help entry. Read them carefully.
yann@168
   260
yann@168
   261
String and number options can refer to environment variables. In such a case,
yann@192
   262
you must use the shell syntax: ${VAR}. You shall neither single- nor double-
yann@294
   263
quote the string/number options.
yann@168
   264
yann@192
   265
There are three environment variables that are computed by crosstool-NG, and
yann@168
   266
that you can use:
yann@168
   267
yann@168
   268
CT_TARGET:
yann@335
   269
  It represents the target tuple you are building for. You can use it for
yann@168
   270
  example in the installation/prefix directory, such as:
yann@168
   271
    /opt/x-tools/${CT_TARGET}
yann@168
   272
yann@168
   273
CT_TOP_DIR:
yann@182
   274
  The top directory where crosstool-NG is running. You shouldn't need it in
yann@182
   275
  most cases. There is one case where you may need it: if you have local
yann@182
   276
  patches and you store them in your running directory, you can refer to them
yann@168
   277
  by using CT_TOP_DIR, such as:
yann@168
   278
    ${CT_TOP_DIR}/patches.myproject
yann@168
   279
yann@168
   280
CT_VERSION:
yann@192
   281
  The version of crosstool-NG you are using. Not much use for you, but it's
yann@168
   282
  there if you need it.
yann@168
   283
yann@168
   284
Interesting config options |
yann@476
   285
---------------------------+
yann@168
   286
yann@168
   287
CT_LOCAL_TARBALLS_DIR:
yann@277
   288
  If you already have some tarballs in a direcotry, enter it here. That will
yann@197
   289
  speed up the retrieving phase, where crosstool-NG would otherwise download
yann@168
   290
  those tarballs.
yann@168
   291
yann@168
   292
CT_PREFIX_DIR:
yann@168
   293
  This is where the toolchain will be installed in (and for now, where it
yann@437
   294
  will run from). Common use is to add the target tuple in the directory
yann@277
   295
  path, such as (see above):
yann@277
   296
    /opt/x-tools/${CT_TARGET}
yann@168
   297
yann@168
   298
CT_TARGET_VENDOR:
yann@168
   299
  An identifier for your toolchain, will take place in the vendor part of the
yann@335
   300
  target tuple. It shall *not* contain spaces or dashes. Usually, keep it
yann@168
   301
  to a one-word string, or use underscores to separate words if you need.
yann@168
   302
  Avoid dots, commas, and special characters.
yann@168
   303
yann@168
   304
CT_TARGET_ALIAS:
yann@168
   305
  An alias for the toolchian. It will be used as a prefix to the toolchain
yann@168
   306
  tools. For example, you will have ${CT_TARGET_ALIAS}-gcc
yann@168
   307
yann@246
   308
Also, if you think you don't see enough versions, you can try to enable one of
yann@246
   309
those:
yann@246
   310
yann@246
   311
CT_OBSOLETE:
yann@246
   312
  Show obsolete versions or tools. Most of the time, you don't want to base
yann@246
   313
  your toolchain on too old a version (of gcc, for example). But at times, it
yann@246
   314
  can come handy to use such an old version for regression tests. Those old
yann@1300
   315
  versions are hidden behind CT_OBSOLETE. Those versions (or features) are so
yann@1300
   316
  marked because maintaining support for those in crosstool-NG would be too
yann@1300
   317
  costly, time-wise, and time is dear.
yann@246
   318
yann@246
   319
CT_EXPERIMENTAL:
yann@246
   320
  Show experimental versions or tools. Again, you might not want to base your
yann@246
   321
  toolchain on too recent tools (eg. gcc) for production. But if you need a
yann@246
   322
  feature present only in a recent version, or a new tool, you can find them
yann@1300
   323
  hidden behind CT_EXPERIMENTAL. Those versions (or features) did not (yet)
yann@1300
   324
  receive thorough testing in crosstool-NG, and/or are not mature enough to
yann@1300
   325
  be blindly trusted.
yann@246
   326
yann@276
   327
Re-building an existing toolchain |
yann@276
   328
----------------------------------+
yann@276
   329
yann@276
   330
If you have an existing toolchain, you can re-use the options used to build it
yann@276
   331
to create a new toolchain. That needs a very little bit of effort on your side
yann@894
   332
but is quite easy. The options to build a toolchain are saved with the
yann@894
   333
toolchain, and you can retrieve this configuration by running:
yann@894
   334
  ${CT_TARGET}-config
yann@276
   335
yann@894
   336
This will dump the configuration to stdout, so to rebuild a toolchain with this
yann@894
   337
configuration, the following is all you need to do:
yann@894
   338
  ${CT_TARGET}-config >.config
yann@1098
   339
  ct-ng oldconfig
yann@276
   340
yann@894
   341
Then, you can review and change the configuration by running:
yann@894
   342
  ct-ng menuconfig
yann@276
   343
yann@1580
   344
yann@168
   345
________________________
yann@168
   346
                       /
yann@168
   347
Running crosstool-NG  /
yann@168
   348
_____________________/
yann@1
   349
yann@168
   350
To build the toolchain, simply type:
yann@203
   351
  ct-ng build
yann@135
   352
yann@135
   353
This will use the above configuration to retrieve, extract and patch the
yann@135
   354
components, build, install and eventually test your newly built toolchain.
yann@1
   355
yann@1
   356
You are then free to add the toolchain /bin directory in your PATH to use
yann@1
   357
it at will.
yann@1
   358
yann@135
   359
In any case, you can get some terse help. Just type:
yann@192
   360
  ct-ng help
yann@203
   361
or:
yann@203
   362
  man 1 ct-ng
yann@135
   363
rpjday@436
   364
Stopping and restarting a build |
yann@476
   365
--------------------------------+
yann@135
   366
yann@135
   367
If you want to stop the build after a step you are debugging, you can pass the
yann@135
   368
variable STOP to make:
fr@1643
   369
  ct-ng build STOP=some_step
yann@135
   370
yann@135
   371
Conversely, if you want to restart a build at a specific step you are
yann@135
   372
debugging, you can pass the RESTART variable to make:
fr@1643
   373
  ct-ng build RESTART=some_step
yann@135
   374
yann@136
   375
Alternatively, you can call make with the name of a step to just do that step:
yann@192
   376
  ct-ng libc_headers
yann@136
   377
is equivalent to:
fr@1643
   378
  ct-ng build RESTART=libc_headers STOP=libc_headers
yann@136
   379
yann@304
   380
The shortcuts +step_name and step_name+ allow to respectively stop or restart
yann@136
   381
at that step. Thus:
fr@1643
   382
  ct-ng +libc_headers              and:    ct-ng libc_headers+
yann@136
   383
are equivalent to:
fr@1643
   384
  ct-ng build STOP=libc_headers    and:    ct-ng build RESTART=libc_headers
yann@136
   385
yann@181
   386
To obtain the list of acceptable steps, please call:
yann@544
   387
  ct-ng list-steps
yann@181
   388
yann@168
   389
Note that in order to restart a build, you'll have to say 'Y' to the config
yann@168
   390
option CT_DEBUG_CT_SAVE_STEPS, and that the previous build effectively went
yann@168
   391
that far.
yann@92
   392
yann@1025
   393
Building all toolchains at once |
yann@1025
   394
--------------------------------+
yann@92
   395
yann@1025
   396
You can build all samples; simply call:
yann@1025
   397
  ct-ng build-all
yann@40
   398
yann@335
   399
Overriding the number of // jobs |
yann@476
   400
---------------------------------+
yann@335
   401
yann@335
   402
If you want to override the number of jobs to run in // (the -j option to
yann@335
   403
make), you can either re-enter the menuconfig, or simply add it on the command
yann@335
   404
line, as such:
yann@335
   405
  ct-ng build.4
yann@335
   406
yann@335
   407
which tells crosstool-NG to override the number of // jobs to 4.
yann@335
   408
yann@335
   409
You can see the actions that support overriding the number of // jobs in
yann@335
   410
the help menu. Those are the ones with [.#] after them (eg. build[.#] or
yann@1025
   411
build-all[.#], and so on...).
yann@1025
   412
yann@1025
   413
Note on // jobs |
yann@1025
   414
----------------+
yann@1025
   415
yann@1025
   416
The crosstool-NG script 'ct-ng' is a Makefile-script. It does *not* execute
yann@1025
   417
in parallel (there is not much to gain). When speaking of // jobs, we are
yann@1025
   418
refering to the number of // jobs when making the *components*. That is, we
yann@1025
   419
speak of the number of // jobs used to build gcc, glibc, and so on...
yann@1025
   420
yann@1493
   421
Tools wrapper |
yann@1493
   422
--------------+
yann@1493
   423
yann@1493
   424
Starting with gcc-4.3 come two new dependencies: GMP and MPFR. With gcc-4.4,
yann@1493
   425
come three new ones: GMP, PPL and CLooG/ppl. These are libraries that enable
yann@1493
   426
advanced features to gcc. Additionally, some of the libraries can be used by
yann@1493
   427
binutils and gdb. Unfortunately, not all systems on which crosstool-NG runs
yann@1493
   428
have all of those libraries. And for those that do, the versions of those
yann@1493
   429
libraries may be older than the version required by gcc.
yann@1493
   430
yann@1493
   431
This is why crosstool-NG builds its own set of libraries as part of the
yann@1493
   432
toolchain.
yann@1493
   433
yann@1493
   434
The libraries are built as shared libraries, because building them as static
yann@1493
   435
libraries has some short-comings. This poses no problem at build time, as
yann@1513
   436
crosstool-NG correctly points gcc (and binutils and gdb) to the correct
yann@1493
   437
place where our own version of the libraries are installed. But it poses
yann@1493
   438
a problem when gcc et al. are run: the place where the libraries are is most
yann@1493
   439
probably not known to the host dynamic linker. Still worse, if the host system
yann@1493
   440
has its own versions, then ld.so would load the wrong library!
yann@1493
   441
yann@1493
   442
So we have to force the dynamic linker to load the correct version. We do this
yann@1493
   443
by using the LD_LIBRARY_PATH variable, that informs the dynamic linker where
yann@1493
   444
to look for shared libraries prior to searching its standard places. But we
yann@1493
   445
can't impose that burden on all the system (because it'd be a nightmare to
yann@1513
   446
configure, and because two toolchains on the same system may use different
yann@1493
   447
versions of the libraries); so we have to do it on a per-toolchain basis.
yann@1493
   448
yann@1493
   449
So we rename all binaries of the toolchain (by adding a dot '.' as their first
yann@1493
   450
character), and add a small program, the so-called "tools wrapper", that
yann@1493
   451
correctly sets LD_LIBRARY_PATH prior to running the real tool.
yann@1493
   452
yann@1493
   453
First, the wrapper was written as a POSIX-compliant shell script. That shell
yann@1493
   454
script is very simple, if not trivial, and works great. The only drawback is
yann@1493
   455
that it does not work on host systems that lack a shell, for example the
yann@1493
   456
MingW32 environment. To solve the issue, the wrapper has been re-written in C,
yann@1493
   457
and compiled at build time. This C wrapper is much more complex than the shell
yann@1493
   458
script, and although it sems to be working, it's been only lightly tested.
yann@1493
   459
Some of the expected short-comings with this C wrapper are;
yann@1493
   460
 - multi-byte file names may not be handled correctly
yann@1493
   461
 - it's really big for what it does
yann@1493
   462
yann@1493
   463
So, the default wrapper installed with your toolchain is the shell script.
yann@1493
   464
If you know that your system is missing a shell, then you shall use the C
yann@1493
   465
wrapper (and report back whether it works, or does not work, for you).
yann@1493
   466
yann@335
   467
yann@227
   468
_______________________
yann@227
   469
                      /
yann@227
   470
Using the toolchain  /
yann@227
   471
____________________/
yann@227
   472
yann@227
   473
Using the toolchain is as simple as adding the toolchain's bin directory in
yann@227
   474
your PATH, such as:
yann@227
   475
  export PATH="${PATH}:/your/toolchain/path/bin"
yann@227
   476
yann@335
   477
and then using the target tuple to tell the build systems to use your
yann@227
   478
toolchain:
yann@335
   479
  ./configure --target=your-target-tuple
yann@294
   480
or
yann@335
   481
  make CC=your-target-tuple-gcc
yann@294
   482
or
yann@335
   483
  make CROSS_COMPILE=your-target-tuple-
yann@294
   484
and so on...
yann@227
   485
yann@476
   486
It is strongly advised not to use the toolchain sys-root directory as an
yann@620
   487
install directory for your programs/packages. If you do so, you will not be
yann@476
   488
able to use your toolchain for another project. It is even strongly advised
yann@476
   489
that your toolchain is chmod-ed to read-only once successfully build, so that
yann@620
   490
you don't go polluting your toolchain with your programs/packages' files.
yann@476
   491
yann@476
   492
Thus, when you build a program/package, install it in a separate directory,
yann@476
   493
eg. /your/root. This directory is the /image/ of what would be in the root file
yann@620
   494
system of your target, and will contain all that your programs/packages have
yann@476
   495
installed.
yann@476
   496
Yann@1405
   497
The 'populate' script |
Yann@1405
   498
----------------------+
Yann@1405
   499
yann@227
   500
When your root directory is ready, it is still missing some important bits: the
yann@227
   501
toolchain's libraries. To populate your root directory with those libs, just
yann@227
   502
run:
yann@335
   503
  your-target-tuple-populate -s /your/root -d /your/root-populated
yann@227
   504
yann@227
   505
This will copy /your/root into /your/root-populated, and put the needed and only
yann@227
   506
the needed libraries there. Thus you don't polute /your/root with any cruft that
yann@227
   507
would no longer be needed should you have to remove stuff. /your/root always
yann@227
   508
contains only those things you install in it.
yann@227
   509
yann@227
   510
You can then use /your/root-populated to build up your file system image, a
yann@227
   511
tarball, or to NFS-mount it from your target, or whatever you need.
yann@227
   512
Yann@1405
   513
The populate script accepts the following options:
yann@294
   514
Yann@1405
   515
 -s src_dir
Yann@1405
   516
    Use 'src_dir' as the un-populated root directory.
yann@294
   517
Yann@1405
   518
 -d dst_dir
Yann@1405
   519
    Put the populated root directory in 'dst_dir'.
Yann@1405
   520
Yann@1405
   521
 -l lib1 [...]
Yann@1405
   522
    Always add specified libraries.
Yann@1405
   523
Yann@1405
   524
 -L file
Yann@1405
   525
    Always add libraries listed in 'file'.
yann@294
   526
yann@294
   527
 -f
Yann@1405
   528
    Remove 'dst_dir' if it previously existed; continue even if any library
Yann@1405
   529
    specified with -l or -L is missing.
yann@294
   530
yann@294
   531
 -v
yann@294
   532
    Be verbose, and tell what's going on (you can see exactly where libs are
yann@294
   533
    coming from).
yann@294
   534
yann@294
   535
 -h
Yann@1405
   536
    Print the help.
Yann@1405
   537
Yann@1405
   538
See 'your-target-tuple-populate -h' for more information on the options.
yann@294
   539
Yann@1406
   540
Here is how populate works:
Yann@1406
   541
Yann@1406
   542
  1) performs some sanity checks:
Yann@1406
   543
     - src_dir and dst_dir are specified
Yann@1406
   544
     - src_dir exists
Yann@1406
   545
     - unless forced, dst_dir does not exist
Yann@1406
   546
     - src_dir != dst_dir
Yann@1406
   547
Yann@1406
   548
  2) copy src_dir to dst_dir
Yann@1406
   549
Yann@1406
   550
  3) add forced libraries to dst_dir
Yann@1406
   551
     - build the list from -l and -L options
Yann@1406
   552
     - get forced libraries from the sysroot (see below for heuristics)
Yann@1406
   553
       - abort on the first missing library, unless -f is specified
Yann@1406
   554
Yann@1406
   555
  4) add all missing libraries to dst_dir
Yann@1406
   556
     - scan dst_dir for every ELF files that are 'executable' or
Yann@1406
   557
       'shared object'
Yann@1406
   558
     - list the "NEEDED Shared library" fields
Yann@1406
   559
       - check if the library is already in dst_dir/lib or dst_dir/usr/lib
Yann@1406
   560
       - if not, get the library from the sysroot
Yann@1406
   561
         - if it's in sysroot/lib, copy it to dst_dir/lib
Yann@1406
   562
         - if it's in sysroot/usr/lib, copy it to dst_dir/usr/lib
Yann@1406
   563
         - in both cases, use the SONAME of the library to create the file
Yann@1406
   564
           in dst_dir
Yann@1406
   565
         - if it was not found in the sysroot, this is an error.
Yann@1406
   566
yann@1580
   567
yann@40
   568
___________________
yann@40
   569
                  /
yann@40
   570
Toolchain types  /
yann@40
   571
________________/
yann@40
   572
yann@40
   573
There are four kinds of toolchains you could encounter.
yann@40
   574
yann@40
   575
First off, you must understand the following: when it comes to compilers there
yann@40
   576
are up to four machines involved:
yann@40
   577
  1) the machine configuring the toolchain components: the config machine
yann@40
   578
  2) the machine building the toolchain components:    the build machine
yann@40
   579
  3) the machine running the toolchain:                the host machine
yann@203
   580
  4) the machine the toolchain is generating code for: the target machine
yann@40
   581
yann@40
   582
We can most of the time assume that the config machine and the build machine
yann@40
   583
are the same. Most of the time, this will be true. The only time it isn't
yann@40
   584
is if you're using distributed compilation (such as distcc). Let's forget
yann@40
   585
this for the sake of simplicity.
yann@40
   586
yann@40
   587
So we're left with three machines:
yann@40
   588
 - build
yann@40
   589
 - host
yann@40
   590
 - target
yann@40
   591
yann@40
   592
Any toolchain will involve those three machines. You can be as pretty sure of
yann@40
   593
this as "2 and 2 are 4". Here is how they come into play:
yann@40
   594
yann@40
   595
1) build == host == target
yann@40
   596
    This is a plain native toolchain, targetting the exact same machine as the
yann@40
   597
    one it is built on, and running again on this exact same machine. You have
yann@40
   598
    to build such a toolchain when you want to use an updated component, such
yann@40
   599
    as a newer gcc for example.
yann@197
   600
    crosstool-NG calls it "native".
yann@40
   601
yann@40
   602
2) build == host != target
yann@40
   603
    This is a classic cross-toolchain, which is expected to be run on the same
yann@40
   604
    machine it is compiled on, and generate code to run on a second machine,
yann@40
   605
    the target.
yann@197
   606
    crosstool-NG calls it "cross".
yann@40
   607
yann@40
   608
3) build != host == target
yann@40
   609
    Such a toolchain is also a native toolchain, as it targets the same machine
yann@40
   610
    as it runs on. But it is build on another machine. You want such a
yann@40
   611
    toolchain when porting to a new architecture, or if the build machine is
yann@40
   612
    much faster than the host machine.
yann@197
   613
    crosstool-NG calls it "cross-native".
yann@40
   614
yann@40
   615
4) build != host != target
yann@92
   616
    This one is called a canadian-toolchain (*), and is tricky. The three
yann@40
   617
    machines in play are different. You might want such a toolchain if you
yann@40
   618
    have a fast build machine, but the users will use it on another machine,
yann@40
   619
    and will produce code to run on a third machine.
yann@197
   620
    crosstool-NG calls it "canadian".
yann@40
   621
yann@197
   622
crosstool-NG can build all these kinds of toolchains (or is aiming at it,
yann@197
   623
anyway!)
yann@40
   624
yann@40
   625
(*) The term Canadian Cross came about because at the time that these issues
yann@40
   626
    were all being hashed out, Canada had three national political parties.
yann@40
   627
    http://en.wikipedia.org/wiki/Cross_compiler
yann@40
   628
yann@1551
   629
yann@1575
   630
________________
yann@1575
   631
               /
yann@1575
   632
Contributing  /
yann@1575
   633
_____________/
yann@1575
   634
yann@1575
   635
Sending a bug report |
yann@1575
   636
---------------------+
yann@1575
   637
yann@1575
   638
If you need to send a bug report, please send a mail with subject
yann@1575
   639
prefixed with "[CT_NG]" with to following destinations:
yann@1575
   640
    TO: yann.morin.1998 (at) anciens.enib.fr
yann@1575
   641
    CC: crossgcc (at) sourceware.org
yann@1575
   642
yann@1575
   643
Sending patches |
yann@1575
   644
----------------+
yann@1575
   645
yann@1575
   646
If you want to enhance crosstool-NG, there's a to-do list in the TODO file.
yann@1575
   647
yann@1575
   648
Patches should come with the appropriate SoB line. A SoB line is typically
yann@1575
   649
something like:
yann@1575
   650
   Signed-off-by: John DOE <john.doe@somewhere.net>
yann@1575
   651
yann@1575
   652
The SoB line is clearly described in Documentation/SubmittingPatches , section
yann@1575
   653
12, of your favourite Linux kernel source tree.
yann@1575
   654
yann@1575
   655
Then you'll need to correctly configure Mercurial. There are two extensions
yann@1575
   656
that you may find usefull:
yann@1575
   657
  - mq        : http://mercurial.selenic.com/wiki/MqExtension
yann@1575
   658
  - patchbomb : http://mercurial.selenic.com/wiki/PatchbombExtension
yann@1575
   659
yann@1575
   660
Commit messages should look like (without leading pipes):
yann@1575
   661
 |component: short, one-line description
yann@1575
   662
 |
yann@1575
   663
 |optional longer description
yann@1575
   664
 |on multiple lines if needed
yann@1575
   665
yann@1575
   666
Here is an example commit message (see revision a53a5e1d61db):
yann@1575
   667
 |comp-libs/cloog: fix building
yann@1575
   668
 |
yann@1575
   669
 |For CLooG/PPL 0.15.3, the directory name was simply cloog-ppl.
yann@1575
   670
 |For any later versions, the directory name does have the version, such as
yann@1575
   671
 |cloog-ppl-0.15.4.
yann@1575
   672
yann@1575
   673
Here's a typical hacking session:
yann@1575
   674
  hg clone http://ymorin.is-a-geek.org/hg/crosstool-ng crosstool-ng
yann@1575
   675
  cd crosstool-ng
yann@1575
   676
  hg qinit
yann@1575
   677
  hg qnew -D -U -e my_first_patch
yann@1575
   678
  *edit patch description*
yann@1575
   679
  *hack* *hack* *check* *fails* *hack* *hack* *check* *works*
yann@1575
   680
  hg qref -D -e
yann@1575
   681
  *edit patch description, serving as commit message*
yann@1575
   682
  hg qnew -D -U -e my_second_patch
yann@1575
   683
  *edit patch description*
yann@1575
   684
  *hack* *hack* *check* *fails* *hack* *hack* *check* *works*
yann@1575
   685
  hg qref -D -e
yann@1575
   686
  *edit patch description, serving as commit message*
yann@1575
   687
  hg email --outgoing --intro   \
yann@1575
   688
           --from '"Your Full NAME" <your.email (at) your.domain>'   \
yann@1575
   689
           --to '"Yann E. MORIN" <yann.morin.1998 (at) anciens.enib.fr>'    \
yann@1575
   690
           --cc 'crossgcc (at) sourceware.org'
yann@1575
   691
  *edit introductory message*
yann@1575
   692
  *wait for feedback*
yann@1575
   693
  *re-send if no answer for a few days*
yann@1575
   694
yann@1575
   695
Note: replace '(at)' above with a plain '@'.
yann@1575
   696
yann@1575
   697
yann@1
   698
_____________
yann@1
   699
            /
yann@1
   700
Internals  /
yann@1
   701
__________/
yann@1
   702
yann@92
   703
Internally, crosstool-NG is script-based. To ease usage, the frontend is
yann@92
   704
Makefile-based.
yann@92
   705
yann@92
   706
Makefile front-end |
yann@476
   707
-------------------+
yann@92
   708
yann@203
   709
The entry point to crosstool-NG is the Makefile script "ct-ng". Calling this
yann@203
   710
script with an action will act exactly as if the Makefile was in the current
yann@203
   711
working directory and make was called with the action as rule. Thus:
yann@203
   712
  ct-ng menuconfig
yann@294
   713
yann@203
   714
is equivalent to having the Makefile in CWD, and calling:
yann@203
   715
  make menuconfig
yann@203
   716
yann@203
   717
Having ct-ng as it is avoids copying the Makefile everywhere, and acts as a
yann@203
   718
traditional command.
yann@203
   719
yann@203
   720
ct-ng loads sub- Makefiles from the library directory $(CT_LIB_DIR), as set up
yann@203
   721
at configuration time with ./configure.
yann@203
   722
yann@437
   723
ct-ng also searches for config files, sub-tools, samples, scripts and patches in
yann@203
   724
that library directory.
yann@92
   725
yann@294
   726
Because of a stupid make behavior/bug I was unable to track down, implicit make
yann@294
   727
rules are disabled: installing with --local would triger those rules, and mconf
yann@294
   728
was unbuildable.
yann@294
   729
yann@182
   730
Kconfig parser |
yann@476
   731
---------------+
yann@92
   732
yann@965
   733
The kconfig language is a hacked version, vampirised from the Linux kernel
yann@965
   734
(http://www.kernel.org/), and (heavily) adapted to my needs.
yann@92
   735
yann@1040
   736
The list of the most notable changes (at least the ones I remember) follows:
yann@1040
   737
- the CONFIG_ prefix has been replaced with CT_
yann@1040
   738
- a leading | in prompts is skipped, and subsequent leading spaces are not
yann@1040
   739
  trimmed
yann@1040
   740
- otherwise leading spaces are silently trimmed
yann@1040
   741
yann@203
   742
The kconfig parsers (conf and mconf) are not installed pre-built, but as
yann@203
   743
source files. Thus you can have the directory where crosstool-NG is installed,
yann@203
   744
exported (via NFS or whatever) and have clients with different architectures
yann@203
   745
use the same crosstool-NG installation, and most notably, the same set of
yann@203
   746
patches.
yann@203
   747
yann@381
   748
Architecture-specific |
yann@476
   749
----------------------+
yann@381
   750
yann@628
   751
Note: this chapter is not really well written, and might thus be a little bit
yann@628
   752
complex to understand. To get a better grasp of what an architecture is, the
yann@628
   753
reader is kindly encouraged to look at the "arch/" sub-directory, and to the
yann@628
   754
existing architectures to see how things are laid out.
yann@628
   755
yann@381
   756
An architecture is defined by:
yann@381
   757
yann@381
   758
 - a human-readable name, in lower case letters, with numbers as appropriate.
yann@628
   759
   The underscore is allowed; space and special characters are not.
yann@628
   760
     Eg.: arm, x86_64
yann@903
   761
 - a file in "config/arch/", named after the architecture's name, and suffixed
yann@903
   762
   with ".in".
yann@903
   763
     Eg.: config/arch/arm.in
yann@903
   764
 - a file in "scripts/build/arch/", named after the architecture's name, and
yann@903
   765
   suffixed with ".sh".
yann@903
   766
     Eg.: scripts/build/arch/arm.sh
yann@628
   767
yann@903
   768
The architecture's ".in" file API:
yann@628
   769
 > the config option "ARCH_%arch%" (where %arch% is to be replaced with the
yann@628
   770
   actual architecture name).
yann@628
   771
   That config option must have *neither* a type, *nor* a prompt! Also, it can
yann@628
   772
   *not* depend on any other config option (EXPERIMENTAL is managed as above).
yann@628
   773
     Eg.:
yann@628
   774
       config ARCH_arm
yann@630
   775
   + mandatory:
yann@702
   776
       defines a (terse) help entry for this architecture:
yann@630
   777
       Eg.:
yann@630
   778
         config ARCH_arm
yann@630
   779
           help
yann@630
   780
             The ARM architecture.
yann@628
   781
   + optional:
yann@628
   782
       selects adequate associated config options.
yann@1038
   783
       Note: 64-bit architectures *shall* select ARCH_64
yann@628
   784
       Eg.:
yann@628
   785
         config ARCH_arm
yann@628
   786
           select ARCH_SUPPORTS_BOTH_ENDIAN
yann@628
   787
           select ARCH_DEFAULT_LE
yann@630
   788
           help
yann@630
   789
             The ARM architecture.
yann@1038
   790
       Eg.:
yann@1038
   791
         config ARCH_x86_64
yann@1038
   792
            select ARCH_64
yann@1038
   793
            help
yann@1038
   794
              The x86_64 architecture.
yann@628
   795
yann@628
   796
 > other target-specific options, at your discretion. Note however that to
yann@628
   797
   avoid name-clashing, such options shall be prefixed with "ARCH_%arch%",
yann@628
   798
   where %arch% is again replaced by the actual architecture name.
yann@628
   799
   (Note: due to historical reasons, and lack of time to clean up the code,
yann@628
   800
    I may have left some config options that do not completely conform to
yann@628
   801
    this, as the architecture name was written all upper case. However, the
yann@628
   802
    prefix is unique among architectures, and does not cause harm).
yann@381
   803
yann@903
   804
The architecture's ".sh" file API:
yann@965
   805
 > the function "CT_DoArchTupleValues"
yann@381
   806
   + parameters: none
yann@381
   807
   + environment:
yann@901
   808
     - all variables from the ".config" file,
yann@901
   809
     - the two variables "target_endian_eb" and "target_endian_el" which are
yann@901
   810
       the endianness suffixes
yann@381
   811
   + return value: 0 upon success, !0 upon failure
yann@381
   812
   + provides:
yann@391
   813
     - mandatory
yann@383
   814
     - the environment variable CT_TARGET_ARCH
yann@389
   815
     - contains:
yann@389
   816
       the architecture part of the target tuple.
yann@389
   817
       Eg.: "armeb" for big endian ARM
yann@389
   818
            "i386" for an i386
yann@389
   819
   + provides:
yann@391
   820
     - optional
yann@389
   821
     - the environment variable CT_TARGET_SYS
yann@456
   822
     - contains:
yann@383
   823
       the sytem part of the target tuple.
yann@383
   824
       Eg.: "gnu" for glibc on most architectures
yann@383
   825
            "gnueabi" for glibc on an ARM EABI
yann@383
   826
     - defaults to:
yann@383
   827
       - for glibc-based toolchain: "gnu"
yann@383
   828
       - for uClibc-based toolchain: "uclibc"
yann@383
   829
   + provides:
yann@383
   830
     - optional
yann@391
   831
     - the environment variable CT_KERNEL_ARCH
yann@383
   832
     - contains:
yann@391
   833
       the architecture name as understandable by the Linux kernel build
yann@391
   834
       system.
yann@391
   835
       Eg.: "arm" for an ARM
yann@391
   836
            "powerpc" for a PowerPC
yann@391
   837
            "i386" for an x86
yann@383
   838
     - defaults to:
yann@391
   839
       ${CT_ARCH}
yann@391
   840
   + provides:
yann@391
   841
     - optional
yann@767
   842
     - the environment variables to configure the cross-gcc (defaults)
yann@767
   843
       - CT_ARCH_WITH_ARCH    : the gcc ./configure switch to select architecture level         ( "--with-arch=${CT_ARCH_ARCH}"   )
yann@767
   844
       - CT_ARCH_WITH_ABI     : the gcc ./configure switch to select ABI level                  ( "--with-abi=${CT_ARCH_ABI}"     )
yann@767
   845
       - CT_ARCH_WITH_CPU     : the gcc ./configure switch to select CPU instruction set        ( "--with-cpu=${CT_ARCH_CPU}"     )
yann@767
   846
       - CT_ARCH_WITH_TUNE    : the gcc ./configure switch to select scheduling                 ( "--with-tune=${CT_ARCH_TUNE}"   )
yann@767
   847
       - CT_ARCH_WITH_FPU     : the gcc ./configure switch to select FPU type                   ( "--with-fpu=${CT_ARCH_FPU}"     )
yann@767
   848
       - CT_ARCH_WITH_FLOAT   : the gcc ./configure switch to select floating point arithmetics ( "--with-float=soft" or /empty/  )
yann@391
   849
   + provides:
yann@391
   850
     - optional
yann@767
   851
     - the environment variables to pass to the cross-gcc to build target binaries (defaults)
yann@391
   852
       - CT_ARCH_ARCH_CFLAG   : the gcc switch to select architecture level                     ( "-march=${CT_ARCH_ARCH}"            )
yann@456
   853
       - CT_ARCH_ABI_CFLAG    : the gcc switch to select ABI level                              ( "-mabi=${CT_ARCH_ABI}"              )
yann@391
   854
       - CT_ARCH_CPU_CFLAG    : the gcc switch to select CPU instruction set                    ( "-mcpu=${CT_ARCH_CPU}"              )
yann@391
   855
       - CT_ARCH_TUNE_CFLAG   : the gcc switch to select scheduling                             ( "-mtune=${CT_ARCH_TUNE}"            )
yann@391
   856
       - CT_ARCH_FPU_CFLAG    : the gcc switch to select FPU type                               ( "-mfpu=${CT_ARCH_FPU}"              )
yann@391
   857
       - CT_ARCH_FLOAT_CFLAG  : the gcc switch to choose floating point arithmetics             ( "-msoft-float" or /empty/           )
yann@391
   858
       - CT_ARCH_ENDIAN_CFLAG : the gcc switch to choose big or little endian                   ( "-mbig-endian" or "-mlittle-endian" )
yann@391
   859
     - default to:
yann@391
   860
       see above.
yann@767
   861
   + provides:
yann@767
   862
     - optional
yann@767
   863
     - the environement variables to configure the core and final compiler, specific to this architecture:
yann@767
   864
       - CT_ARCH_CC_CORE_EXTRA_CONFIG   : additional, architecture specific core gcc ./configure flags
yann@767
   865
       - CT_ARCH_CC_EXTRA_CONFIG        : additional, architecture specific final gcc ./configure flags
yann@767
   866
     - default to:
yann@767
   867
       - all empty
yann@767
   868
   + provides:
yann@767
   869
     - optional
yann@767
   870
     - the architecture-specific CFLAGS and LDFLAGS:
yann@767
   871
       - CT_ARCH_TARGET_CLFAGS
yann@767
   872
       - CT_ARCH_TARGET_LDFLAGS
yann@767
   873
     - default to:
yann@767
   874
       - all empty
yann@628
   875
yann@903
   876
You can have a look at "config/arch/arm.in" and "scripts/build/arch/arm.sh" for
yann@903
   877
a quite complete example of what an actual architecture description looks like.
yann@901
   878
yann@890
   879
Kernel specific |
yann@890
   880
----------------+
yann@890
   881
yann@890
   882
A kernel is defined by:
yann@890
   883
yann@890
   884
 - a human-readable name, in lower case letters, with numbers as appropriate.
yann@890
   885
   The underscore is allowed; space and special characters are not (although
yann@890
   886
   they are internally replaced with underscores.
yann@890
   887
     Eg.: linux, bare-metal
yann@890
   888
 - a file in "config/kernel/", named after the kernel name, and suffixed with
yann@890
   889
   ".in".
yann@890
   890
     Eg.: config/kernel/linux.in, config/kernel/bare-metal.in
yann@901
   891
 - a file in "scripts/build/kernel/", named after the kernel name, and suffixed
yann@901
   892
   with ".sh".
yann@901
   893
     Eg.: scripts/build/kernel/linux.sh, scripts/build/kernel/bare-metal.sh
yann@890
   894
yann@890
   895
The kernel's ".in" file must contain:
yann@890
   896
 > an optional lines containing exactly "# EXPERIMENTAL", starting on the
yann@890
   897
   first column, and without any following space or other character.
yann@890
   898
   If this line is present, then this kernel is considered EXPERIMENTAL,
yann@890
   899
   and correct dependency on EXPERIMENTAL will be set.
yann@901
   900
yann@890
   901
 > the config option "KERNEL_%kernel_name%" (where %kernel_name% is to be
yann@890
   902
   replaced with the actual kernel name, with all special characters and
yann@890
   903
   spaces replaced by underscores).
yann@890
   904
   That config option must have *neither* a type, *nor* a prompt! Also, it can
yann@890
   905
   *not* depends on EXPERIMENTAL.
yann@890
   906
     Eg.: KERNEL_linux, KERNEL_bare_metal
yann@890
   907
   + mandatory:
yann@890
   908
       defines a (terse) help entry for this kernel.
yann@890
   909
       Eg.:
yann@890
   910
         config KERNEL_bare_metal
yann@890
   911
           help
yann@890
   912
             Build a compiler for use without any kernel.
yann@890
   913
   + optional:
yann@890
   914
       selects adequate associated config options.
yann@890
   915
       Eg.:
yann@890
   916
         config KERNEL_bare_metal
yann@890
   917
           select BARE_METAL
yann@890
   918
           help
yann@890
   919
             Build a compiler for use without any kernel.
yann@890
   920
yann@890
   921
 > other kernel specific options, at your discretion. Note however that, to
yann@890
   922
   avoid name-clashing, such options should be prefixed with
yann@890
   923
   "KERNEL_%kernel_name%", where %kernel_name% is again tp be replaced with
yann@890
   924
   the actual kernel name.
yann@890
   925
   (Note: due to historical reasons, and lack of time to clean up the code,
yann@890
   926
    I may have left some config options that do not completely conform to
yann@890
   927
    this, as the kernel name was written all upper case. However, the prefix
yann@890
   928
    is unique among kernels, and does not cause harm).
yann@890
   929
yann@901
   930
The kernel's ".sh" file API:
yann@901
   931
 > is a bash script fragment
yann@901
   932
yann@965
   933
 > defines the function CT_DoKernelTupleValues
yann@965
   934
   + see the architecture's CT_DoArchTupleValues, except for:
yann@965
   935
   + set the environment variable CT_TARGET_KERNEL, the kernel part of the
yann@965
   936
     target tuple
yann@965
   937
   + return value: ignored
yann@965
   938
yann@901
   939
 > defines the function "do_kernel_get":
yann@901
   940
   + parameters: none
yann@901
   941
   + environment:
yann@901
   942
      - all variables from the ".config" file.
yann@901
   943
   + return value: 0 for success, !0 for failure.
yann@901
   944
   + behavior: download the kernel's sources, and store the tarball into
yann@901
   945
     "${CT_TARBALLS_DIR}". To this end, a functions is available, that
yann@901
   946
     abstracts downloading tarballs:
yann@901
   947
     - CT_DoGet <tarball_base_name> <URL1 [URL...]>
yann@901
   948
       Eg.: CT_DoGet linux-2.6.26.5 ftp://ftp.kernel.org/pub/linux/kernel/v2.6
yann@901
   949
     Note: retrieving sources from svn, cvs, git and the likes is not supported
yann@901
   950
     by CT_DoGet. You'll have to do this by hand, as it is done for eglibc in
yann@901
   951
     "scripts/build/libc/eglibc.sh"
yann@901
   952
yann@901
   953
 > defines the function "do_kernel_extract":
yann@901
   954
   + parameters: none
yann@901
   955
   + environment:
yann@901
   956
      - all variables from the ".config" file,
yann@901
   957
   + return value: 0 for success, !0 for failure.
yann@901
   958
   + behavior: extract the kernel's tarball into "${CT_SRC_DIR}", and apply
yann@901
   959
     required patches. To this end, a function is available, that abstracts
yann@901
   960
     extracting tarballs:
yann@901
   961
     - CT_ExtractAndPatch <tarball_base_name>
yann@901
   962
       Eg.: CT_ExtractAndPatch linux-2.6.26.5
yann@901
   963
yann@901
   964
 > defines the function "do_kernel_headers":
yann@901
   965
   + parameters: none
yann@901
   966
   + environment:
yann@901
   967
      - all variables from the ".config" file,
yann@901
   968
   + return value: 0 for success, !0 for failure.
yann@901
   969
   + behavior: install the kernel headers (if any) in "${CT_SYSROOT_DIR}/usr/include"
yann@901
   970
yann@901
   971
 > defines any kernel-specific helper functions
yann@901
   972
   These functions, if any, must be prefixed with "do_kernel_%CT_KERNEL%_",
yann@901
   973
   where '%CT_KERNEL%' is to be replaced with the actual kernel name, to avoid
yann@901
   974
   any name-clashing.
yann@901
   975
yann@901
   976
You can have a look at "config/kernel/linux.in" and "scripts/build/kernel/linux.sh"
yann@903
   977
as an example of what a complex kernel description looks like.
yann@901
   978
yann@620
   979
Adding a new version of a component |
yann@476
   980
------------------------------------+
yann@476
   981
yann@476
   982
When a new component, such as the Linux kernel, gcc or any other is released,
yann@476
   983
adding the new version to crosstool-NG is quite easy. There is a script that
yann@476
   984
will do all that for you:
yann@1095
   985
  scripts/addToolVersion.sh
yann@476
   986
yann@476
   987
Run it with no option to get some help.
yann@381
   988
yann@203
   989
Build scripts |
yann@476
   990
--------------+
yann@203
   991
yann@203
   992
To Be Written later...