From Gentoo-en
Jump to: navigation, search
Please format this article according to the Style Guidelines and Wikification suggestions, then remove this notice {{Wikify}} from the article.


  • numbering and levels of headers need to be fixed
  • add to categories

Crossdev is a script which automates the building of cross-compiling toolchains. It is in the sys-devel/crossdev package.

What is cross compiling?

Cross-compiling is building binaries for one architecture (the target machine) on another (the host machine).

Reasons you may wish to do this include:

  • You are an embedded developer, and cannot fit a native toolchain on an embedded system.
  • You are porting Gentoo to a new architecture, and need to cross-compile a stage 1 system to bootstrap.
  • You are building binaries against a different C library. While this is not cross-compiling, a different target tuple can be used to accomplish this.
  • You need 32 bit library on a 64bit system and don't want to build a complete chroot environment

Why do we need crossdev?

Gentoo created the crossdev script to automate the complex process of building a cross compiler. While it is not error-free, it does not require the extensive GNU lore and trial and error required by building it from scratch. A lot of the build options are set up for you, meaning that the developers have figured it out already so you don't have to.

Installation and Use

The first thing that is necessary is the creation of an overlay. If you have one, emerge the script:

emerge crossdev

This will provide you with the crossdev script. This script automates the steps necessary to build a toolchain. These steps are, in short:

  1. binutils: Build a cross-binutils, which links and processes for the target architecture.
  2. linux-headers: Install a set of C library and kernel headers for the target architecture.
  3. libc-headers: Additional header files
  4. gcc-stage-1: Build a basic (stage 1) gcc cross-compiler. This will be used to compile the C library. It will be unable to build anything almost else (because it can't link against the C library it doesn't have).
  5. libc: Build the cross-compiled C library (using the stage 1 cross compiler).
  6. gcc-stage-2: Build a full (stage 2) C cross-compiler.

All cross toolchains will be kept locally in the overlay, separate from native tools.

Note: crossdev uses the first overlay (which is the least important one), so if you use layman you'd probably like to have lines like following in make.conf
File: /etc/make.conf
source /usr/portage/local/layman/make.conf
Layman places additional overlays before your one, so the second line is needed to make your one the first one.

The script is used like:

crossdev -t powerpc-unknown-linux-gnu

This will build a cross-compiling toolchain for PowerPC machines.

By default, the newest stable version of the binutils, libraries, and C compiler will be used. It is quite often the case they will not compile themselves through the entire build process. Less bleeding edge versions can be specified with additional flags:

--b 2.17      # specifies the version of binutils
--g 4.2.3     # specifies the version of gcc
--l 0.98.3-r2 # specifies the version of the tuple-specified libc
--k 2.6.25    # specifies the version of the kernel headers

It is recommended trying older versions, particularly of gcc, if the script fails.

If you want to remove a toolchain, use the clean flag:

crossdev -C powerpc-unknown-linux-gnu

This will unmerge the packages created by crossdev.

Known problems

Error while building GCC stage 1: "Building GCC requires GMP 4.1+ and MPFR 2.3.0+."

emerge --ask -v gmp mpfr

pkg-config problems

There are problems where build program does not take into account using the correct pkg-config. To correct this you need to also install a pkg-config wrapper for your target. The following is taken from the Gentoo Embedded Handbook.

Note: Many packages are moving to installing pkg-config files (*.pc) and using those to discover needed libraries and includes. To ease the build process, you should install a pkg-config wrapper for your target which will tell pkg-config to only search your cross-compiler paths rather than your host paths. You should install this into your PATH so that configure scripts will detect it properly. Name it with a CTARGET prefix and the script will do the rest. In other words, if your CTARGET is set to arm-linux-uclibc, the canonical name is arm-linux-uclibc-pkg-config. Older configure scripts would only search for pkg-config, so in those cases you will need to export the PKG_CONFIG variable to the wrapper script.

Here is also the script that gentoo doc uses put here for easy refrence

File: /usr/bin/0%-pkg-config

export PKG_CONFIG_LIBDIR="${SYSROOT}/usr/lib/pkgconfig"
exec pkg-config "$@"

Don't forget to chmod + x the file or it won't be found. I also had a problem CTARGET not being set right so you might have to change it as well.

Problem with libtool

I found out there problem with libtool you can read about it here

Supported Architectures

Fix me: Is there a list somewhere?

Currently, every GCC-tuple (e.g. i686-pc-linux-gnu) for which Gentoo has been ported is supported. Additional architectures, of course, have their own patches, bugs, hacks, and specific necessary versions of all the tools. Several are already listed on this wiki in different articles.

