Cross build environment

Introduction
Cross build environments are needed for different situations


 * To cross build software for a slow target host on a fast build host. If the target has a different architecture additionally a qemu chroot is needed.
 * To build software with a different toolchain (i.e. different libc versions)
 * When a specialized system environment is needed
 * i.e. a seperate multilib system for binaries with abnormal dependencies which you don't want to mix with your main system (like the steam platform)
 * i.e. a base image for docker containers

Create the cross toolchain

 * Install crossdev:
 * Create the toolchain. For the raspberry-pi it would look like
 * For a amd64-multilib environment it would look like
 * Target (-t) takes a tuple ARCH-VENDOR-OS-LIBC; see 'crossdev -t help'

Update the target build configuration

 * The target make.conf should be changed according to the installation handbook. For the base system at least these options should be checked, the rest can be configured later:


 * Set the appropriate make profile. For the raspberry-pi it would be
 * If you build on amd64 see the lib64-bug #known-bugs-and-limitation

Build the base system
It can be built from scratch or a stage3 tarball can be unpacked into /usr/. To build it from scratch:
 * Build the system packages for the raspberry-pi it would be  (Do not care about failed packages, this will be fixed later)
 * Build other essential packages
 * To build the failed packages it is needed to compile them "natively", which means in this case, that the packes need to be compiled in the target chroot enviroment. If the target host has a different architecture a qemu-chroot is needed. For targets that the build host cpu can handle directly the following steps can be skipped and you can chroot directly into the target environment.
 * prepare qemu (in this case for the arm architecture)
 * install qemu to the build environment
 * A first test: If it works, leave the chroot and go on with the next steps.
 * Optional: This step is not necessary in most cases. To make the target environment emulation more complete, a wrapper can be used, that passes the the correct cpu option to qemu. The following would be an example for the raspberry-pi cpu option for qemu (-cpu arm1176). Please check if the command at the end (qemu-arm) is present on your build host.
 * Build it with

Chroot into the target environment

 * Create a chroot script
 * To chroot into the new environment run the script and complete the set up of your build environment
 * Create the portage temp dir
 * Update /etc/locale.gen and /etc/env.d/02locale and run after that.
 * Check/Reload config
 * To run emerge inside the chroot it is needed to pass other config variables to portage, it can be done with an alias:
 * Packages, that refused the cross compilation can now be build with:
 * After installation of the base system the target environment can be finished according to the installation handbook

Known bugs and limitations

 * On amd64 build hosts, some cross compiled packages end up in the target environment in /usr/lib64 even if it is not a 64bit target, so set a symlink
 * Some packages, that create new system users fail to create them in the target environment and create them in build host instead (i.e. openssh). You need to create the user manually or emerge it in the chroot again.