docs/3 - Configuring a toolchain.txt
author "Yann E. MORIN" <yann.morin.1998@free.fr>
Sun May 11 23:55:16 2014 +0200 (2014-05-11)
changeset 3321 8a753e6c5621
parent 2564 5d4e91c0343e
permissions -rw-r--r--
scripts/functions: introduce target_bits_32 and target_bits_64 variables

These variables behave the same for bitness as their counterparts do
for endianness: they are defined to the appropriate bitness.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Cody P Schafer <dev@codyps.com>
yann@2076
     1
File.........: 3 - Configuring a toolchain.txt
yann@2908
     2
Copyright....: (C) 2010 Yann E. MORIN <yann.morin.1998@free.fr>
yann@2076
     3
License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
yann@2076
     4
yann@2076
     5
yann@2076
     6
yann@2076
     7
Configuring crosstool-NG  /
yann@2076
     8
_________________________/
yann@2076
     9
yann@2076
    10
antony@2564
    11
crosstool-NG is configured with a configurator presenting a menu-structured set
yann@2076
    12
of options. These options let you specify the way you want your toolchain
yann@2076
    13
built, where you want it installed, what architecture and specific processor it
yann@2076
    14
will support, the version of the components you want to use, etc... The
yann@2076
    15
value for those options are then stored in a configuration file.
yann@2076
    16
yann@2076
    17
The configurator works the same way you configure your Linux kernel. It is
yann@2076
    18
assumed you now how to handle this.
yann@2076
    19
yann@2076
    20
To enter the menu, type:
yann@2076
    21
  ct-ng menuconfig
yann@2076
    22
yann@2076
    23
Almost every config item has a help entry. Read them carefully.
yann@2076
    24
yann@2076
    25
String and number options can refer to environment variables. In such a case,
yann@2076
    26
you must use the shell syntax: ${VAR}. You shall neither single- nor double-
yann@2076
    27
quote the string/number options.
yann@2076
    28
yann@2076
    29
There are three environment variables that are computed by crosstool-NG, and
yann@2076
    30
that you can use:
yann@2076
    31
yann@2076
    32
CT_TARGET:
yann@2076
    33
  It represents the target tuple you are building for. You can use it for
yann@2076
    34
  example in the installation/prefix directory, such as:
yann@2076
    35
    /opt/x-tools/${CT_TARGET}
yann@2076
    36
yann@2076
    37
CT_TOP_DIR:
yann@2076
    38
  The top directory where crosstool-NG is running. You shouldn't need it in
yann@2076
    39
  most cases. There is one case where you may need it: if you have local
yann@2076
    40
  patches and you store them in your running directory, you can refer to them
yann@2076
    41
  by using CT_TOP_DIR, such as:
yann@2076
    42
    ${CT_TOP_DIR}/patches.myproject
yann@2076
    43
yann@2076
    44
CT_VERSION:
yann@2076
    45
  The version of crosstool-NG you are using. Not much use for you, but it's
yann@2076
    46
  there if you need it.
yann@2076
    47
yann@2076
    48
yann@2076
    49
Interesting config options |
yann@2076
    50
---------------------------+
yann@2076
    51
yann@2076
    52
CT_LOCAL_TARBALLS_DIR:
antony@2564
    53
  If you already have some tarballs in a directory, enter it here. That will
yann@2076
    54
  speed up the retrieving phase, where crosstool-NG would otherwise download
yann@2076
    55
  those tarballs.
yann@2076
    56
yann@2076
    57
CT_PREFIX_DIR:
yann@2076
    58
  This is where the toolchain will be installed in (and for now, where it
yann@2076
    59
  will run from). Common use is to add the target tuple in the directory
yann@2076
    60
  path, such as (see above):
yann@2076
    61
    /opt/x-tools/${CT_TARGET}
yann@2076
    62
yann@2076
    63
CT_TARGET_VENDOR:
yann@2076
    64
  An identifier for your toolchain, will take place in the vendor part of the
yann@2076
    65
  target tuple. It shall *not* contain spaces or dashes. Usually, keep it
yann@2076
    66
  to a one-word string, or use underscores to separate words if you need.
