crossdev

This page contains changes which are not marked for translation.

Resources

Project

Package information

GitWeb

Article status

This article needs wikification.

crossdev is a set of bash scripts that utilize emerge to provide a system integrated cross-compilation capability.

A Gentoo host machine's toolchain is leveraged by compiling for the specified target; by overriding several environment variables.^[1]^[2]

Installation

Emerge

root #emerge --ask sys-devel/crossdev

Crossdev overlay

Warning
Improperly using crossdev may "pollute" ebuild repositories: crossdev operates by adding packages to an ebuild repository, so care must be taken to ensure crossdev adds packages to a separate repository. Follow one of the creation methods below to create a separate repository for crossdev.

eselect creation

To use eselect-repository to create the repository, first install the package.

root #emerge --ask app-eselect/eselect-repository

Then, create the repository with:

root #eselect repository create crossdev

Manual creation

To manually create a crossdev repository:

root #

mkdir -p /var/db/repos/crossdev/{profiles,metadata}

root #

echo 'crossdev' > /var/db/repos/crossdev/profiles/repo_name

root #

echo 'masters = gentoo' > /var/db/repos/crossdev/metadata/layout.conf

root #

chown -R portage:portage /var/db/repos/crossdev

If the Gentoo ebuild repository is synchronized using Git, or any other method with Manifest files that do not include checksums for ebuilds, prevent "masked by: corruption" errors with:

FILE /var/db/repos/crossdev/metadata/layout.conf

masters = gentoo
thin-manifests = true

Instruct Portage, and subsequently crossdev, to use the new ebuild repository by enabling it:

FILE /etc/portage/repos.conf/crossdev.conf

[crossdev]
location = /var/db/repos/crossdev
priority = 10
masters = gentoo
auto-sync = no

Repository search order

In order of precedence, crossdev will make use of a Portage repository specified by:

The command-line option: --ov-output (-oO)
${CROSSDEV_OVERLAY}
Repository with name cross-${CTARGET}
Repository with name crossdev

Usage

Important
The -S option (for stable) should not be used on arches with no stable keywords or a mixed (unstable, inconsistent) profile, e.g. mips or riscv.

Invocation

user $crossdev --help

Usage: crossdev [options] --target TARGET

Options:
    -L,  --llvm              Use LLVM/Clang as a cross compiler
    --b, --binutils ver      Specify version of binutils to use
    --g, --gcc ver           Specify version of gcc to use
    --k, --kernel ver        Specify version of kernel headers to use
    --l, --libc ver          Specify version of libc to use
                                Note: versions support depend atom syntaxes:
                                 e.g. ">=2.20" "~4.6.1" "=2.13.1-r3"
    -A, --abis abis          Specify ABIs to build, first one is the default
    --host-abi abi           Specify the ABI of the compiler itself
    --env env                Specify env settings for all packages (see below)
    --[bdgkl]env env         Specify env settings for binutils/gdb/gcc/kernel/libc
                                Note: make sure to quote: 'VAR="some value"\nFOO="cow"'
    --[bdgkl]cat category    Use binutils/gdb/gcc/kernel/libc package from category
    --[bdgkl]pkg pkg         Use binutils/gdb/gcc/kernel/libc package with given name
    -f, --force              I don't need a seat belt!
    -S, --stable             Use latest stable versions as default
    -C, --clean target       Uninstall specified target
    -P, --portage opts       Options to pass to emerge (see emerge(1))
    --with[out]-headers      Build C library headers before C compiler?
    --show-fail-log          If the build fails, dump the failing log

Overlay Options:
    -oS, --overlays list     Space delimited list of overlays to search
                                [default: `portageq repositories_configuration`]
    -oO, --ov-output path    Parent directory of overlay to write crossdev package links
                                [default: uses repo with name 'crossdev', or
                                 'cross-${CTARGET}', or falls back to first
                                 from --overlays list]
    -ob, --ov-binutils path  Overlay for binutils ebuilds [default: search]
    -od, --ov-gdb path       Overlay for gdb ebuilds [default: search]
    -og, --ov-gcc path       Overlay for gcc ebuilds [default: search]
    -ok, --ov-kernel path    Overlay for kernel ebuilds [default: search]
    -ol, --ov-libc path      Overlay for C library ebuilds [default: search]
    -ox, --ov-extra path     Overlay for extra packages [default: search]

