diff options
Diffstat (limited to 'docs/manual/configure.txt')
| -rw-r--r-- | docs/manual/configure.txt | 277 |
1 files changed, 277 insertions, 0 deletions
diff --git a/docs/manual/configure.txt b/docs/manual/configure.txt index 2c7987dda..65e0eeb2f 100644 --- a/docs/manual/configure.txt +++ b/docs/manual/configure.txt @@ -9,6 +9,283 @@ providing details about the option. However, a number of topics require additional details that cannot easily be covered in the help text and are there covered in the following sections. +Cross-compilation toolchain +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A compilation toolchain is the set of tools that allows you to compile +code for your system. It consists of a compiler (in our case, +gcc+), +binary utils like assembler and linker (in our case, +binutils+) and a +C standard library (for example +http://www.gnu.org/software/libc/libc.html[GNU Libc], +http://www.uclibc.org/[uClibc]). + +The system installed on your development station certainly already has +a compilation toolchain that you can use to compile an application +that runs on your system. If you're using a PC, your compilation +toolchain runs on an x86 processor and generates code for an x86 +processor. Under most Linux systems, the compilation toolchain uses +the GNU libc (glibc) as the C standard library. This compilation +toolchain is called the "host compilation toolchain". The machine on +which it is running, and on which you're working, is called the "host +system" footnote:[This terminology differs from what is used by GNU +configure, where the host is the machine on which the application will +run (which is usually the same as target)]. + +The compilation toolchain is provided by your distribution, and +Buildroot has nothing to do with it (other than using it to build a +cross-compilation toolchain and other tools that are run on the +development host). + +As said above, the compilation toolchain that comes with your system +runs on and generates code for the processor in your host system. As +your embedded system has a different processor, you need a +cross-compilation toolchain - a compilation toolchain that runs on +your _host system_ but generates code for your _target system_ (and +target processor). For example, if your host system uses x86 and your +target system uses ARM, the regular compilation toolchain on your host +runs on x86 and generates code for x86, while the cross-compilation +toolchain runs on x86 and generates code for ARM. + +Buildroot provides different solutions to build, or use existing +cross-compilation toolchains: + + * The *internal toolchain backend*, called +Buildroot toolchain+ in + the configuration interface. + + * The *external toolchain backend*, called +External toolchain+ in + the configuration interface. + + * The *Crosstool-NG toolchain backend*, called +Crosstool-NG + toolchain+ in the configuration interface. + +The choice between these three solutions is done using the +Toolchain +Type+ option in the +Toolchain+ menu. Once one solution has been +chosen, a number of configuration options appear, they are detailed in +the following sections. + +Internal toolchain backend +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The _internal toolchain backend_ is the backend where Buildroot builds +by itself a cross-compilation toolchain, before building the userspace +applications and libraries for your target embedded system. + +This backend is the historical backend of Buildroot, and is limited to +the usage of the http://www.uclibc.org[uClibc C library] (i.e, the +_glibc_ and _eglibc_ C libraries are not supported by this backend, +see the _External toolchain backend_ and _Crosstool-NG toolchain +backend_ for solutions to use either _glibc_ or _eglibc_). + +Once you have selected this backend, a number of options appear. The +most important ones allow to: + + * Change the version of the Linux kernel headers used to build the + toolchain. This item deserves a few explanations. In the process of + building a cross-compilation toolchain, the C library is being + built. This library provides the interface between userspace + applications and the Linux kernel. In order to know how to "talk" + to the Linux kernel, the C library needs to have access to the + _Linux kernel headers_ (i.e, the +.h+ files from the kernel), which + define the interface between userspace and the kernel (system + calls, data structures, etc.). Since this interface is backward + compatible, the version of the Linux kernel headers used to build + your toolchain do not need to match _exactly_ the version of the + Linux kernel you intend to run on your embedded system. They only + need to have a version equal or older to the version of the Linux + kernel you intend to run. If you use kernel headers that are more + recent than the Linux kernel you run on your embedded system, then + the C library might be using interfaces that are not provided by + your Linux kernel. + + * Change the version and the configuration of the uClibc C + library. The default options are usually fine. However, if you + really need to specifically customize the configuration of your + uClibc C library, you can pass a specific configuration file + here. Or alternatively, you can run the +make uclibc-menuconfig+ + command to get access to uClibc's configuration interface. Note + that all packages in Buildroot are tested against the default + uClibc configuration bundled in Buildroot: if you deviate from this + configuration by removing features from uClibc, some packages may + no longer build. + + * Change the version of the GCC compiler and binutils. + + * Select a number of toolchain options: whether the toolchain should + have largefile support (i.e support for files larger than 2 GB on + 32 bits systems), IPv6 support, RPC support (used mainly for NFS), + wide-char support, locale support (for internationalization), C++ + support, thread support. Depending on which options you choose, the + number of userspace applications and libraries visible in Buildroot + menus will change: many applications and libraries require certain + toolchain options to be enabled. Most packages show a comment when + a certain toolchain option is required to be able to enable those + packages. + +It is worth noting that whenever one of those options is modified, +then the entire toolchain and system must be rebuilt. See +xref:full-rebuild[]. + +Advantages of this backend: + +* Well integrated with Buildroot +* Fast, only builds what's necessary + +Drawbacks of this backend: + +* Rebuilding the toolchain is needed when doing +make clean+, which + takes time. If you're trying to reduce your build time, consider + using the _External toolchain backend_. +* Limited to the _uClibc_ C library. + +External toolchain backend +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The _external toolchain backend_ allows to use existing pre-built +cross-compilation toolchains. Buildroot knows about a number of +well-known cross-compilation toolchains (from +http://www.linaro.org[Linaro] for ARM, +http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/[Sourcery +CodeBench] for ARM, x86, x86-64, PowerPC, MIPS and SuperH, +https://blackfin.uclinux.org/gf/project/toolchain[Blackfin toolchains +from ADI], http://git.xilinx.com/[Xilinx toolchains for Microblaze], +etc.) and is capable of downloading them automatically, or it can be +pointed to a custom toolchain, either available for download or +installed locally. + +Then, you have three solutions to use an external toolchain: + +* Use a predefined external toolchain profile, and let Buildroot + download, extract and install the toolchain. Buildroot already knows + about a few CodeSourcery, Linaro, Blackfin and Xilinx toolchains. + Just select the toolchain profile in +Toolchain+ from the + available ones. This is definitely the easiest solution. + +* Use a predefined external toolchain profile, but instead of having + Buildroot download and extract the toolchain, you can tell Buildroot + where your toolchain is already installed on your system. Just + select the toolchain profile in +Toolchain+ through the available + ones, unselect +Download toolchain automatically+, and fill the + +Toolchain path+ text entry with the path to your cross-compiling + toolchain. + +* Use a completely custom external toolchain. This is particularly + useful for toolchains generated using crosstool-NG. To do this, + select the +Custom toolchain+ solution in the +Toolchain+ list. You + need to fill the +Toolchain path+, +Toolchain prefix+ and +External + toolchain C library+ options. Then, you have to tell Buildroot what + your external toolchain supports. If your external toolchain uses + the 'glibc' library, you only have to tell whether your toolchain + supports C\+\+ or not and whether it has built-in RPC support. If + your external toolchain uses the 'uClibc' + library, then you have to tell Buildroot if it supports largefile, + IPv6, RPC, wide-char, locale, program invocation, threads and + C++. At the beginning of the execution, Buildroot will tell you if + the selected options do not match the toolchain configuration. + +Our external toolchain support has been tested with toolchains from +CodeSourcery and Linaro, toolchains generated by +http://crosstool-ng.org[crosstool-NG], and toolchains generated by +Buildroot itself. In general, all toolchains that support the +'sysroot' feature should work. If not, do not hesitate to contact the +developers. + +We do not support toolchains from the +http://www.denx.de/wiki/DULG/ELDK[ELDK] of Denx, for two reasons: + +* The ELDK does not contain a pure toolchain (i.e just the compiler, + binutils, the C and C++ libraries), but a toolchain that comes with + a very large set of pre-compiled libraries and programs. Therefore, + Buildroot cannot import the 'sysroot' of the toolchain, as it would + contain hundreds of megabytes of pre-compiled libraries that are + normally built by Buildroot. + +* The ELDK toolchains have a completely non-standard custom mechanism + to handle multiple library variants. Instead of using the standard + GCC 'multilib' mechanism, the ARM ELDK uses different symbolic links + to the compiler to differentiate between library variants (for ARM + soft-float and ARM VFP), and the PowerPC ELDK compiler uses a + +CROSS_COMPILE+ environment variable. This non-standard behaviour + makes it difficult to support ELDK in Buildroot. + +We also do not support using the distribution toolchain (i.e the +gcc/binutils/C library installed by your distribution) as the +toolchain to build software for the target. This is because your +distribution toolchain is not a "pure" toolchain (i.e only with the +C/C++ library), so we cannot import it properly into the Buildroot +build environment. So even if you are building a system for a x86 or +x86_64 target, you have to generate a cross-compilation toolchain with +Buildroot or crosstool-NG. + +If you want to generate a custom toolchain for your project, that can +be used as an external toolchain in Buildroot, our recommandation is +definitely to build it with http://crosstool-ng.org[crosstool-NG]. We +recommend to build the toolchain separately from Buildroot, and then +_import_ it in Buildroot using the external toolchain backend. + +Advantages of this backend: + +* Allows to use well-known and well-tested cross-compilation + toolchains. + +* Avoids the build time of the cross-compilation toolchain, which is + often very significant in the overall build time of an embedded + Linux system. + +* Not limited to uClibc: glibc and eglibc toolchains are supported. + +Drawbacks of this backend: + +* If your pre-built external toolchain has a bug, may be hard to get a + fix from the toolchain vendor, unless you build your external + toolchain by yourself using Crosstool-NG. + +Crosstool-NG toolchain backend +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The _Crosstool-NG toolchain backend_ integrates the +http://crosstool-ng.org[Crosstool-NG] project with +Buildroot. Crosstool-NG is a highly-configurable, versatile and +well-maintained tool to build cross-compilation toolchains. + +If you select the +Crosstool-NG toolchain+ option in +Toolchain Type+, +then you will be offered to: + + * Choose which C library you want to use. Crosstool-NG supports the + three most important C libraries used in Linux systems: glibc, + eglibc and uClibc + + * Choose a custom Crosstool-NG configuration file. Buildroot has its + own default configuration file (one per C library choice), but you + can provide your own. Another option is to run +make + ctng-menuconfig+ to get access to the Crosstool-NG configuration + interface. However, note that all Buildroot packages have only been + tested with the default Crosstool-NG configurations. + + * Choose a number of toolchain options (rather limited if glibc or + eglibc are used, or numerous if uClibc is used) + +When you will start the Buildroot build process, Buildroot will +download and install the Crosstool-NG tool, build and install its +required dependencies, and then run Crosstool-NG with the provided +configuration. + +Advantages of this backend: + +* Not limited to uClibc: glibc and eglibc are supported. + +* Vast possibilities of toolchain configuration. + +Drawbacks of this backend: + +* Crosstool-NG is not perfectly integrated with Buildroot. For + example, Crosstool-NG has its own download infrastructure, not + integrated with the one in Buildroot (for example a Buildroot +make + source+ will not download all the source code tarballs needed by + Crosstool-NG). + +* The toolchain is completely rebuilt from scratch if you do a +make + clean+. + /dev management ~~~~~~~~~~~~~~~ |