Embedded Handbook/General/Creating a cross-compiler

== Creating a cross-compiler == The first thing users should know about building a toolchain is that some versions of toolchain components refuse to work together. Exactly which combinations are problematic is a matter that's constantly in flux as the Gentoo ebuild repository evolves. The only reliable way to determine what works is to run, adjusting individual component versions as necessary, until crossdev completes the toolchain build successfully. Even then, the cross toolchain may build binaries which break on the target system. Only through trial and error and patience will you arrive at a favorable combination of all factors.

Users do not have to worry about the cross-compiler interfering with the native build system. All of the toolchain packages are designed such that they are isolated from each other based on the target. This way cross-compilers can be installed for desired architecture(s) without breaking the rest of the system.

Intro
Generating a cross-compiler by hand is a long and painful process. This is why it has been fully integrated into Gentoo! A command-line front-end called will run  with all of the proper environment variables and install all the right packages to generate arbitrary cross-compilers based on the need of the user. First install :

Consider installing the unstable version of crossdev to get all the latest fixes.

Only basic usage of is covered here, but crossdev can customize the process fairly well for most needs. Run to get some ideas on how to use crossdev. Here are some common usage options:

Installing
The first step is to select the proper tuple for the target. Here we will assume the user would like to build a cross-compiler for the SH4 (SuperH) processor with glibc running on Linux. This action will be performed on a PowerPC machine. Generate a SH4 cross-compiler:

Quick test
If everything goes as planned,a shiny new compiler should now be present on the machine. Give it a spin!

Use the SH4 cross-compiler:

If the crossdev command failed, you have the log file which you can review to see if the problem is local. If you're unable to fix the issue, you're welcome to file a bug in our Bugzilla. See the Communication section for more information.

Tuples
To find out which tuple you should use, look over the output from the following command:

You can now find a newly compiled cross-compiler in the sysroot at. It's a good idea to create pre-built binary packages so you don't end up waiting another two to three hours every time you want to reinstall this toolchain.

Create binpkgs
If the command warns about excluded files, please follow its prompts to include all files.

In the future the sysroot can be reinstalled by executing the following simple Portage command:

Uninstalling
To uninstall a toolchain, simply use the  option. If you modified the sysroot by hand, you'll be prompted to delete every file inside, so you will want to prepend to this command if you are sure:

Uninstall the SH4 cross-compiler:

In case you didn't already notice, deleting any and all files in the directory is completely safe.

Overview
There are generally two ways to build a cross-compiler. The "accepted" way, and the cheater's shortcut.

The current "accepted" way is:


 * 1) binutils
 * 2) kernel headers
 * 3) libc headers
 * 4) gcc stage1 (c-only)
 * 5) libc
 * 6) gcc stage2 (c/c++/etc...)

The cheater's shortcut is:


 * 1) binutils
 * 2) kernel headers
 * 3) gcc stage1 (c-only)
 * 4) libc
 * 5) gcc stage2 (c/c++/etc...)

The reason people are keen on the shortcut is that the libc headers step tends to take quite a while, especially on slower machines. It can also be kind of a pain to setup kernel/libc headers without a usuable cross compiler. Note though that if you seek help with cross-compilers, upstream projects will not want to help you if you took the shortcut.

Also note that the shortcut requires the gcc stage1 to be "crippled". Since you're building without headers, you cannot enable the sysroot option nor can you build up proper gcc libs. This is OK if the only thing you use the stage1 is building the C library and a kernel, but beyond that you need a nice sysroot based compiler.

Below I will describe the "accepted" way as the steps are pretty much the same. You just need some extra patches for gcc in order to take the shortcut.

Sysroot
We will be cross-compiling using the sysroot method. But what does the sysroot do?

The sysroot tells GCC to consider dir as the root of a tree that contains a (subset of) the root filesystem of the target operating system. Target system headers, libraries and run-time object files will be searched in there.

The top level directory is commonly rooted in

As you can see, it's just like the directory setup in but in. This setup is of course not an accident but designed on purpose so you can easily migrate applications/libraries out of and into  on your target board. If you wanted, you could even be lazy and use the as a quick NFS root!

Binutils
Grab the latest binutils tarball and unpack it.

The  option is to prevent binutils from aborting the compile due to warnings. Great feature for developers, but a pain for users. Configure and build binutils:

The reason we install into the localdir is so we can remove crap that doesn't belong. For example, a normal install will give us which doesn't belong in our host. So clean out stuff first:

And install what's left:

Kernel headers
Grab the latest Linux tarball and unpack it. There are two ways of installing the kernel headers: sanitized and unsanitized. The former is clearly better (but requires a recent version of the Linux kernel), but we'll quickly cover both.

Building and install the unsanitized headers:

Build and install the sanitized headers:

System libc headers
Grab the latest glibc tarball and unpack it. Glibc is picky, so you'll have to compile in a directory separate from the source code. Build and install the glibc headers:

Glibc sucks at life so you have to do a few things by hand:

GCC Stage 1 (C only)
We first have to help gcc find the current libc headers:

Then grab the latest gcc tarball and unpack it:

Same as binutils, gcc leaves some stuff behind we don't want. Clean the gcc stage 1:

System libc
Remove the old glibc build directory and recreate it:

GCC Stage 2 (All frontends)
Build up a full GCC now. Select whichever compiler frontends you like; we'll just do C/C++ for simplicity. Build and install the gcc stage 2:

Core runtime files
There are many random core runtime files that people wonder what they may be for. Let's explain:

The general linking order: