docs/3 - Configuring a toolchain.txt
author "Antony N. Pavlov" <antony@niisi.msk.ru>
Sun Jul 17 16:54:50 2011 +0200 (2011-07-17)
changeset 2563 e17f35b05539
parent 2076 b58109b7b321
child 2564 5d4e91c0343e
permissions -rw-r--r--
misc: fix typos

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