Embedded Handbook/General/Cross-compiling with Portage

From Gentoo Wiki
Jump to:navigation Jump to:search
General topics
Creating a cross-compiler
Cross-compiling with Portage
Cross-compiling the kernel
Compiling with qemu user chroot
Frequently asked questions
Das U-Boot
Hammer Board and Nail Board
QNAP TurboStation 109/209/409
Marvell Sheevaplug
Genesi Efika MX
BeagleBone Black
Intel Edison

Leverage Portage as a cross-compiling package manager.


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

Variable name Meaning
CBUILD Platform you are building on.
CHOST Platform you are compiling for.
ROOT The virtual / you are installing into.
PORTAGE_CONFIGROOT The virtual / Portage can find its config files (like make.conf).

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 /usr/${CTARGET}/ 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 -I/-L 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 man make.conf 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 emerge. PORTAGE_CONFIGROOT and ROOT both point to the SYSROOT.

root #emerge --ask sys-devel/crossdev
crossdev's wrappers automatically configure the CBUILD and CHOST variables. Do not set them by hand in the environment!
Before beginning any cross-emerge, you'll need to run emerge-wrapper --init. Be sure to follow any instructions printed by emerge-wrapper before beginning your cross-emerge.

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 --root 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:

root #armv4tl-softfloat-linux-gnueabi-emerge pkg0 pkg1 pkg2

By default these wrappers use the --root-deps=rdeps option to avoid the host dependencies from being pulled into the deptree. This can lead to incomplete deptrees. Therefore you may want to use --root-deps 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.

root #ln -s /usr/portage/profiles/default/linux/arm/13.0 ${SYSROOT}/etc/portage/make.profile

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

root #${EDITOR} ${SYSROOT}/etc/portage/make.conf

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 /usr/share/crossdev/include/site/ 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 ac_) and adding it to the appropriate target file. This becomes easier with ebuild development experience.


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.

This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Mike Frysinger, Ned Ludd, Robin H. Johnson, Alex Tarkovsky, Alexey Shvetsov, Raúl Porcel, Joshua Saddler on April 28, 2013.
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.