docs/overview.txt
author Arnaud Lacombe <lacombar@gmail.com>
Thu Aug 05 17:59:51 2010 +0200 (2010-08-05)
changeset 2069 366bd2b22675
parent 1937 384b7f8fc780
permissions -rw-r--r--
complibs/mpc: fix MPC 0.8.1 build with MPFR 3.0.0

This is the change introduced by revision 734 of MPC repository.

Author: Paul Zimmermann <Paul.Zimmermann@loria.fr>
Revision log: [acos.c] fixed problem with GMP_RNDA (should be MPFR_RNDA, and code was wrong)

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