1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/3 - Configuring a toolchain.txt Sat Aug 14 16:37:11 2010 +0200
1.3 @@ -0,0 +1,133 @@
1.4 +File.........: 3 - Configuring a toolchain.txt
1.5 +Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
1.6 +License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
1.7 +
1.8 +
1.9 +
1.10 +Configuring crosstool-NG /
1.11 +_________________________/
1.12 +
1.13 +
1.14 +crosstool-NG is configured with a configurator presenting a menu-stuctured set
1.15 +of options. These options let you specify the way you want your toolchain
1.16 +built, where you want it installed, what architecture and specific processor it
1.17 +will support, the version of the components you want to use, etc... The
1.18 +value for those options are then stored in a configuration file.
1.19 +
1.20 +The configurator works the same way you configure your Linux kernel. It is
1.21 +assumed you now how to handle this.
1.22 +
1.23 +To enter the menu, type:
1.24 + ct-ng menuconfig
1.25 +
1.26 +Almost every config item has a help entry. Read them carefully.
1.27 +
1.28 +String and number options can refer to environment variables. In such a case,
1.29 +you must use the shell syntax: ${VAR}. You shall neither single- nor double-
1.30 +quote the string/number options.
1.31 +
1.32 +There are three environment variables that are computed by crosstool-NG, and
1.33 +that you can use:
1.34 +
1.35 +CT_TARGET:
1.36 + It represents the target tuple you are building for. You can use it for
1.37 + example in the installation/prefix directory, such as:
1.38 + /opt/x-tools/${CT_TARGET}
1.39 +
1.40 +CT_TOP_DIR:
1.41 + The top directory where crosstool-NG is running. You shouldn't need it in
1.42 + most cases. There is one case where you may need it: if you have local
1.43 + patches and you store them in your running directory, you can refer to them
1.44 + by using CT_TOP_DIR, such as:
1.45 + ${CT_TOP_DIR}/patches.myproject
1.46 +
1.47 +CT_VERSION:
1.48 + The version of crosstool-NG you are using. Not much use for you, but it's
1.49 + there if you need it.
1.50 +
1.51 +
1.52 +Interesting config options |
1.53 +---------------------------+
1.54 +
1.55 +CT_LOCAL_TARBALLS_DIR:
1.56 + If you already have some tarballs in a direcotry, enter it here. That will
1.57 + speed up the retrieving phase, where crosstool-NG would otherwise download
1.58 + those tarballs.
1.59 +
1.60 +CT_PREFIX_DIR:
1.61 + This is where the toolchain will be installed in (and for now, where it
1.62 + will run from). Common use is to add the target tuple in the directory
1.63 + path, such as (see above):
1.64 + /opt/x-tools/${CT_TARGET}
1.65 +
1.66 +CT_TARGET_VENDOR:
1.67 + An identifier for your toolchain, will take place in the vendor part of the
1.68 + target tuple. It shall *not* contain spaces or dashes. Usually, keep it
1.69 + to a one-word string, or use underscores to separate words if you need.
1.70 + Avoid dots, commas, and special characters.
1.71 +
1.72 +CT_TARGET_ALIAS:
1.73 + An alias for the toolchian. It will be used as a prefix to the toolchain
1.74 + tools. For example, you will have ${CT_TARGET_ALIAS}-gcc
1.75 +
1.76 +Also, if you think you don't see enough versions, you can try to enable one of
1.77 +those:
1.78 +
1.79 +CT_OBSOLETE:
1.80 + Show obsolete versions or tools. Most of the time, you don't want to base
1.81 + your toolchain on too old a version (of gcc, for example). But at times, it
1.82 + can come handy to use such an old version for regression tests. Those old
1.83 + versions are hidden behind CT_OBSOLETE. Those versions (or features) are so
1.84 + marked because maintaining support for those in crosstool-NG would be too
1.85 + costly, time-wise, and time is dear.
1.86 +
1.87 +CT_EXPERIMENTAL:
1.88 + Show experimental versions or tools. Again, you might not want to base your
1.89 + toolchain on too recent tools (eg. gcc) for production. But if you need a
1.90 + feature present only in a recent version, or a new tool, you can find them
1.91 + hidden behind CT_EXPERIMENTAL. Those versions (or features) did not (yet)
1.92 + receive thorough testing in crosstool-NG, and/or are not mature enough to
1.93 + be blindly trusted.
1.94 +
1.95 +
1.96 +Re-building an existing toolchain |
1.97 +----------------------------------+
1.98 +
1.99 +If you have an existing toolchain, you can re-use the options used to build it
1.100 +to create a new toolchain. That needs a very little bit of effort on your side
1.101 +but is quite easy. The options to build a toolchain are saved with the
1.102 +toolchain, and you can retrieve this configuration by running:
1.103 + ${CT_TARGET}-ct-ng.config
1.104 +
1.105 +An alternate method is to extract the configuration from a build.log file.
1.106 +This will be necessary if your toolchain was build with crosstool-NG prior
1.107 +to 1.4.0, but can be used with build.log files from any version:
1.108 + ct-ng extractconfig <build.log >.config
1.109 +
1.110 +Or, if your build.log file is compressed (most probably!):
1.111 + bzcat build.log.bz2 |ct-ng extractconfig >.config
1.112 +
1.113 +The above commands will dump the configuration to stdout, so to rebuild a
1.114 +toolchain with this configuration, just redirect the output to the
1.115 +.config file:
1.116 + ${CT_TARGET}-ct-ng.config >.config
1.117 + ct-ng oldconfig
1.118 +
1.119 +Then, you can review and change the configuration by running:
1.120 + ct-ng menuconfig
1.121 +
1.122 +
1.123 +Using as a backend for a build-system |
1.124 +--------------------------------------+
1.125 +
1.126 +Crosstool-NG can be used as a backend for an automated build-system. In this
1.127 +case, some components that are expected to run on the target (eg. the native
1.128 +gdb, ltrace, DUMA...) are not available in the menuconfig, and they are not
1.129 +build either, as it is considered the responsibility of the build-system to
1.130 +build its own versions of those tools.
1.131 +
1.132 +If you want to use crosstool-NG as a backend to generate your toolchains for
1.133 +your build-system, you have to set and export this environment variable:
1.134 + CT_IS_A_BACKEND=y
1.135 +
1.136 +(case is not sensitive, you can say Y).