Cross build environment

Cross build environments are needed for different situations


 * To cross build software for slow target hosts on a fast build host.
 * To build software with a different toolchain (i.e. different libc versions)
 * When a specialized system environment is needed
 * i.e. a separate 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 takes a tuple ARCH-VENDOR-OS-LIBC; see

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 at

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 packages need to be compiled in the target chroot environment. 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.
 * install qemu on the host
 * prepare qemu for the target (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 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 directory:
 * Update /etc/locale.gen and /etc/env.d/02locale and run:
 * 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 built with:
 * After installation of the base system the target environment can be finished according to the installation handbook
 * 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 built with:
 * After installation of the base system the target environment can be finished according to the installation handbook
 * After installation of the base system the target environment can be finished according to the installation handbook
 * 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 the package in the chroot again.
 * If the build host is no-multilib and target environment is multilib: Emerge of sys-apps/sandbox fails because of missing 32bit support of the cross compiler. To solve this remove temporarily the dependency to sys-apps/sandbox in sys-apps/portage. Emerge sys-devel/gcc after that in the chroot environment. Now it is possible to emerge sys-apps/sandbox in the chroot.
 * Some targets (e.g. ) may require you to add to the  command line, otherwise the  (version 5) stage 2 will fail to build (as discussed in Gentoo ).

Cross building static binaries for closed systems
Static binaries are not needed often, but there are some occasions where they are useful.
 * When creating (Docker) container images. According to the container philosophy it is recommended to run only one process per container. It is also recommended to put as little as possible into a container. In this case one statically linked binary is desirable.
 * When a program will run on a closed system like an ARM device with Android. In the case of Android it is possible to either use the Android's NDK and/or its clib implementation "bionic" or build a statically linked binary, that depends on no system libs and can run standalone.

Cross build toolchain for static binaries
It is pretty much the same as above beside that it is not needed to emerge a full @system. The build essentials are enough.
 * If the target is an Android device the architechture ist probably armv7a or arvm8a, so the tuple ARCH-VENDOR-OS-LIBC could be
 * Compiling the build essentials for an exemplary android toolchain could look like
 * should be switched on after installation of the base system (e.g. if the target program needs openssl)

customized glibc
There are some issues with glibc. Probably this does not affect other libc's like µclibc or musl. If you use glibc you should pay attention to the following.
 * Even when a program was built with, the resulting binaries aren't necessary really static. Because of design decisions of the glibc, at least the   are looked up dynamically. To force nss linked statically the flag   can be used for compiling glibc.
 * When a program is linked statically and makes use of glibc's NSS features like  the lookup of user names fails when nsswitch.conf is set to "compat". Set it to files in this case:
 * The glibc has hardcoded absolute pathes for some configuration files like . On an closed system (like Android) these files doesn't necessarily exist and without them DNS lookups will fail. Normally the files can't be written without root priviledges. If becoming root is not an option, glibc must be customized to look at a different location for these files. Keep in mind, that his is only necessary if the program makes use of glibc functions that need these files. But virtually every program, that connects to the internet uses sorts of gethostbyname and therefor needs a resolv.conf.

(optionally) create an customized glibc ebuild
This step is only necessary, if the glibc config files don't reside in /etc and the target program makes use of glibc's lookup functions (probably when the program does dns or user name lookups)
 * 1) Copy /usr/portage/sys-libs/glibc to your local ebuild repository and create a custom glibc ebuild
 * 2) Make the following changes
 * 3) Remove the KEYWORDS line (to prevent a accidential use in other environments)
 * 4) If you want to change the path to the config files add to the   section

Rebuild a customized glibc
Rebuild glibc with static options. When the default path was changed in the previous step remember to change  here appropriate.

Build the desired Software

 * Chroot into the target environment (e.g. )
 * If the default path for glibc config files was changed symlink it
 * Build a statically linked package
 * an example for android is privoxy
 * an example for a statically linked nginx is

Example: Use a statically linked privoxy on Android

 * unzip the binary tarball from above to /sdcard/ on the android device (e.g. trough the ssh server "sshelper" via Google Play or "ftpserver" via F-Droid)
 * change in the privoxy config  at least all entries with   and   in   and
 * put a resolv.conf in /sdcard/etc/ (e.g. with nameservers from www.opennicproject.org or the ad blocking nameservers fom www.alternate-dns.com )
 * put a privoxy startscript in /sdcard/
 * install the android app "connectbot" (available via F-Droid)
 * open a local connection named "privoxy" and close it again
 * hold long the "privoxy" connection to open the context menu and choose "edit host"
 * insert as "automation"-task:  (a newline is needed at the end)
 * to start privoxy open the connection in connectbot
 * To browse trough privoxy, add as proxy localhost/8118 to the mobile data APN's (in the android control panel at "mobile networks" → "APNs") and WiFi's