yann@2076
    67
  Avoid dots, commas, and special characters.
yann@2076
    68
yann@2076
    69
CT_TARGET_ALIAS:
antony@2564
    70
  An alias for the toolchain. It will be used as a prefix to the toolchain
yann@2076
    71
  tools. For example, you will have ${CT_TARGET_ALIAS}-gcc
yann@2076
    72
yann@2076
    73
Also, if you think you don't see enough versions, you can try to enable one of
yann@2076
    74
those:
yann@2076
    75
yann@2076
    76
CT_OBSOLETE:
yann@2076
    77
  Show obsolete versions or tools. Most of the time, you don't want to base
yann@2076
    78
  your toolchain on too old a version (of gcc, for example). But at times, it
yann@2076
    79
  can come handy to use such an old version for regression tests. Those old
yann@2076
    80
  versions are hidden behind CT_OBSOLETE. Those versions (or features) are so
yann@2076
    81
  marked because maintaining support for those in crosstool-NG would be too
yann@2076
    82
  costly, time-wise, and time is dear.
yann@2076
    83
yann@2076
    84
CT_EXPERIMENTAL:
yann@2076
    85
  Show experimental versions or tools. Again, you might not want to base your
yann@2076
    86
  toolchain on too recent tools (eg. gcc) for production. But if you need a
yann@2076
    87
  feature present only in a recent version, or a new tool, you can find them
yann@2076
    88
  hidden behind CT_EXPERIMENTAL. Those versions (or features) did not (yet)
yann@2076
    89
  receive thorough testing in crosstool-NG, and/or are not mature enough to
yann@2076
    90
  be blindly trusted.
yann@2076
    91
yann@2076
    92
yann@2076
    93
Re-building an existing toolchain |
yann@2076
    94
----------------------------------+
yann@2076
    95
yann@2076
    96
If you have an existing toolchain, you can re-use the options used to build it
yann@2076
    97
to create a new toolchain. That needs a very little bit of effort on your side
yann@2076
    98
but is quite easy. The options to build a toolchain are saved with the
yann@2076
    99
toolchain, and you can retrieve this configuration by running:
yann@2076
   100
  ${CT_TARGET}-ct-ng.config
yann@2076
   101
yann@2076
   102
An alternate method is to extract the configuration from a build.log file.
yann@2076
   103
This will be necessary if your toolchain was build with crosstool-NG prior
yann@2076
   104
to 1.4.0, but can be used with build.log files from any version:
yann@2076
   105
  ct-ng extractconfig <build.log >.config
yann@2076
   106
yann@2076
   107
Or, if your build.log file is compressed (most probably!):
yann@2076
   108
  bzcat build.log.bz2 |ct-ng extractconfig >.config
yann@2076
   109
yann@2076
   110
The above commands will dump the configuration to stdout, so to rebuild a
yann@2076
   111
toolchain with this configuration, just redirect the output to the
yann@2076
   112
.config file:
yann@2076
   113
  ${CT_TARGET}-ct-ng.config >.config
yann@2076
   114
  ct-ng oldconfig
yann@2076
   115
yann@2076
   116
Then, you can review and change the configuration by running:
yann@2076
   117
  ct-ng menuconfig
yann@2076
   118
yann@2076
   119
yann@2076
   120
Using as a backend for a build-system |
yann@2076
   121
--------------------------------------+
yann@2076
   122
yann@2076
   123
Crosstool-NG can be used as a backend for an automated build-system. In this
yann@2076
   124
case, some components that are expected to run on the target (eg. the native
yann@2076
   125
gdb, ltrace, DUMA...) are not available in the menuconfig, and they are not
yann@2076
   126
build either, as it is considered the responsibility of the build-system to
yann@2076
   127
build its own versions of those tools.
yann@2076
   128
yann@2076
   129
If you want to use crosstool-NG as a backend to generate your toolchains for
yann@2076
   130
your build-system, you have to set and export this environment variable:
yann@2076
   131
  CT_IS_A_BACKEND=y
yann@2076
   132
yann@2076
   133
(case is not sensitive, you can say Y).