Notable architectures include:

  • i686-pc-linux-gnu: The default x86 tuple for PCs.
  • x86_64-pc-linux-gnu: The default tuple for 64-bit x86 Machines (such as the AMD 64 and IA64 architectures).
  • powerpc-unknown-linux-gnu: Support for PowerPC PCs, such as Apple Macintoshes.
  • armv7a-hardfloat-linux-gnueabi: Support for embedded devices with newer Cortex-A9 based ARM chips.
  • arm-unknown-linux-gnu: Support for embedded devices based on ARM chips.
  • arm-softfloat-elf: For embedded devices with ARM chips without hardware floats
  • arm-elf: For embedded devices with ARM chips with hardware floats
  • i686-pc-mingw32: Supports cross-compiling for 32-bit Windows (toolchain based on mingw32).
  • i686-w64-mingw32: Supports cross-compiling for 32-bit Windows (toolchain based on mingw64).
  • x86_64-w64-mingw32: Supports cross-compiling for 64-bit Windows (toolchain based on mingw64).
  • avr: Supports cross-compiling for Atmel AVR-MCU's.

More information about supported arch and vendors available here: [1]

Known Working Architecture Matrix

The following sections are by no means exhaustive. However, these are known working combinations of versions of some of the more common architectures.

Power PC Architecture

Fix me: crossdev -t powerpc-unknown-linux-gnu --g 4.3.1

ARM Architecture

Fix me: crossdev -t arm-unknown-linux-gnu --b 2.19.1 --g 4.3.3 --l 2.9_p20081201-r1 --k 2.6.28-r1
Fix me: crossdev -t arm-softfloat-linux-gnueabi

(resulted with working versions: --g 4.5.2 --l 2.13-r2 --k --b 2.21)

This example works for an Atmel SAM9 MCU (arm926ej-s core):

Fix me: crossdev -t crossdev armv5tej-softfloat-linux-gnueabi

As of November 13, 2012, this example works for Cortex-A9 targets:

crossdev -S -t armv7a-hardfloat-linux-gnueabi

AVR Architecture

A patch is needed in order to properly enable multilib to avoid library problems. Bug:

curl -o crossdev-378387.patch
patch /usr/bin/crossdev crossdev-378387.patch

first build without headers

USE="-cxx" crossdev -s1 --without-headers --target avr

then the rest

USE="cxx" crossdev -s4 --target avr

You also need workaround so that the linking works like expected

For x86: ln -s /usr/i686-pc-linux-gnu/avr/lib/ldscripts /usr/avr/lib/ldscripts
On amd64: ln -s /usr/x86_64-pc-linux-gnu/avr/lib/ldscripts /usr/avr/lib/ldscripts

Seems as if this Bug will not get fixed! ->

14 September 2010: Works fine with gcc-4.4.4-r1. The only thing is, you must force USE="-openmp". If you are using a single file /etc/portage/package.use, do mkdir /etc/portage/package.use and move the file into that directory. Any name is fine. Then crossdev will create /etc/portage/package.use/cross-avr and you can force USE="-openmp" by adding a cross-avr/gcc -openmp line in some other file (any file). More info: []

Some versions of gcc have serious bugs when it comes to compiling avr. Your best bet may be to unmask gcc-4.6.2 and add the following to the commands above:

--gcc 4.6.2 --binutils 2.21 --libc 2.21.1-r1

other versions reported to work:

--gcc 4.5.2 --binutils 2.21 --libc 1.7.0
--gcc 4.3.3 --binutils --libc 1.6.4

2012-09-11 A few fruitless weeks in trying, now everything seems to be working!!!

crossdev -C avr USE="multilib -cxx" crossdev --l 1.6.4 --b 2.19.1-r1 --g 4.3.3-r2 -S -s1 --target avr -v USE="multilib cxx" crossdev --l 1.6.4 --b 2.19.1-r1 --g 4.3.3-r2 -S -s4 --target avr -v ln -nsf /usr/x86_64-pc-linux-gnu/avr/lib/ldscripts /usr/avr/lib/ldscripts ln -nsf /usr/x86_64-pc-linux-gnu/avr/lib/ldscripts /usr/x86_64-pc-linux-gnu/avr/binutils-bin/2.22/ldscripts cd /usr/avr/lib ln -nsf avr5/crtm328p.o . ln -nsf avr6/crtm2561.o . ln -nsf avr6/crtm2560.o .

NB: I am on x86_64 and using binutils-2.22 for the normal install

2013-01-06 Although not a real solution, there is precompiled ArduinoIDE (toolchain included), I made an ebuild:

MIPS Architeture

MIPSel Specific

Looks that MIPsel have some problems with the last binutils/gcc

Fix me: crossdev -t mipsel-linux-uclibc --b 2.19.1 --g 3.4.6-r2
Note: See Gentoo Forum for more information: Crossdev MIPS, mips-headers deleted [solved]