Cross compiling toolchains in Docker images
Go to file
Matt McCormick 9f0468a72f crossbuild-essential images: disable deploy
This is a follow-up to 57bf16fa17
2018-04-15 22:54:04 -04:00
.circleci crossbuild-essential images: disable deploy 2018-04-15 22:54:04 -04:00
android-arm Update Dockerfile 2018-03-28 11:43:22 +03:00
android-arm64 Changed CC and CXX variables 2018-03-28 04:42:48 -04:00
browser-asmjs ENH: Compile git with SSL support 2018-04-14 19:12:07 -04:00
imagefiles ENH: Compile git with SSL support 2018-04-14 19:12:07 -04:00
linux-arm64 linux-arm64: Fix CPP path 2017-10-09 23:28:23 -04:00
linux-armv5 linux-armv5: Fix cpp path 2017-04-10 00:20:40 -04:00
linux-armv6 Dockerfile: Explicitly depend on "dockcross/base:latest" 2016-11-26 18:25:08 -05:00
linux-armv7 linux-armv7: Fix cpp path 2017-04-17 11:30:15 -07:00
linux-mips Implement "ct-ng" building, add "linux-mips". 2017-09-01 10:09:31 -04:00
linux-mipsel linux-mipsel: Fix toolchain environmental variable paths 2017-04-09 20:51:49 -04:00
linux-ppc64le Dockerfile: Explicitly depend on "dockcross/base:latest" 2016-11-26 18:25:08 -05:00
linux-s390x Address comments in linux-s390/Dockerfile.in 2017-09-15 14:03:08 -04:00
linux-x64 Dockerfile: Explicitly depend on "dockcross/base:latest" 2016-11-26 18:25:08 -05:00
linux-x86 ENH: Compile git with SSL support 2018-04-14 19:12:07 -04:00
manylinux-common manylinux: Update scikit-build from 0.5.1 to 0.6.1 2017-06-08 14:06:14 -04:00
manylinux-x64 ENH: Compile git with SSL support 2018-04-14 19:12:07 -04:00
manylinux-x86 ENH: Compile git with SSL support 2018-04-14 19:12:07 -04:00
test base: Add cmake wrapper scripts for CMAKE_TOOLCHAIN_FILE 2016-07-22 08:48:59 -04:00
windows-x64 ENH: Compile git with SSL support 2018-04-14 19:12:07 -04:00
windows-x86 ENH: Compile git with SSL support 2018-04-14 19:12:07 -04:00
.gitignore browser-asmjs: Update to depend on existing image from "trzeci/emscripten" 2016-11-25 15:51:42 -05:00
common.crosstool Implement "ct-ng" building, add "linux-mips". 2017-09-01 10:09:31 -04:00
common.debian ENH: Compile git with SSL support 2018-04-14 19:12:07 -04:00
common.docker ENH: Compile git with SSL support 2018-04-14 19:12:07 -04:00
common.manylinux ENH: Compile git with SSL support 2018-04-14 19:12:07 -04:00
Dockerfile.in common: Introduce "common.debian" 2016-11-25 15:51:42 -05:00
LICENSE Update LICENSE copyright dates and add @jcfr 2018-03-19 15:50:28 -04:00
Makefile Adding android-arm64 as a target 2018-03-19 14:50:17 +02:00
README.rst Merge pull request #201 from Nadav-Eyesight/android_arm64 2018-04-02 14:55:49 -04:00

dockcross
=========

Cross compiling toolchains in Docker images.

.. image:: https://circleci.com/gh/dockcross/dockcross/tree/master.svg?style=svg
  :target: https://circleci.com/gh/dockcross/dockcross/tree/master


Features
--------

* Pre-built and configured toolchains for cross compiling.
* Most images also contain an emulator for the target system.
* 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`, `LD` etc) are set to point to the appropriate tools in the container.
* Recent `CMake <https://cmake.org>`_ and ninja are precompiled.
* `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/>`_.


What is the difference between `dockcross` and `dockbuild` ?
------------------------------------------------------------

The key difference is that `dockbuild <https://github.com/dockbuild/dockbuild#readme>`_
images use the same method to conveniently isolate the build environment as
`dockcross <https://github.com/dockcross/dockcross#readme>`_ but they do **NOT** provide
a toolchain file.


