crossdev
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/crossdevCrossdev overlay
Using crossdev may "pollute" ebuild repositories, care must be taken to ensure crossdev environments use separate repositories.
eselect creation
To use eselect-repository to create the repository then first install the package.
root #emerge --ask app-eselect/eselect-repositoryThen, create the repository with:
root #eselect repository create crossdevManual creation
In order of precedence, crossdev will make use of a portage repository specified by:
- The command-line option:
--ov-output(-oO) ${CROSSDEV_OVERLAY}cross-${CTARGET}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:
/var/db/repos/crossdev/metadata/layout.confmasters = gentoo
thin-manifests = true
Instruct Portage, and subsequently crossdev, to use the new ebuild repository by enabling it:
/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 --helpUsage: 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 helpTarget (-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
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.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-muslBuild 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.0Setting 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.
Emerge a single package
To emerge a single package then just run:
root #emerge-aarch64-unknown-linux-gnu --ask app-editors/nanoReplacing 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 @systemBinary packages
By default crossdev will create packages in /usr/aarch64-unknown-linux-gnu/var/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.
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.
Removal
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!
To remove a LLVM/Clang crossdev target you need to explicitly pass
--llvm.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/crossdevSee also
- ARM — compiling code for an ARM processor, taking advantage of its FPU.
- Cross build environment — provides instructions on creating a cross build environment using crossdev.
- Catalyst — a tool to build stage files and live-images for Gentoo
- Creating a cross-compiler (Embedded Handbook)
- Joshua Kinard (kumba) - original crossdev author.
References
- ↑ Gentoo Gitweb: "Crossdev Script"
- ↑ crossdev was originally written by: Joshua Kinard (kumba)