Stage Options:
    -s0, --stage0            Build just binutils
    -s1, --stage1            Also build a bare C compiler (no C library/
                                C++/shared GCC libs/C++ exceptions/etc...)
    -s2, --stage2            Also build kernel headers
    -s3, --stage3            Also build the C library
    -s4, --stage4            Also build a full compiler [default]
                                (shared libs GCC/various lang frontends/etc...)

External Tooling Options:
    --show-target-cfg        Display target settings that crossdev will use
    --init-target            Setup config/overlay/etc... files only

Extra Fun (must be run after above stages):
    --ex-only                Skip the stage steps above
    --ex-gcc                 Build extra gcc targets (gcj/ada/etc...)
    --ex-gdb                 Build a cross gdb
    --ex-pkg pkg             Build extra packages (may be used multiple times)

LLVM/Clang Specific Options (--llvm):
    --r, --crt ver           Specify version of compiler-rt to use
    --c, --ccw ver           Specify version of clang-crossdev-wrapper to use
    --[rc]env env            Specify env settings for compiler-rt/clang-crossdev-wrapper
    --[rc]cat category       Use compiler-rt/clang-crossdev-wrapper package from category
    --[rc]pkg pkg            Use compiler-rt/clang-crossdev-wrapper package with given name
    -or, --ov-crt path       Overlay for compiler-rt ebuilds [default: search]
    -oc, --ov-ccw path       Overlay for clang-crossdev-wrapper ebuilds [default: search]

Target (-t) takes a tuple ARCHITECTURE-VENDOR-OS-LIBC; see 'crossdev -t help'

To see the supported architectures, C libraries, and special targets:

user $crossdev --target help

Target (-t) takes a tuple ARCHITECTURE-VENDOR-OS-LIBC:

Supported Architectures (ARCHITECTURE):
   - alpha
   - arm / armeb / aarch64
   - hppa (parisc)
   - ia64
   - i386 / i486 / i586 / i686 (x86)
   - m68k
   - mips / mipsel / mips64 / mips64el
   - or1k
   - powerpc (ppc) / powerpc64 (ppc64)
   - riscv32 / riscv64
   - sparc / sparc64
   - s390 / s390x
   - sh / sh[1-5] / sh64
   - x86_64 (amd64)
Supported C Libraries (LIBC):
   - glibc (gnu)
   - klibc       [prob wont work]
   - musl
   - newlib      [bare metal/no operating system]
   - uclibc      [not all arches are ported]
Special Targets (full tuple):
   - avr      http://www.nongnu.org/avr-libc/
   - bfin     http://blackfin.uclinux.org/
   - h8300    http://h8300-hms.sourceforge.net/
   - mingw64  http://mingw-w64.sourceforge.net/
   - mmix     http://www-cs-faculty.stanford.edu/~knuth/mmix.html
   - msp430   http://www.ti.com/msp430
   - nds32    http://github.com/nds32
   - nios2    http://www.altera.com/products/ip/processors/nios2/ni2-index.html
   - xc16x    http://www.infineon.com/
   - ppu / spu (cell) [Cell/Playstation 3 targets]
Softfloat toolchains:
   Include 'softfloat' in the 'vendor' field
   e.g. armeb-softfloat-linux-uclibc  powerpc-booya_softfloat-linux-gnu

To build a cross toolchain, specify the target with the --target flag, such as:

root #crossdev --target aarch64-unknown-linux-gnu

To use the host LLVM toolchain as a cross compiler instead of compiling a target specific GCC toolchain, use the --llvm flag.

root #crossdev --llvm --target aarch64-gentoo-linux-musl

Important
It is currently not possible to compile glibc with LLVM/Clang, therefore any -gnu triplet will fail with the --llvm flag. There are also several CPU architectures not fully supported by the compiler-rt builtins library, which is needed for LLVM crossdev.

Note
C++ and unwinding is currently not supported by LLVM crossdev, but it is planned for the near future. It is therefore recommended to set USE="-cxx" in the meantime.

Build packages with crossdev

To cross compile packages it is now possible to use emerge-$CHOST, using an aarch64 glibc cross compiler it would look like emerge-aarch64-unknown-linux-gnu then use the Portage's commands as normal.

Set profiles

Profiles can be set like on normal system by doing the following.

First, list the available profiles:

