crossdev

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

Resources
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]

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

Installation

Emerge

root #emerge --ask sys-devel/crossdev

Crossdev overlay

Warning
Using crossdev may "pollute" ebuild repositories, care must be taken to ensure crossdev environments use separate repositories.

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

  1. The command-line option: --ov-output (-oO)
  2. ${CROSSDEV_OVERLAY}
  3. cross-${CTARGET}
  4. crossdev

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

Usage

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.

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

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

user $crossdev --llvm --target aarch64-gentoo-linux-musl

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

See also

References

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