Embedded Handbook/General/Cross-compiling with Portage

== Cross-compiling with Portage == Leverage Portage as a cross-compiling package manager.

Variables
There are a few important variables that will be used throughout this section:

These variables can be set by hand, but that obviously gets tedious very quickly. A better idea is to stick these into a shell script to avoid typing them each time.

Filesystem setup
Cross-compiling a system generally involves two directory structures. The differences between them can be difficult to understand, but they are important concepts to cross-compiling.

The first directory structure to consider is the sysroot. Please read the Introduction chapter for the definition of sysroot.

The second directory structure is the real root. This one is much simpler to understand: it's where the bootable stage3-like installation of Gentoo is located. This installation can then be copied to the target device.

The common convention is to use the directory as the sysroot since the include/library directories in this tree are already encoded into the gcc cross-compiler for searching. You could use another directory and then add custom /  paths to the CPPFLAGS / LDFLAGS, but this has historically proven to be problematic in enough corner cases to be discouraged for practical use. In the embedded handbook, we'll assume the sysroot is being used as the development ROOT.

For your runtime system, you'll need a much slimmer/trimmed-down setup. The files you remove from a normal installed package is why this tree is not suitable for compiling against. If you build binary packages while installing into your sysroot, then you can use those binary packages in conjunction with the INSTALL_MASK variable to trim out most things. See for more information.

Intro: crossdev's wrappers
These are simple wrapper scripts that will setup the environment variables to point to the right places for you to be able to cross compile using. PORTAGE_CONFIGROOT and ROOT both point to the SYSROOT.

We can use these tools for both installing into your development root (sysroot) and into your runtime root. For the latter, simply specify by using the  option. For example if you had merged via crossdev an armv4tl-softfloat-linux-gnueabi toolchain you would then invoke the command just like normal emerge. But using the ctarget prefix:

By default these wrappers use the  option to avoid the host dependencies from being pulled into the deptree. This can lead to incomplete deptrees. Therefore you may want to use  alone to see the full depgraph.

By default crossdev will link to the generic embedded profile. This is done to simplify things, but the user may wish to use a more advanced targeted profile. In order to do that we can update the profile symlink.

To change settings (such as USE flags) for the target system, edit the standard Portage config files:

Sometimes there are some additional, cross-compile-incompatible tests that must be overridden for configure scripts. To make this possible, crossdev exports a few variables to force the test to get the answer it should receive. This helps prevent bloat in packages which add local functions to workaround issues it assumes the target system has because it could not run the test while cross-compiling (because, of course, it's not running on the target system). From time-to-time additional variables may need to be added to these files in in order to get a package to compile. To figure out the variable that needs added, it is often as simple as grepping the configure script for the autoconf variable (which often begins with ) and adding it to the appropriate target file. This becomes easier with ebuild development experience.

Uninstall
If you want to uninstall and delete your work, then you can safely remove the sysroot tree without affecting any native packages. See also the section in the crossdev guide about uninstalling.