// -*- mode:doc -*- ;

[[external-toolchain]]
Using an external toolchain
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Using an already existing toolchain is useful for different
reasons:

* you already have a toolchain that is known to work for your specific
  CPU

* you want to speed up the Buildroot build process by skipping the
  long toolchain build part

* the toolchain generation feature of Buildroot is not sufficiently
  flexible for you (for example if you need to generate a system with
  'glibc' instead of 'uClibc')

Buildroot supports using existing toolchains through a mechanism
called 'external toolchain'. The external toolchain mechanism is
enabled in the +Toolchain+ menu, by selecting +External toolchain+ in
+Toolchain type+.

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.