There are a few important variables that we will use throughout this section.

You can either set this all by hand, but that obviously gets quite tedious very quickly. A better idea is to stick these into a shell script so you can avoid typing it out all the time.

Cross-compiling a system generally involves two directory trees. The first is where all development files are normally installed. This is your sysroot. The other tree is where only your runtime files are installed. You emerge all of your fun packages into your sysroot (without trimming down any files), and then either install via binary packages or copying files by hand all the stuff you need in your runtime tree.

The common convention is to use your /usr/CTARGET/ tree as your sysroot as 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 your CPPFLAGS/LDFLAGS, but this has historically proven to be problematic. Yes, it works most of the time, but the corner cases are why this method is discouraged. In the embedded handbook, we'll assume you're using the sysroot as your 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.

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.

# emerge crossdev

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:

# 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 the wrappers will link to the generic embedded profile. This is done to simpilify things, but the user may wish to use a more advanced targeted profile. In order to do that we can update the profile symlink.

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

And naturally to change settings for the target system like USE flags, FEATURES, and VIDEO_CARDS. We would edit the standard portage config files.

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

Sometimes there are some additional tests we need override for configure scripts. To do this the wrappers export a few variables to force the test to get the answer it should. This will help prevent bloat in packages which add local functions to workaround issues it assumes your system has because it could not run the test. From time to time you may find you need to add additional variables to these files in /usr/share/crossdev/include/site/ to get a package to compile. To figure out the variable you need to add, it's often as simple as greping the configure script for the autoconf variable and adding it to the appropriate target file. This becomes obvious after the first few times of doing it.

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.