root #PORTAGE_CONFIGROOT=/usr/aarch64-unknown-linux-gnu eselect profile list

  
  [1]  default/linux/arm64/23.0 (exp) *
  [2]  default/linux/arm64/23.0/hardened (exp)
  [3]  default/linux/arm64/23.0/hardened/selinux (exp)
  [4]  default/linux/arm64/23.0/hardened/selinux/systemd (exp)
  [5]  default/linux/arm64/23.0/desktop (exp)
  [6]  default/linux/arm64/23.0/desktop/gnome (exp)
  [7]  default/linux/arm64/23.0/desktop/gnome/systemd (exp)
  [8]  default/linux/arm64/23.0/desktop/plasma (exp)
  [9]  default/linux/arm64/23.0/desktop/plasma/systemd (exp)
  [10]  default/linux/arm64/23.0/desktop/systemd (exp)
  [11]  default/linux/arm64/23.0/systemd (exp)
  [12]  default/linux/arm64/23.0/llvm (exp)
  [13]  default/linux/arm64/23.0/llvm/systemd (exp)
  [14]  default/linux/arm64/23.0/split-usr (exp)
  [15]  default/linux/arm64/23.0/split-usr/hardened (exp)
  [16]  default/linux/arm64/23.0/split-usr/hardened/selinux (exp)
  [17]  default/linux/arm64/23.0/split-usr/desktop (exp)
  [18]  default/linux/arm64/23.0/split-usr/desktop/gnome (exp)
  [19]  default/linux/arm64/23.0/split-usr/desktop/plasma (exp)
  [20]  default/linux/arm64/23.0/split-usr/llvm (exp)
  [21]  default/linux/arm64/23.0/big-endian (exp)
  [23]  default/linux/arm64/23.0/big-endian/systemd (exp)
  [24]  default/linux/arm64/23.0/split-usr/big-endian (exp)
  [25]  default/linux/arm64/23.0/musl (exp)
  [26]  default/linux/arm64/23.0/musl/llvm (exp)
  [27]  default/linux/arm64/23.0/musl/hardened (exp)
  [28]  default/linux/arm64/23.0/musl/hardened/selinux (exp)
  [29]  default/linux/arm64/23.0/split-usr/musl (exp)
  [30]  default/linux/arm64/23.0/split-usr/musl/llvm (exp)
  [31]  default/linux/arm64/23.0/split-usr/musl/hardened (exp)
  [32]  default/linux/arm64/23.0/split-usr/musl/hardened/selinux (exp)

Then pick the required profile for the system needs.

root #PORTAGE_CONFIGROOT=/usr/aarch64-unknown-linux-gnu eselect profile set default/linux/arm64/23.0

Setting emerge options

crossdev allows the same configuration as /etc/portage by editing make.conf, package.use, package.accept_keywords etc in the /usr/aarch64-unknown-linux-gnu/etc/portage directory. See Portage documentation for more information.

Set up the base system

Crossdev sets up only the cross compiler and runtime. By itself, it doesn't install the base system or any libraries, which are

There are two ways:

Manual build of the base system. It works well for GCC-based environments, but has no guarantee to work with LLVM-based ones.
Using a stage3 tarball.

Manual build

Manual build consists of installation of glibc and @system without recording them in @world.

root #

USE=build aarch64-unknown-linux-gnu-emerge -v1 baselayout

root #

aarch64-unknown-linux-gnu-emerge -v1 sys-libs/glibc

root #

aarch64-unknown-linux-gnu-emerge -v1 @system

Stage3 tarball

First, download a desired stage3 archive, which matches your architecture and environment. For aarch64-unknown-linux-musl, that would be:

root #

wget https://gentoo.osuosl.org/releases/arm64/autobuilds/current-stage3-arm64-musl-llvm/stage3-arm64-musl-llvm-XXXXXXXXXXXXXXXX.tar.xz -O stage3-arm64-musl-llvm-latest.tar.xz

Then unpack it into the target root directory:

root #tar -xJpf stage3-arm64-musl-llvm-latest.tar.xz -C /usr/aarch64-unknown-linux-musl --exclude=dev --skip-old-files

Emerge a single package

To emerge a single package then just run:

root #emerge-aarch64-unknown-linux-gnu --ask app-editors/nano

Replacing the package with the one required for the system.

Emerge all the packages in system set

To emerge all packages in @system then run:

root #emerge-aarch64-unknown-linux-gnu --ask --verbose --oneshot @system

Binary packages

By default crossdev will create packages in /usr/aarch64-unknown-linux-gnu/var/cache/binpkgs which can be used to set up a Binary Host to install packages on a much weaker system which would take days, if not weeks otherwise.

User Patches

Because crossdev makes the ebuilds via symlinks, the default patch directory becomes /etc/portage/patches/cross-${CTARGET}/${PN}/. For example, to apply foobar.patch to sys-libs/glibc on the target system, the patch file should be placed in in /etc/portage/patches/cross-aarch64-unknown-linux-gnu/glibc/foobar.patch.