Cross compilers
---------------

.. |base-images| image:: https://images.microbadger.com/badges/image/dockcross/base.svg
  :target: https://microbadger.com/images/dockcross/base

dockcross/base
  |base-images| Base image for other toolchain images. From Debian Jessie with GCC,
  make, autotools, CMake, Ninja, Git, and Python.


.. |android-arm-images| image:: https://images.microbadger.com/badges/image/dockcross/android-arm.svg
  :target: https://microbadger.com/images/dockcross/android-arm

dockcross/android-arm
  |android-arm-images| The Android NDK standalone toolchain for the arm
  architecture.


.. |android-arm64-images| image:: https://images.microbadger.com/badges/image/dockcross/android-arm64.svg
  :target: https://microbadger.com/images/dockcross/android-arm64

dockcross/android-arm64
  |android-arm64-images| The Android NDK standalone toolchain for the arm64
  architecture.

.. |browser-asmjs-images| image:: https://images.microbadger.com/badges/image/dockcross/browser-asmjs.svg
  :target: https://microbadger.com/images/dockcross/browser-asmjs

dockcross/browser-asmjs
  |browser-asmjs-images| The Emscripten JavaScript cross compiler.


.. |linux-arm64-images| image:: https://images.microbadger.com/badges/image/dockcross/linux-arm64.svg
  :target: https://microbadger.com/images/dockcross/linux-arm64

dockcross/linux-arm64
  |linux-arm64-images| Cross compiler for the 64-bit ARM platform on Linux,
  also known as AArch64.


.. |linux-armv5-images| image:: https://images.microbadger.com/badges/image/dockcross/linux-armv5.svg
  :target: https://microbadger.com/images/dockcross/linux-armv5

dockcross/linux-armv5
  |linux-armv5-images| Linux armv5 cross compiler toolchain for legacy devices
  like the Parrot AR Drone.


.. |linux-armv6-images| image:: https://images.microbadger.com/badges/image/dockcross/linux-armv6.svg
  :target: https://microbadger.com/images/dockcross/linux-armv6

dockcross/linux-armv6
  |linux-armv6-images| Linux ARMv6 cross compiler toolchain for the Raspberry
  Pi, etc.


.. |linux-armv7-images| image:: https://images.microbadger.com/badges/image/dockcross/linux-armv7.svg
  :target: https://microbadger.com/images/dockcross/linux-armv7

dockcross/linux-armv7
  |linux-armv7-images| Generic Linux armv7 cross compiler toolchain.

.. |linux-mipsel-images| image:: https://images.microbadger.com/badges/image/dockcross/linux-mipsel.svg
  :target: https://microbadger.com/images/dockcross/linux-mipsel

dockcross/linux-mipsel
  |linux-mipsel-images| Linux mipsel cross compiler toolchain for little endian MIPS GNU systems.

.. |linux-mips-images| image:: https://images.microbadger.com/badges/image/dockcross/linux-mips.svg
  :target: https://microbadger.com/images/dockcross/linux-mips

dockcross/linux-mips
  |linux-mips-images| Linux mips cross compiler toolchain for big endian 32-bit hard float MIPS GNU systems.

.. |linux-s390x-images| image:: https://images.microbadger.com/badges/image/dockcross/linux-s390x.svg
  :target: https://microbadger.com/images/dockcross/linux-s390x

dockcross/linux-s390x
  |linux-s390x-images| Linux s390x cross compiler toolchain for S390X GNU systems.

.. |linux-ppc64le-images| image:: https://images.microbadger.com/badges/image/dockcross/linux-ppc64le.svg
  :target: https://microbadger.com/images/dockcross/linux-ppc64le

dockcross/linux-ppc64le
  |linux-ppc64le-images| Linux PowerPC 64 little endian cross compiler
  toolchain for the POWER8, etc.


.. |linux-x64-images| image:: https://images.microbadger.com/badges/image/dockcross/linux-x64.svg
  :target: https://microbadger.com/images/dockcross/linux-x64

dockcross/linux-x64
  |linux-x64-images| Linux x86_64 / amd64 compiler. Since the Docker image is
  natively x86_64, this is not actually a cross compiler.


