Gentoo Logo

[ << ] [ < ] [ Home ] [ > ] [ >> ]

1. Introduction


1.a. Overview

Cross development has traditionally been a black art, requiring a lot of research, trial and error, and perseverance. Intrepid developers face a shortage of documentation and the lack of mature, comprehensive open source toolkits for multi-platform cross development. Ongoing work by the Embedded Gentoo project, the Gentoo Toolchain herd, and other contributors is yielding a Gentoo-based development platform that greatly simplifies cross development.

1.b. The Toolchain

The term "toolchain" refers to the collection of packages used to build up a system (the "tools" which are used in the "chain" of events to take some input and produce some output). It is a loose definition in terms of what packages exactly are considered part of the toolchain, but for the sake of keeping things simple, we will consider the components that are needed to compile code into something fun and usable.

Your typical toolchain is therefore composed of the following:

  • binutils - Essential utilities for handling binaries (includes assembler and linker)
  • gcc - The GNU Compiler Collection (the C and C++ compiler)
  • glibc or uclibc or newlib - The system C Library
  • linux-headers - Kernel headers needed by the system C Library
  • gdb - The GNU debugger

All proper Gentoo systems have a toolchain installed as part of the base system. This toolchain is configured to build binaries native to its host platform.

In order to build binaries on the host system for a non-native platform you'll need a special toolchain - a so-called cross toolchain - which can target that particular platform. Gentoo provides a simple but powerful tool called crossdev for this purpose. Crossdev can build and install arbitrary GCC-supported cross toolchains on the host system, and because Gentoo installs toolchain files into target-specific directories the toolchains built by crossdev won't interfere with the host's native toolchain.

1.c. Toolchain Tuples

All toolchains have a prefix (think CHOST). More details on that can be found in the system tuples page.

1.d. Environment Variables

Certain environment variables used by the Gentoo toolchain and Portage can thoroughly confuse developers inexperienced with cross development. The following table explains some tricky variables and provides sample values based on the cross development examples presented in this guide. See More Terminology and Variables for more unusual variables and related concepts.

Variable Meaning When Building Cross-Toolchain Meaning When Building Cross-Binaries
CBUILD Platform you are building on Platform you are building on
CHOST Platform the cross-toolchain will run on Platform the binaries built by cross-toolchain will run on
CTARGET Platform the binaries built by cross-toolchain will run on Platform the binaries built by cross-toolchain will run on. Redundant, but there's no harm in setting this, and a few binaries do like it.
ROOT Path to the virtual root (/) you are installing into
PORTAGE_CONFIGROOT Path to the virtual root (/) portage can find its config files (like /etc/make.conf)

Say we have an AMD64 desktop as our normal Gentoo machine and we have an ARM PDA we wanted to develop for, the above table would look like:

Variable Value For Building Cross-Toolchain Value For Building Cross-Binaries
CBUILD x86_64-pc-linux-gnu x86_64-pc-linux-gnu
CHOST x86_64-pc-linux-gnu arm-unknown-linux-gnu
CTARGET arm-unknown-linux-gnu not set
ROOT not set -- defaults to / /path/where/you/install
PORTAGE_CONFIGROOT not set -- defaults to / /path/where/your/portage/env/for/arm/pda/is

1.e. More Terminology and Variables

canadian cross
The process of building a cross-compiler which will run on a different machine from the one it was compiled on (CBUILD != CHOST && CHOST != CTARGET)
sysroot: system root
The root directory a compiler uses to find its standard headers and libraries
The system has a hardware Floating Point Unit (FPU) to handle floating point math
The system lacks a hardware FPU so all floating point operations are approximated with fixed point math
Position Independent Executable (-fPIE -pie)
Position Independent Code (-fPIC)
C RunTime

[ << ] [ < ] [ Home ] [ > ] [ >> ]


View all

Page updated April 28, 2013

Summary: An introduction into the world of embedded, cross-compilers, and dragons.

Mike Frysinger

Ned Ludd

Robin H. Johnson

Alex Tarkovsky

Alexey Shvetsov

Raúl Porcel

Joshua Saddler

Donate to support our development efforts.

Copyright 2001-2015 Gentoo Foundation, Inc. Questions, Comments? Contact us.