Repository files navigation

Cross compiling toolchains in Docker images.

• Pre-built and configured toolchains for cross compiling.
• Most images also contain an emulator for the target system.
• Clean separation of build tools, source code, and build artifacts.
• Commands in the container are run as the calling user, so that any created files have the expected ownership, (i.e. not root).
• Make variables (CC,CXX,LD,AS etc) are set to point to the appropriate tools in the container.
• RecentCMake and ninja are precompiled.
• Meson is pre-installed.
• Conan.io can be used as a package manager.
• Toolchain files configured for CMake.
• Rustup is pre-installed.
• Some images (e.g. android) are configured for Rust.
• Current directory is mounted as the container's workdir,/work.
• Works with theDocker for Mac andDocker for Windows.
• Support using alternative container executor by settingOCI_EXE environment variable. By default, it searches fordocker andpodman executable.
• crosstool-ng andbuildroot configuration files.

1. dockcross make: Build theMakefile in the current directory.
2. dockcross cmake -Bbuild -S. -GNinja: Run CMake with a build directory./build for aCMakeLists.txt file in the current directory and generateninja build configuration files.
3. dockcross ninja -Cbuild: Run ninja in the./build directory.
4. dockcross bash -c '$CC test/C/hello.c -o hello': Build thehello.c file with the compiler identified with theCC environmental variable in the build environment.
5. dockcross bash: Run an interactive shell in the build environment.
6. dockcross cargo build: Build the current Rust project.

Note that commands are executed verbatim. If any shell processing for environment variable expansion or redirection is required, please use

bash -c"<command args>"

SeeCONTRIBUTING.md.

This image does not need to be run manually. Instead, there is a helper script to execute build commands on source code existing on the local host filesystem. This script is bundled with the image.

To install the helper script, run one of the images with no arguments, and redirect the output to a file:

docker run --rm CROSS_COMPILER_IMAGE_NAME> ./dockcrosschmod +x ./dockcrossmv ./dockcross~/bin/

WhereCROSS_COMPILER_IMAGE_NAME is the name of the cross-compiler toolchain Docker instance, e.g:dockcross/linux-armv7.

Only 64-bit x86_64 images are provided, a 64-bit x86_64 host system is required.

For the impatient, here's how to compile a hello world for armv7:

git clone https://github.com/dockcross/dockcross.gitcd dockcrossdocker run --rm dockcross/linux-armv7> ./dockcross-linux-armv7chmod +x ./dockcross-linux-armv7./dockcross-linux-armv7 bash -c'$CC test/C/hello.c -o hello_arm'

Note how invoking any toolchain command (make, gcc, etc.) is just a matter of prepending thedockcross script on the commandline:

./dockcross-linux-armv7 [command] [args...]

The dockcross script will execute the given command-line inside the container, along with all arguments passed after the command. Commands that evaluate environmental variables in the image, like$CC or$CXX above, should be executed in [bash -c]. The present working directory is mounted within the image, which can be used to make source code available in the Docker container.

The list of docker images that areno longer maintained.

Base image for other toolchain images. From Debian Bookworm with GCC, make, autotools, CMake, Ninja, Git, and Python.

The Android NDK standalone toolchain for the arm architecture.

The Android NDK standalone toolchain for the arm64 architecture.

The Android NDK standalone toolchain for the x86 architecture.

The Android NDK standalone toolchain for the x86_64 architecture.

Cross compiler for the 64-bit ARM platform on Linux, also known as AArch64.

Cross compiler for the 64-bit ARM platform on Linux, also known as AArch64, with Long-term support (For Ubuntu 18.04 or Debian Buster).With GCC 8.5.0 and GLibc 2.27.

Cross compiler for the 64-bit ARM platform on Linux, with cross-libs: SDL2, OpenSSL, Boost, OpenCV and Qt5 (minimal).

Cross compiler for the 64-bit ARM platform on Linux (also known asAArch64), usingmusl as base "libc".

Linux armv5 cross compiler toolchain for legacy devices like theParrot AR Drone.

Linux armv5 cross compiler toolchain usingmusl as base "libc".

Linux armv5 cross compiler toolchain for legacy devices like wrt routersLinux kernel 2.6uclibc as base "libc".

Linux ARMv6 cross compiler toolchain for the Raspberry Pi

Linux ARMv6 cross compiler toolchain for the Raspberry Pi (Debian buster...)

Linux ARMv6 cross compiler toolchain for the Raspberry Pi, etc,usingmusl as base "libc".

Generic Linux armv7 cross compiler toolchain.

Linux ARMv7 cross compiler toolchain for the Raspberry Pi (Debian buster...)

Toolchain configured for ARMv7-A used in Beaglebone Black singleboard PC with TI SoC AM3358 on board, Cortex-A8.

Toolchain configured for ARMv7-L, usingmusl as base "libc".

Linux mips cross compiler toolchain for big endian 32-bit hard floatMIPS GNU systems.

