From Gentoo Wiki
Jump to:navigation Jump to:search
This article is a stub. Please help out by expanding it - how to get started.

Article status
This article needs wikification.

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

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

See also
See the cross build environment guide for more detailed usage information.



root #emerge --ask sys-devel/crossdev

Crossdev overlay

Using crossdev may unintentionally "pollute" ebuild repositories if proper care is not taken. Follow this section to assure that crossdev places files in a reasonable location, and does not create other disturbances.

crossdev will place the ebuilds/categories it generates into one of four places, in this order:

  1. An ebuild repository specified on the command-line with the --ov-output (-oO) option
  2. An ebuild repository named 'cross-${CTARGET}'
  3. An ebuild repository named 'crossdev'
  4. It then falls back on the ebuild repository having the lowest priority value in /etc/portage/repos.conf/
  5. If it falls back on ebuild repositories that have the same priority, it will use the first ebuild repository alphabetically

Most users will want to prevent crossdev from disturbing configured ebuild repositories. One solution is to create an ebuild repository for crossdev, in order to avoid it from choosing a seemingly random repository to store packages in:

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

Then instruct Portage and crossdev to use this ebuild repository:

FILE /etc/portage/repos.conf/crossdev.conf
location = /var/db/repos/crossdev
priority = 10
masters = gentoo
auto-sync = no


Please note that 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.


user $crossdev --help
Usage: crossdev [options] --target TARGET

    --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"'
    -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)

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
   - bfin
   - h8300
   - mingw64
   - mmix
   - msp430
   - nds32
   - nios2
   - xc16x
   - 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


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!
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


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

See also


  1. Gentoo Gitweb: "Crossdev Script"
  2. Crossdev was originally written by: Joshua Kinard (kumba)