17.x to 23.0 migration

Users that have cross toolchain profiles created for 17.x profiles are recommend to delete the cross compiler and then recreate them again using a 23.0 profile to prevent multiple issues and assure the correct USE flags are set.

Please follow below for removal steps then see Crossdev#Usage on how to create them again.

Toolchains for architectures Gentoo doesn't officially support

Sometimes a user needs to build a cross compiler for a CPU arch which isn't supported by Gentoo however the toolchain does.

Visit packages.gentoo.org and find the current versions for the packages sys-devel/binutils, sys-devel/gcc and sys-libs/glibc or sys-libs/musl.

GCC	14.1.1_p20240622
Binutils	2.42-r2
Glibc	2.39-r9

With these version we can force crossdev to use the required versions in this usage case with the following:

root #ACCEPT_KEYWORDS="**" crossdev -s4 --binutils 2.42-r2 --libc 2.39-r9 --gcc 14.1.1_p20240622 sh4-unknown-linux-gnu

ACCEPT_KEYWORDS="**" Tells portage to temporailty accept any architeure keyword.

--binutils Explicitly set the binutils version

--gcc Explicitly set the GCC version

--libc Explicitly set the Glibc or musl version (crossdev selects the correct libc based on the triple provided.)

sh4-unknown-linux-gnu Triple required for cross compiler.

This will build a very basic cross compiler without profile support.

Removal

Important
Specifying the same machine-vendor-kernel-operating system as the host utils during removal could result in breakages that are irrecoverable without a proper backup method!

Important
To remove a LLVM/Clang crossdev target you need to explicitly pass --llvm.

Tip
Optionally, please see make.conf for setting up regular backups via binpkg & Portage's built-in features!

To remove a crossdev-generated toolchain, set the --clean flag before the --target flag using the target tuple to remove, for example:

root #crossdev --clean --target arm-none-eabi

 * Uninstalling target 'arm-none-eabi' ...
*** unmerging cross-arm-none-eabi/newlib-4.1.0-r1
*** unmerging cross-arm-none-eabi/binutils-2.37_p1-r1
*** unmerging cross-arm-none-eabi/gcc-11.2.1_p20211127
 * gcc-config: Could not locate profile # !
Cleaning up masquerade for ccache ...
removed 'arm-none-eabi-gcc'
removed 'arm-none-eabi-gcc-11.2.1'
 * Removing last cross-compiler instance. Deleting dangling symlinks.
rm: cannot remove '/usr/arm-none-eabi/usr': Is a directory
/usr/arm-none-eabi: directory still exists; remove recursively? [y/N] y

Unmerge

root #emerge --ask --depclean --verbose sys-devel/crossdev

Clang

To use Clang as a cross-compiler with `crossdev`, first ensure that `sys-devel/llvm` is installed with support for the necessary targets (e.g., `arm64`, `riscv64`):

emerge --ask sys-devel/llvm

Additionally, create a dedicated overlay for cross-compilation if it does not already exist:

eselect repository create crossdev

Note: `sys-devel/clang-crossdev-wrappers` is not meant to be installed directly. Instead, use `crossdev` to generate a toolchain.

Template:Info

To configure `crossdev` with Clang as the cross-compiler, use the `--llvm` flag when setting up a toolchain:

#!/bin/bash
CROSSDEV_OVERLAY=/usr/local/portage \
CROSSDEV_TARGET=aarch64-unknown-linux-gnu \
CBUILD=x86_64-pc-linux-gnu \
CC=clang \
CXX=clang++ \
crossdev --llvm --stable aarch64-unknown-linux-gnu

Replace `aarch64-unknown-linux-gnu` with your desired target architecture.

References

↑ Gentoo Gitweb: "Crossdev Script"
↑ crossdev was originally written by: Joshua Kinard (kumba)

[1] Gentoo Gitweb: "Crossdev Script"

[2] rossdev was originally written by: Joshua Kinard (kumba)

[1]

[2]

crossdev

Contents

Installation

Emerge

Crossdev overlay

eselect creation

Manual creation

Repository search order

Usage

Invocation

Build packages with crossdev

Set profiles

Setting emerge options

Set up the base system

Manual build

Stage3 tarball

Emerge a single package

Emerge all the packages in system set

Binary packages

User Patches

17.x to 23.0 migration

Toolchains for architectures Gentoo doesn't officially support

Removal

Unmerge

Clang

See also

References