summaryrefslogtreecommitdiffstats
path: root/docs/manual/external-toolchain.txt
diff options
context:
space:
mode:
Diffstat (limited to 'docs/manual/external-toolchain.txt')
-rw-r--r--docs/manual/external-toolchain.txt84
1 files changed, 84 insertions, 0 deletions
diff --git a/docs/manual/external-toolchain.txt b/docs/manual/external-toolchain.txt
new file mode 100644
index 000000000..20eebdb20
--- /dev/null
+++ b/docs/manual/external-toolchain.txt
@@ -0,0 +1,84 @@
+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 toolchains for ARM, PowerPC, MIPS and
+ SuperH. Just select the toolchain profile in +Toolchain+ through 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. 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, 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.