2021-06-29 17:30:05 +02:00
# dockcross
2021-06-29 16:44:11 +02:00
Cross compiling toolchains in Docker images.
2021-08-07 16:48:59 +02:00
[](https://github.com/dockcross/dockcross/actions?query=branch%3Amaster) [](https://github.com/dockcross/dockcross/actions/workflows/shellcheck.yml)
2021-08-07 17:00:19 +02:00
2021-08-07 16:59:09 +02:00
 
2021-06-29 16:44:11 +02:00
2021-06-29 17:30:05 +02:00
## Features
2021-06-29 16:44:11 +02:00
2022-05-13 15:44:28 +02:00
- 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.
- Recent [CMake ](https://cmake.org ) and ninja are precompiled.
2023-01-07 00:30:54 +01:00
- [Meson ](https://mesonbuild.com ) is pre-installed.
2022-05-13 15:44:28 +02:00
- [Conan.io ](https://www.conan.io ) can be used as a package manager.
- Toolchain files configured for CMake.
- Current directory is mounted as the container\'s workdir, `/work` .
- Works with the [Docker for Mac ](https://docs.docker.com/docker-for-mac/ ) and [Docker for Windows ](https://docs.docker.com/docker-for-windows/ ).
- Support using alternative container executor by setting **OCI_EXE** environment variable. By default, it searches for [docker ](https://www.docker.com ) and [podman ](https://podman.io ) executable.
- [crosstool-ng ](https://github.com/crosstool-ng/crosstool-ng ) and [buildroot ](https://github.com/buildroot/buildroot ) configuration files.
2021-06-29 16:44:11 +02:00
2021-06-29 17:30:05 +02:00
## Examples
2021-06-29 16:44:11 +02:00
2022-05-13 15:44:28 +02:00
1. `dockcross make` : Build the *Makefile* in the current directory.
2022-05-18 14:48:03 +02:00
2. `dockcross cmake -Bbuild -S. -GNinja` : Run CMake with a build directory `./build` for a *CMakeLists.txt* file in the current directory and generate `ninja` build configuration files.
2022-05-13 15:44:28 +02:00
3. `dockcross ninja -Cbuild` : Run ninja in the `./build` directory.
4. `dockcross bash -c '$CC test/C/hello.c -o hello'` : Build the *hello.c* file with the compiler identified with the `CC` environmental variable in the build environment.
5. `dockcross bash` : Run an interactive shell in the build environment.
2021-06-29 16:44:11 +02:00
2021-08-08 20:58:04 +02:00
Note that commands are executed verbatim. If any shell processing for environment variable expansion or redirection is required, please use
2022-05-13 15:44:28 +02:00
2021-08-07 16:39:31 +02:00
```bash
bash -c "< command args > "
```
2021-06-29 16:44:11 +02:00
2022-05-13 15:44:28 +02:00
## Contributing
See [CONTRIBUTING.md ](CONTRIBUTING.md ).
2021-06-29 17:30:05 +02:00
## Installation
2021-06-29 16:44:11 +02:00
2021-08-07 16:48:59 +02:00
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.
2021-06-29 16:44:11 +02:00
2021-08-07 16:48:59 +02:00
To install the helper script, run one of the images with no arguments, and redirect the output to a file:
2021-06-29 16:44:11 +02:00
2021-08-10 21:39:37 +02:00
```bash
docker run --rm CROSS_COMPILER_IMAGE_NAME > ./dockcross
chmod +x ./dockcross
mv ./dockcross ~/bin/
```
2021-06-29 16:44:11 +02:00
2021-08-07 16:48:59 +02:00
Where **CROSS_COMPILER_IMAGE_NAME** is the name of the cross-compiler toolchain Docker instance, e.g: **dockcross/linux-armv7** .
2021-06-29 16:44:11 +02:00
2021-08-10 21:32:27 +02:00
Only 64-bit x86_64 images are provided, a 64-bit x86_64 host system is required.
2021-06-29 16:44:11 +02:00
2021-06-29 17:30:05 +02:00
## Usage
2021-06-29 16:44:11 +02:00
For the impatient, here\'s how to compile a hello world for armv7:
2021-08-10 21:39:37 +02:00
```bash
2021-11-03 20:54:39 +01:00
git clone https://github.com/dockcross/dockcross.git
cd dockcross
2021-08-10 21:39:37 +02:00
docker run --rm dockcross/linux-armv7 > ./dockcross-linux-armv7
chmod +x ./dockcross-linux-armv7
./dockcross-linux-armv7 bash -c '$CC test/C/hello.c -o hello_arm'
```
2021-06-29 16:44:11 +02:00
2021-08-07 16:48:59 +02:00
Note how invoking any toolchain command (make, gcc, etc.) is just a matter of prepending the **dockcross** script on the commandline:
2021-06-29 16:44:11 +02:00
2021-08-10 21:39:37 +02:00
```bash
./dockcross-linux-armv7 [command] [args...]
```
2021-06-29 16:44:11 +02:00
2021-08-07 16:48:59 +02:00
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.
2021-06-29 16:44:11 +02:00
2021-08-07 16:36:19 +02:00
## Summary cross compilers
2021-08-07 17:21:08 +02:00
| Image name | Target arch | Compiler | Target OS |
2021-08-07 16:36:19 +02:00
|:-------:|:--------:|:------:|:-----:|
| dockcross/base | - | - | - |
2021-08-09 21:37:16 +02:00
| dockcross/android-arm | ARMv7 | Clang | Android |
2021-08-07 16:36:19 +02:00
| dockcross/android-arm64 | ARMv8 | Clang | Android |
2021-08-09 21:37:16 +02:00
| dockcross/android-x86 | x86 | Clang | Android |
| dockcross/android-x86_64 | x86_64 | Clang | Android |
| dockcross/linux-arm64 | ARMv8 | GCC | Linux |
2021-09-20 12:55:18 +02:00
| dockcross/linux-arm64-lts | ARMv8 | GCC 8.5.0 + Glibc 2.27 | Linux |
2021-08-21 21:09:48 +02:00
| dockcross/linux-arm64-full | ARMv8 | GCC + libs | Linux |
2021-08-09 21:37:16 +02:00
| dockcross/linux-arm64-musl | ARMv8 | GCC + musl | Linux |
| dockcross/linux-armv5 | ARMv5 | GCC | Linux |
| dockcross/linux-armv5-musl | ARMv5 | GCC + musl | Linux |
2022-02-01 16:29:54 +01:00
| dockcross/linux-armv5-uclibc | ARMv5 | GCC + uclibc | Linux |
2021-08-09 21:37:16 +02:00
| dockcross/linux-armv6 | ARMv6 | GCC | Linux |
2021-09-20 12:55:18 +02:00
| dockcross/linux-armv6-lts | ARMv6 | GCC 8.5.0 + Glibc 2.28 | Linux |
2021-08-09 21:37:16 +02:00
| dockcross/linux-armv6-musl | ARMv6 | GCC + musl | Linux |
| dockcross/linux-armv7 | ARMv7 | GCC | Linux |
2021-10-15 21:10:39 +02:00
| dockcross/linux-armv7-lts | ARMv7 | GCC 8.5.0 + Glibc 2.28 | Linux |
2021-08-09 21:37:16 +02:00
| dockcross/linux-armv7a | ARMv7a | GCC | Linux |
| dockcross/linux-armv7l-musl | ARMv7l | GCC + musl | Linux |
| dockcross/linux-mips | mips | GCC | Linux |
2023-03-29 11:40:36 +02:00
| dockcross/linux-mips-uclibc | mips | GCC + uclibc | Linux |
2022-04-24 22:50:06 +02:00
| dockcross/linux-mips-lts | mips | GCC 8.5.0 + Glibc 2.28 | Linux |
2022-04-24 22:24:30 +02:00
| dockcross/linux-mipsel-lts | mipsel | GCC 8.5.0 + Glibc 2.28 | Linux |
2021-08-09 21:37:16 +02:00
| dockcross/linux-s390x | s390x | GCC | Linux |
| dockcross/linux-ppc64le | ppc64le | GCC | Linux |
2023-09-21 23:56:23 +02:00
| dockcross/linux-ppc64le-lts | ppc64le | GCC 8.5.0 + Glibc 2.28 | Linux |
2021-08-09 21:37:16 +02:00
| dockcross/linux-riscv32 | riscv32 | GCC | Linux |
| dockcross/linux-riscv64 | riscv64 | GCC | Linux |
| dockcross/linux-m68k-uclibc | m68k | GCC + uclibc | Linux |
| dockcross/linux-xtensa-uclibc | xtensa | GCC + uclibc | Linux |
2022-07-05 17:45:51 +02:00
| dockcross/manylinux_2_28-x64 | x86_64 | GCC | Linux |
2021-08-09 21:37:16 +02:00
| dockcross/manylinux2014-x86 | x86 | GCC | Linux |
| dockcross/manylinux2014-x64 | x86_64 | GCC | Linux |
2022-10-31 16:43:48 +01:00
| dockcross/linux-i686 | x86 | GCC | Linux |
2021-08-09 21:37:16 +02:00
| dockcross/linux-x86 | x86 | GCC | Linux |
| dockcross/linux-x64 | x86_64 | GCC | Linux |
2021-09-20 12:38:23 +02:00
| dockcross/linux-x86_64-full | x86_64 | GCC + libs | Linux |
2021-08-09 21:37:16 +02:00
| dockcross/linux-x64-clang | x86_64 | Clang | Linux |
2021-08-12 22:37:43 +02:00
| dockcross/linux-x64-tinycc | x86_64 | tinycc + GCC | Linux |
2021-10-08 23:07:09 +02:00
| dockcross/web-wasm | Wasm | LLVM | Web (JS) |
| dockcross/web-wasi | Wasm | LLVM | Web (Universal) |
2024-04-02 19:32:34 +02:00
| dockcross/web-wasi-threads | Wasm | LLVM | Web (Universal) |
2021-08-09 21:37:16 +02:00
| dockcross/windows-shared-x86 | x86 | GCC | Windows |
| dockcross/windows-shared-x64 | x86_64 | GCC | Windows |
| dockcross/windows-shared-x64-posix | x86_64 | GCC | Windows |
| dockcross/windows-static-x86 | x86 | GCC | Windows |
| dockcross/windows-static-x64 | x86_64 | GCC | Windows |
| dockcross/windows-static-x64-posix | x86_64 | GCC | Windows |
2021-08-11 01:18:07 +02:00
| dockcross/windows-armv7 | ARMv7 | Clang | Windows |
| dockcross/windows-arm64 | ARMv8 | Clang | Windows |
2021-08-07 16:36:19 +02:00
2021-10-18 10:52:20 +02:00
The list of docker images that are **no longer maintained** .
2021-10-18 10:46:38 +02:00
2022-02-05 21:53:20 +01:00
| Image name | Target arch | Compiler | Target OS | End of life (EOL) |
|:-------:|:--------:|:------:|:-----:|:-----:|
2022-07-07 20:26:03 +02:00
| dockcross/manylinux-x86 | x86 | GCC | manylinux | [2019-05-22][1e0e89814] |
| dockcross/manylinux-x64 | x86 | GCC | manylinux | [2019-05-22][1e0e89814] |
| dockcross/linux-mipsel | mipsel | GCC 4.9 | Debian 8 | [2021-06-27][a30e76d5c] |
| dockcross/manylinux1-x86 | x86 | GCC | manylinux | [2021-08-05][54f73cbb6] |
| dockcross/manylinux1-x64 | x86_64 | GCC| manylinux | [2021-08-05][54f73cbb6] |
| dockcross/manylinux2010-x86 | x86 | GCC | manylinux | [2021-08-05][54f73cbb6] |
| dockcross/manylinux2010-x64 | x86_64 | GCC | manylinux | [2021-08-05][54f73cbb6] |
| dockcross/manylinux_2_24-x64 | x86_64 | GCC | manylinux | [2022-07-05][ada2c8dad], [pypa/manylinux#1332][manylinux_2_24-eol] |
2022-02-05 21:53:20 +01:00
[1e0e89814]: https://github.com/dockcross/dockcross/commit/1e0e89814
[a30e76d5c]: https://github.com/dockcross/dockcross/commit/a30e76d5c
[54f73cbb6]: https://github.com/dockcross/dockcross/commit/54f73cbb6
2022-07-07 20:26:03 +02:00
[ada2c8dad]: https://github.com/dockcross/dockcross/commit/ada2c8dad
2022-07-05 17:45:51 +02:00
[manylinux_2_24-eol]: https://github.com/pypa/manylinux/issues/1332#issuecomment-1157666846
2021-10-18 10:46:38 +02:00
2021-06-29 17:30:05 +02:00
## Cross compilers
2021-06-29 16:44:11 +02:00
### dockcross/base
2021-08-07 16:39:31 +02:00
  
2021-06-29 17:30:05 +02:00
2024-04-04 12:18:43 +02:00
Base image for other toolchain images. From Debian Bookworm with GCC, make, autotools, CMake, Ninja, Git, and Python.
2021-06-29 16:44:11 +02:00
### dockcross/android-arm
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
The Android NDK standalone toolchain for the arm architecture.
2021-06-29 16:44:11 +02:00
### dockcross/android-arm64
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
The Android NDK standalone toolchain for the arm64 architecture.
2021-06-29 16:44:11 +02:00
### dockcross/android-x86
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
The Android NDK standalone toolchain for the x86 architecture.
2021-06-29 16:44:11 +02:00
### dockcross/android-x86_64
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
The Android NDK standalone toolchain for the x86_64 architecture.
2021-06-29 16:44:11 +02:00
### dockcross/linux-arm64
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
2021-08-07 16:59:09 +02:00
Cross compiler for the 64-bit ARM platform on Linux, also known as AArch64.
2021-06-29 16:44:11 +02:00
2021-09-20 12:55:18 +02:00
### dockcross/linux-arm64-lts
 
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.
2021-08-10 21:32:27 +02:00
### dockcross/linux-arm64-full
 
Cross compiler for the 64-bit ARM platform on Linux, with cross-libs: SDL2, OpenSSL, Boost, OpenCV and Qt5 (minimal).
2021-06-29 16:44:11 +02:00
### dockcross/linux-arm64-musl
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
Cross compiler for the 64-bit ARM platform on Linux (also known as
AArch64), using [musl ](https://www.musl-libc.org/ ) as base \"libc\".
2021-06-29 16:44:11 +02:00
### dockcross/linux-armv5
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
Linux armv5 cross compiler toolchain for legacy devices like the
Parrot AR Drone.
2021-06-29 16:44:11 +02:00
### dockcross/linux-armv5-musl
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
Linux armv5 cross compiler toolchain using
[musl ](https://www.musl-libc.org/ ) as base \"libc\".
2021-06-29 16:44:11 +02:00
2022-02-01 16:03:56 +01:00
### dockcross/linux-armv5-uclibc
 
Linux armv5 cross compiler toolchain for legacy devices like wrt routers
Linux kernel 2.6
[uclibc ](https://www.uclibc.org/ ) as base \"libc\".
2021-06-29 16:44:11 +02:00
### dockcross/linux-armv6
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
2021-08-06 20:23:31 +02:00
Linux ARMv6 cross compiler toolchain for the Raspberry Pi
### dockcross/linux-armv6-lts
2021-08-07 16:39:31 +02:00
 
2021-08-06 20:23:31 +02:00
Linux ARMv6 cross compiler toolchain for the Raspberry Pi (Debian buster...)
2021-06-29 16:44:11 +02:00
### dockcross/linux-armv6-musl
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
Linux ARMv6 cross compiler toolchain for the Raspberry Pi, etc,
using [musl ](https://www.musl-libc.org/ ) as base \"libc\".
2021-06-29 16:44:11 +02:00
### dockcross/linux-armv7
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
Generic Linux armv7 cross compiler toolchain.
2021-06-29 16:44:11 +02:00
2021-10-15 21:10:39 +02:00
### dockcross/linux-armv7-lts
 
Linux ARMv7 cross compiler toolchain for the Raspberry Pi (Debian buster...)
2021-06-29 16:44:11 +02:00
### dockcross/linux-armv7a
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
Toolchain configured for ARMv7-A used in Beaglebone Black single
board PC with TI SoC AM3358 on board, Cortex-A8.
2021-06-29 16:44:11 +02:00
### dockcross/linux-armv7l-musl
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
Toolchain configured for ARMv7-L, using
[musl ](https://www.musl-libc.org/ ) as base \"libc\".
2021-06-29 16:44:11 +02:00
### dockcross/linux-mips
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
Linux mips cross compiler toolchain for big endian 32-bit hard float
MIPS GNU systems.
2021-06-29 16:44:11 +02:00
2022-04-24 22:50:06 +02:00
### dockcross/linux-mips
 
2023-09-21 23:56:23 +02:00
Linux mips cross compiler toolchain for big endian 32-bit hard float MIPS GNU systems, with GCC 8.5.0, Glibc 2.28 ....
2022-04-24 22:50:06 +02:00
2022-04-22 15:18:28 +02:00
### dockcross/linux-mipsel-lts
 
2022-04-22 20:20:34 +02:00
Linux mips cross compiler toolchain for little endian 32-bit soft float
2022-04-22 15:18:28 +02:00
MIPS GNU systems.
2022-04-24 22:50:06 +02:00
2021-06-29 16:44:11 +02:00
### dockcross/linux-s390x
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
Linux s390x cross compiler toolchain for S390X GNU systems.
2021-06-29 16:44:11 +02:00
2021-07-02 22:44:47 +02:00
### dockcross/linux-riscv64
2021-08-07 16:39:31 +02:00
 
2021-07-02 22:44:47 +02:00
Linux risc-v 64bit cross compiler toolchain for risc-v 64bit GNU systems.
### dockcross/linux-riscv32
2021-08-07 16:39:31 +02:00
 
2021-07-02 22:44:47 +02:00
Linux risc-v 32bit cross compiler toolchain for risc-v 32bit GNU systems.
2021-07-02 22:42:07 +02:00
### dockcross/linux-m68k-uclibc
2021-08-07 16:39:31 +02:00
 
2021-07-02 22:42:07 +02:00
Linux m68k cross compiler toolchain for m68k GNU systems (http://www.mac.linux-m68k.org/ and http://www.linux-m68k.org/).
2021-06-29 16:44:11 +02:00
### dockcross/linux-ppc64le
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
2022-10-31 19:14:33 +01:00
Linux PowerPC 64 little endian cross compiler toolchain for the POWER8, etc.
2021-06-29 16:44:11 +02:00
2023-09-21 23:56:23 +02:00
### dockcross/linux-ppc64le-lts
 
Linux PowerPC 64 little endian cross compiler toolchain for the POWER8, with GCC 8.5.0, Glibc 2.28 ....
2021-06-29 16:44:11 +02:00
### dockcross/linux-x64
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
2021-08-07 16:59:09 +02:00
Linux x86_64/amd64 compiler. Since the Docker image is natively x86_64, this is not actually a cross compiler.
2021-06-29 16:44:11 +02:00
2021-08-21 21:09:48 +02:00
### dockcross/linux-x86_64-full
 
Linux x86_64/amd64 compiler with libs: SDL2, OpenSSL, Boost, OpenCV and Qt5 (minimal).
2021-06-29 16:44:11 +02:00
### dockcross/linux-x64-clang
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
2021-08-07 16:59:09 +02:00
Linux clang x86_64/amd64 compiler. Since the Docker image is natively x86_64, this is not actually a cross compiler.
2021-06-29 16:44:11 +02:00
### dockcross/linux-x86
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
2022-10-31 16:43:48 +01:00
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.
2021-06-29 16:44:11 +02:00
2021-08-11 10:58:03 +02:00
### dockcross/linux-x64-tinycc
 
Linux tcc compiler for C compiler, and GCC for C++ compiler, for linux x86_64/amd64 arch.
2022-10-31 16:43:48 +01:00
### dockcross/linux-i686
 
Standalone Linux i686 cross compiler.
2022-07-05 17:45:51 +02:00
### dockcross/manylinux_2_28-x64
2022-06-22 01:23:22 +02:00
2022-07-05 17:45:51 +02:00
 
2022-06-22 01:23:22 +02:00
2022-07-05 17:45:51 +02:00
Docker [manylinux_2_28 ](https://github.com/pypa/manylinux ) image for building Linux x86_64 / amd64 [Python wheel packages ](http://pythonwheels.com/ ). 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, and [scikit-build ](http://scikit-build.org ). For CMake, it sets **MANYLINUX_2_28** to \"TRUE\" in the toolchain.
2022-06-22 01:23:22 +02:00
2021-06-29 16:44:11 +02:00
### dockcross/manylinux2014-x64
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
2021-08-07 16:59:09 +02:00
Docker [manylinux2014 ](https://github.com/pypa/manylinux ) image for building Linux x86_64 / amd64 [Python wheel packages ](http://pythonwheels.com/ ). 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, and [scikit-build ](http://scikit-build.org ). For CMake, it sets **MANYLINUX2014** to \"TRUE\" in the toolchain.
2021-06-29 16:44:11 +02:00
### dockcross/manylinux2014-x86
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
2021-08-07 16:59:09 +02:00
Docker [manylinux2014 ](https://github.com/pypa/manylinux ) image for building Linux i686 [Python wheel packages ](http://pythonwheels.com/ ). 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, and [scikit-build ](http://scikit-build.org ). For CMake, it sets **MANYLINUX2014** to \"TRUE\" in the toolchain.
2021-06-29 16:44:11 +02:00
2021-08-20 14:44:22 +02:00
### dockcross/manylinux2014-aarch64
 
Docker [manylinux2014 ](https://github.com/pypa/manylinux ) image for building Linux aarch64 / arm64 [Python wheel packages ](http://pythonwheels.com/ ). 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, and [scikit-build ](http://scikit-build.org ). For CMake, it sets **MANYLINUX2014** to \"TRUE\" in the toolchain.
2021-06-29 16:44:11 +02:00
### dockcross/web-wasm
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
2021-10-08 23:07:09 +02:00
The [Emscripten ](https://emscripten.org/ ) [WebAssembly ](https://webassembly.org/ )/JavaScript cross compiler.
### dockcross/web-wasi
 
The [WebAssembly System Interface (WASI) ](https://wasi.dev/ ) SDK LLVM/Clang/WASI Sysroot cross compiler.
2021-06-29 16:44:11 +02:00
2024-04-02 19:32:34 +02:00
### dockcross/web-wasi-threads
 
The [WebAssembly System Interface (WASI) ](https://wasi.dev/ ) SDK LLVM/Clang/WASI Sysroot cross compiler with the toolchain configured to enable the wasm threading proposal.
2021-06-29 16:44:11 +02:00
### dockcross/windows-static-x64
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
64-bit Windows cross-compiler based on [MXE/MinGW-w64 ](https://mxe.cc/ ) with win32 threads and static
linking.
2021-06-29 16:44:11 +02:00
### dockcross/windows-static-x64-posix
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
64-bit Windows cross-compiler based on [MXE/MinGW-w64 ](https://mxe.cc/ ) with posix threads and static
linking.
2021-06-29 16:44:11 +02:00
### dockcross/windows-static-x86
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
32-bit Windows cross-compiler based on [MXE/MinGW-w64 ](https://mxe.cc/ ) with win32 threads and static linking.
2021-06-29 16:44:11 +02:00
### dockcross/windows-shared-x64
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
64-bit Windows cross-compiler based on [MXE/MinGW-w64 ](https://mxe.cc/ ) with win32 threads and dynamic linking.
2021-06-29 16:44:11 +02:00
### dockcross/windows-shared-x64-posix
2021-08-07 16:39:31 +02:00
 
2021-06-29 17:30:05 +02:00
64-bit Windows cross-compiler based on [MXE/MinGW-w64 ](https://mxe.cc/ ) with posix threads and dynamic linking.
2021-06-29 16:44:11 +02:00
### dockcross/windows-shared-x86
2021-08-07 16:39:31 +02:00
 
2021-06-29 16:44:11 +02:00
2021-06-29 17:30:05 +02:00
32-bit Windows cross-compiler based on [MXE/MinGW-w64 ](https://mxe.cc/ ) with win32 threads and dynamic linking.
2021-08-11 01:18:07 +02:00
### dockcross/windows-armv7
 
ARMv7 32-bit Windows cross-compiler based on [LLVM/MinGW-w64 ](https://github.com/mstorsjo/llvm-mingw )
### dockcross/windows-arm64
 
ARMv8 64-bit Windows cross-compiler based on [llvm-mingw ](https://github.com/mstorsjo/llvm-mingw )
2021-06-29 17:30:05 +02:00
## Articles
2021-06-29 16:44:11 +02:00
- [dockcross: C++ Write Once, Run
Anywhere](https://nbviewer.jupyter.org/format/slides/github/dockcross/cxx-write-once-run-anywhere/blob/master/dockcross_CXX_Write_Once_Run_Anywhere.ipynb#/)
- [Cross-compiling binaries for multiple architectures with
Docker](https://web.archive.org/web/20170912153531/http://blogs.nopcode.org/brainstorm/2016/07/26/cross-compiling-with-docker)
2021-06-29 17:30:05 +02:00
## Built-in update commands
2021-06-29 16:44:11 +02:00
A special update command can be executed that will update the source
cross-compiler Docker image or the dockcross script itself.
- `dockcross [--] command [args...]` : Forces a command to run inside
the 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 docker
image.
- `dockcross update-script` : Update the installed dockcross script
with the one bundled in the image.
- `dockcross update` : Update both the docker image, and the dockcross
script.
2021-06-29 17:30:05 +02:00
## Download all images
2021-06-29 16:44:11 +02:00
To easily download all images, the convenience target `display_images`
could be used:
2021-08-10 21:39:37 +02:00
```bash
curl https://raw.githubusercontent.com/dockcross/dockcross/master/Makefile -o dockcross-Makefile
for image in $(make -f dockcross-Makefile display_images); do
echo "Pulling dockcross/$image"
docker pull dockcross/$image
done
```
2021-06-29 16:44:11 +02:00
2021-06-29 17:30:05 +02:00
## Install all dockcross scripts
2021-06-29 16:44:11 +02:00
To automatically install in `~/bin` the dockcross scripts for each
images already downloaded, the convenience target `display_images` could
be used:
2021-08-10 21:39:37 +02:00
```bash
curl https://raw.githubusercontent.com/dockcross/dockcross/master/Makefile -o dockcross-Makefile
for image in $(make -f dockcross-Makefile display_images); do
if [[ $(docker images -q dockcross/$image) == "" ]]; then
echo "~/bin/dockcross-$image skipping: image not found locally"
continue
fi
echo "~/bin/dockcross-$image ok"
docker run dockcross/$image > ~/bin/dockcross-$image & & \
chmod u+x ~/bin/dockcross-$image
done
```
2021-06-29 16:44:11 +02:00
2021-06-29 17:30:05 +02:00
## Dockcross configuration
2021-06-29 16:44:11 +02:00
The following environmental variables and command-line options are used.
In all cases, the command-line option overrides the environment
variable.
2021-06-29 17:30:05 +02:00
### DOCKCROSS_CONFIG / \--config\|-c \<path-to-config-file>
2021-06-29 16:44:11 +02:00
This file is sourced, if it exists, before executing the rest of the
dockcross script.
Default: `~/.dockcross`
2021-06-29 17:30:05 +02:00
### DOCKCROSS_IMAGE / \--image\|-i \<docker-image-name>
2021-06-29 16:44:11 +02:00
The Docker cross-compiler image to run.
Default: Image with which the script was created.
2021-06-29 17:30:05 +02:00
### DOCKCROSS_ARGS / \--args\|-a \<docker-run-args>
2021-06-29 16:44:11 +02:00
2021-08-07 16:45:17 +02:00
Extra arguments to pass to the `docker run` command. Quote the entire set of args if they contain spaces.
2021-06-29 16:44:11 +02:00
2021-06-29 17:30:05 +02:00
## Per-project dockcross configuration
2021-06-29 16:44:11 +02:00
2021-08-07 16:45:17 +02:00
If a shell script named `.dockcross` is found in the current directory where the dockcross script is started, it is executed before the dockcross script `command` argument. The shell script is expected to have a shebang like `#!/usr/bin/env bash` .
2021-06-29 16:44:11 +02:00
For example, commands like
`git config --global advice.detachedHead false` can be added to this
script.
2021-06-29 17:30:05 +02:00
## How to extend Dockcross images
2021-06-29 16:44:11 +02:00
In order to extend Dockcross images with your own commands, one must:
1. Use `FROM dockcross/<name_of_image>` .
2. Set `DEFAULT_DOCKCROSS_IMAGE` to a name of the tag you\'re planning
to use for the image. This tag must then be used during the build
phase, unless you mean to pass the resulting helper script the
`DOCKCROSS_IMAGE` argument.
An example Dockerfile would be:
2021-08-10 21:39:37 +02:00
```
FROM dockcross/linux-armv7
2021-06-29 16:44:11 +02:00
2021-08-10 21:39:37 +02:00
ENV DEFAULT_DOCKCROSS_IMAGE my_cool_image
2022-11-29 21:30:29 +01:00
RUN apt-get install -y nano
2021-08-10 21:39:37 +02:00
```
2021-06-29 16:44:11 +02:00
And then in the shell:
2021-08-10 21:39:37 +02:00
```
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.
```
2021-06-29 16:44:11 +02:00
2021-08-07 16:45:17 +02:00
## What is the difference between **dockcross** and **dockbuild** ?
The key difference is that [dockbuild ](https://github.com/dockbuild/dockbuild#readme ) images do **NOT** provide a [toolchain file ](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html ) but they use the same method to conveniently isolate the build environment as [dockcross ](https://github.com/dockcross/dockcross#readme ).
**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.
2021-06-29 16:44:11 +02:00
2022-12-16 16:07:56 +01:00
## Build images by yourself
2024-02-07 05:26:07 +01:00
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).
2022-12-16 16:07:56 +01:00
To overcome this limitation, you can build your own images on non-amd64 architectures. To do so, you can use the `Makefile` provided in this repository. For example, to build the `linux-armv7` image, and provided that your Docker hub organization name is `ACME` , you can run:
```bash
$ make ORG=ACME base
$ make ORG=ACME linux-armv7
```
This will create the Docker images `ACME/base` and `ACME/linux-armv7` , so that you can later launch a container using the `ACME/linux-armv7` image:
```
$ docker run --rm ACME/linux-armv7 uname -a
Linux 89b164ee8d90 5.15.49-linuxkit #1 SMP PREEMPT Tue Sep 13 07:51:32 UTC 2022 aarch64 GNU/Linux
```
Note that the architecture is now `aarch64` instead of `amd64` , so it runs natively on the Apple M1.
2021-06-29 16:44:11 +02:00
\-\--
2021-08-07 16:45:17 +02:00
Credits:
2022-05-13 15:44:28 +02:00
2021-08-07 16:45:17 +02:00
- [sdt/docker-raspberry-pi-cross-compiler ](https://github.com/sdt/docker-raspberry-pi-cross-compiler ), who invented the base of the **dockcross** script.
- [https://github.com/steeve/cross-compiler ](https://github.com/steeve/cross-compiler ),
