This is Gentoo's testing wiki. It is a non-operational environment and its textual content is outdated.
Please visit our production wiki at https://wiki.gentoo.org
Embedded Handbook/General/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:
| 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/crossdevcrossdev'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 pkg2By 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.profileTo change settings (such as USE flags) for the target system, edit the standard Portage config files:
root #${EDITOR} ${SYSROOT}/etc/portage/make.confSometimes 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.
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.
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.