.. |linux-x86-images| image:: https://images.microbadger.com/badges/image/dockcross/linux-x86.svg
  :target: https://microbadger.com/images/dockcross/linux-x86

dockcross/linux-x86
  |linux-x86-images| Linux i686 cross compiler.


.. |manylinux-x64-images| image:: https://images.microbadger.com/badges/image/dockcross/manylinux-x64.svg
  :target: https://microbadger.com/images/dockcross/manylinux-x64

dockcross/manylinux-x64
  |manylinux-x64-images| Docker `manylinux <https://github.com/pypa/manylinux>`_ image for building Linux x86_64 / amd64 `Python wheel packages <http://pythonwheels.com/>`_.
  Also has support for the dockcross script, and it has installations of CMake, Ninja, and `scikit-build <http://scikit-build.org>`_


.. |manylinux-x86-images| image:: https://images.microbadger.com/badges/image/dockcross/manylinux-x86.svg
  :target: https://microbadger.com/images/dockcross/manylinux-x86

dockcross/manylinux-x86
  |manylinux-x86-images| Docker `manylinux <https://github.com/pypa/manylinux>`_ image for building Linux i686 `Python wheel packages <http://pythonwheels.com/>`_.
  Also has support for the dockcross script, and it has installations of CMake, Ninja, and `scikit-build <http://scikit-build.org>`_


.. |windows-x64-images| image:: https://images.microbadger.com/badges/image/dockcross/windows-x64.svg
  :target: https://microbadger.com/images/dockcross/windows-x64

dockcross/windows-x64
  |windows-x64-images| 64-bit Windows cross-compiler based on MXE/MinGW-w64.


.. |windows-x86-images| image:: https://images.microbadger.com/badges/image/dockcross/windows-x86.svg
  :target: https://microbadger.com/images/dockcross/windows-x86

dockcross/windows-x86
  |windows-x86-images| 32-bit Windows cross-compiler based on MXE/MinGW-w64.


Installation
------------

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 > ./dockcross
  chmod +x ./dockcross
  mv ./dockcross ~/bin/

Where `CROSS_COMPILER_IMAGE_NAME` is the name of the cross-compiler toolchain
Docker instance, e.g. `dockcross/linux-armv7`.

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

Usage
-----

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

  cd ~/src/dockcross
  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'

Note how invoking any toolchain command (make, gcc, etc.) is just a matter of prepending the **dockcross** 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` 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.


Built-in update commands
------------------------

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.


Download all images
-------------------

To easily download all images, the convenience target ``display_images`` could be used::

  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

Install all dockcross scripts
-----------------------------

To automatically install in ``~/bin`` the dockcross scripts for each images already downloaded, the
convenience target ``display_images`` could be used::

  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


Dockcross configuration
-----------------------

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

DOCKCROSS_CONFIG / --config|-c <path-to-config-file>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

Default: ``~/.dockcross``

DOCKCROSS_IMAGE / --image|-i <docker-image-name>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Docker cross-compiler image to run.

Default: Image with which the script was created.

DOCKCROSS_ARGS / --args|-a <docker-run-args>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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


Per-project dockcross configuration
-----------------------------------

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
``#!/bin/bash``.

For example, commands like ``git config --global advice.detachedHead false`` can
be added to this script.


Examples
--------

1. ``dockcross make``: Build the *Makefile* in the current directory.
2. ``dockcross cmake -Bbuild -H. -GNinja``: Run CMake with a build directory
   ``./build`` for a *CMakeLists.txt* file in the current directory and generate
   ``ninja`` 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 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.

Note that commands are executed verbatim. If any shell processing for
environment variable expansion or redirection is required, please use
`bash -c 'command args...'`.

How to extend Dockcross images
------------------------------
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::

  FROM dockcross/linux-armv7
  
  ENV DEFAULT_DOCKCROSS_IMAGE my_cool_image
  RUN apt-get install 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.


Articles
--------

- `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>`_


---

Credits go to `sdt/docker-raspberry-pi-cross-compiler <https://github.com/sdt/docker-raspberry-pi-cross-compiler>`_, who invented the base of the **dockcross** script.