Linux mips cross compiler toolchain for big endian 32-bit hard float MIPS GNU systems, with GCC 8.5.0, Glibc 2.28 ....

Linux mips cross compiler toolchain for little endian 32-bit soft floatMIPS GNU systems.

Linux s390x cross compiler toolchain for S390X GNU systems.

Linux risc-v 64bit cross compiler toolchain for risc-v 64bit GNU systems.

Linux risc-v 32bit cross compiler toolchain for risc-v 32bit GNU systems.

Linux m68k cross compiler toolchain for m68k GNU systems (http://www.mac.linux-m68k.org/ andhttp://www.linux-m68k.org/).

Linux PowerPC cross compiler toolchain for CPUs like the G3, G4, etc.

Linux PowerPC 64 little endian cross compiler toolchain for the POWER8, etc.

Linux PowerPC 64 little endian cross compiler toolchain for the POWER8, with GCC 8.5.0, Glibc 2.28 ....

Linux x86_64/amd64 compiler. Since the Docker image is natively x86_64, this is not actually a cross compiler.

Linux x86_64/amd64 compiler with libs: SDL2, OpenSSL, Boost, OpenCV and Qt5 (minimal).

Linux clang x86_64/amd64 compiler. Since the Docker image is natively x86_64, this is not actually a cross compiler.

Linux x86_64 32bit (i686) toolchain using gcc/g++ multilib. Multilib is a mechanism to support building and running code for different ABIs for the same CPU family on the host system. Most commonly it is used to support 32-bit code on 64-bit systems and 64-bit code on 32-bit systems with a 64-bit kernel. Since the Docker image is natively x86_64, this is not actually a cross compiler, it just adds capability to the existing host toolchain.

Linux tcc compiler for C compiler, and GCC for C++ compiler, for linux x86_64/amd64 arch.

Standalone Linux i686 cross compiler.

Dockermanylinux_2_28 image for building Linux x86_64 / amd64Python wheel packages. It includes Python 3.6, 3.7, 3.8, 3.9, 3.10 and 3.11. Also has support for the dockcross script, and it has installations of CMake, Ninja, andscikit-build. For CMake, it setsMANYLINUX_2_28 to "TRUE" in the toolchain.

Dockermanylinux_2_34 image for building Linux x86_64 / amd64Python wheel packages. It includes Python 3.8.10+, 3.9.5+, 3.10.0+. Also has support for the dockcross script, and it has installations of CMake, Ninja, andscikit-build. For CMake, it setsMANYLINUX_2_34 to "TRUE" in the toolchain.

Dockermanylinux2014 image for building Linux x86_64 / amd64Python wheel packages. It includes Python 3.5, 3.6, 3.7, 3.8, and 3.9. Also has support for the dockcross script, and it has installations of CMake, Ninja, andscikit-build. For CMake, it setsMANYLINUX2014 to "TRUE" in the toolchain.

Dockermanylinux2014 image for building Linux i686Python wheel packages. It includes Python 3.5, 3.6, 3.7, 3.8, and 3.9. Also has support for the dockcross script, and it has installations of CMake, Ninja, andscikit-build. For CMake, it setsMANYLINUX2014 to "TRUE" in the toolchain.

Dockermanylinux2014 image for building Linux aarch64 / arm64Python wheel packages. It includes Python 3.5, 3.6, 3.7, 3.8, and 3.9. Also has support for the dockcross script, and it has installations of CMake, Ninja, andscikit-build. For CMake, it setsMANYLINUX2014 to "TRUE" in the toolchain.

TheEmscriptenWebAssembly/JavaScript cross compiler.

TheWebAssembly System Interface (WASI) SDK LLVM/Clang/WASI Sysroot cross compiler.

TheWebAssembly System Interface (WASI) SDK LLVM/Clang/WASI Sysroot cross compiler with the toolchain configured to enable the wasm threading proposal.

64-bit Windows cross-compiler based onMXE/MinGW-w64 with win32 threads and staticlinking.

64-bit Windows cross-compiler based onMXE/MinGW-w64 with posix threads and staticlinking.

32-bit Windows cross-compiler based onMXE/MinGW-w64 with win32 threads and static linking.

64-bit Windows cross-compiler based onMXE/MinGW-w64 with win32 threads and dynamic linking.

64-bit Windows cross-compiler based onMXE/MinGW-w64 with posix threads and dynamic linking.

32-bit Windows cross-compiler based onMXE/MinGW-w64 with win32 threads and dynamic linking.

ARMv7 32-bit Windows cross-compiler based onLLVM/MinGW-w64

ARMv8 64-bit Windows cross-compiler based onllvm-mingw

• dockcross: C++ Write Once, RunAnywhere
• Cross-compiling binaries for multiple architectures withDocker

A special update command can be executed that will update the sourcecross-compiler Docker image or the dockcross script itself.

• dockcross [--] command [args...]: Forces a command to run insidethe container (in case of a name clash with a built-in command), use-- before the command.
• dockcross update-image: Fetch the latest version of the dockerimage.
• dockcross update-script: Update the installed dockcross scriptwith the one bundled in the image.
• dockcross update: Update both the docker image, and the dockcrossscript.

To easily download all images, the convenience targetdisplay_imagescould be used:

curl https://raw.githubusercontent.com/dockcross/dockcross/master/Makefile -o dockcross-Makefileforimagein$(make -f dockcross-Makefile display_images);doecho"Pulling dockcross/$image"  docker pull dockcross/$imagedone

To automatically install in~/bin the dockcross scripts for eachimages already downloaded, the convenience targetdisplay_images couldbe used:

curl https://raw.githubusercontent.com/dockcross/dockcross/master/Makefile -o dockcross-Makefileforimagein$(make -f dockcross-Makefile display_images);doif [[$(docker images -q dockcross/$image)=="" ]];thenecho"~/bin/dockcross-$image skipping: image not found locally"continuefiecho"~/bin/dockcross-$image ok"  docker run dockcross/$image>~/bin/dockcross-$image&& \  chmod u+x~/bin/dockcross-$imagedone

The following environmental variables and command-line options are used.In all cases, the command-line option overrides the environmentvariable.

This file is sourced, if it exists, before executing the rest of thedockcross script.

Default:~/.dockcross

The Docker cross-compiler image to run.

Default: Image with which the script was created.

Extra arguments to pass to thedocker run command. Quote the entire set of args if they contain spaces.

If a shell script named.dockcross is found in the current directory where the dockcross script is started, it is executed before the dockcross scriptcommand argument. The shell script is expected to have a shebang like#!/usr/bin/env bash.

For example, commands likegit config --global advice.detachedHead false can be added to thisscript.

In order to extend Dockcross images with your own commands, one must:

1. UseFROM dockcross/<name_of_image>.
2. SetDEFAULT_DOCKCROSS_IMAGE to a name of the tag you're planningto use for the image. This tag must then be used during the buildphase, unless you mean to pass the resulting helper script theDOCKCROSS_IMAGE argument.

An example Dockerfile would be:

FROM dockcross/linux-armv7ENV DEFAULT_DOCKCROSS_IMAGE=my_cool_imageRUN apt-get install -y nano

And then in the shell:

docker build -t my_cool_image .                   ## Builds the dockcross image.docker run my_cool_image > linux-armv7                ## Creates a helper script named linux-armv7.chmod +x linux-armv7                          ## Gives the script execution permission../linux-armv7 bash                            ## Runs the helper script with the argument "bash", which starts an interactive container using your extended image.

The key difference is thatdockbuild images doNOT provide atoolchain file but they use the same method to conveniently isolate the build environment asdockcross.

dockbuild is used to build binaries for Linux x86_64/amd64 that will work across most Linux distributions.dockbuild performs a native Linux build where the host build system is a Linux x86_64 / amd64 Docker image (so that it can be used for building binaries on any system which can run Docker images) and the target runtime system is Linux x86_x64/ amd64.

dockcross is used to build binaries for many different platforms.dockcross performs a cross compilation where the host build system is a Linux x86_64 / amd64 Docker image (so that it can be used for building binaries on any system which can run Docker images) and the target runtime system varies.

Prebuilt images available on Docker hub are single architecture amd64 images. Those images work even on different architectures: for example, if you run a dockcross image on Docker running on an Apple M1, the image will run in emulation mode, meaning that it will still work as expected, although it will be slower than running on native hardware (you can expect a factor or 10 or more).

To overcome this limitation, you can build your own images on non-amd64 architectures. To do so, you can use theMakefile provided in this repository. For example, to build thelinux-armv7 image, and provided that your Docker hub organization name isACME, you can run:

$ make ORG=ACME base$ make ORG=ACME linux-armv7

This will create the Docker imagesACME/base andACME/linux-armv7, so that you can later launch a container using theACME/linux-armv7 image:

$ docker run --rm ACME/linux-armv7 uname -aLinux 89b164ee8d90 5.15.49-linuxkit #1 SMP PREEMPT Tue Sep 13 07:51:32 UTC 2022 aarch64 GNU/Linux

Note that the architecture is nowaarch64 instead ofamd64, so it runs natively on the Apple M1.

---

For creating multi-architecture container images, this project usesmanifest-tool to create and manage manifest lists that combine platform-specific images into a single multi-platform reference. This allows container runtimes to automatically select the appropriate image based on the target architecture.

The multi-architecture images are built on different architectures (amd64 and arm64) and then combined using manifest-tool'spush from-args command, which creates manifest lists pointing to the individual platform-specific images.

Credits:

• sdt/docker-raspberry-pi-cross-compiler, who invented the base of thedockcross script.
• https://github.com/steeve/cross-compiler,