Docker build

The build system now supports a number of Docker build targets which allow the source tree to be built and tested on a number of different Linux distributions regardless of your host. These targets can even use the qemu linux-user binaries to allow "foreign" distributions to be run where cross-compiling would be more of a pain.

For the impatient

Once docker is installed on your machine, running

   make docker-test-quick@centos7

from the QEMU git tree will start a quick compiling in a centos7 container. No other additional package is needed.

Besides "quick" and "centos7", there are other available flavors, such as "make docker-test-full@ubuntu" or "make docker-test-mingw@fedora". Run

   make docker

to see an up-to-date help, which will list all available tests and images.

How it works

There are two components in a docker build target: the test name and the image name, both encoded into the make target name in a format of

   docker-$TEST@$IMAGE

The image

There are several Dockerfiles under 'tests/docker/dockerfiles' in the source tree, that define the compiling environment of the container. Each time a docker build is started, the Dockerfile's checksum is compared to the corresponding docker image's, if any. When they don't match, or when the docker image doesn't exist, the docker image is rebuilt.

The test

A test is a script under tests/docker, and is executed inside the container. Typically, they run 'configure' and 'make', and possibly 'make check' commands, with certain parameters.

It is possible to override the target list in the configure option, with TARGET_LIST make variable:

   make docker-test-quick@centos7 TARGET_LIST=ppc-softmmu,ppc64-softmmu

Multiple jobs

Because a docker build procedure is a single make target of your outtermost make command (on the contrary to the make command in the container instance), and because the -j option cannot be propagated into the container, the actual compiling is by default-j1. You may want to make use of your powerful $N-core machine, and luckily you can. J=$N is another artificial variable that is picked up by the inner make command:

   make docker-test-quick@centos7 J=8

Debugging a docker build failure

Similar to the usual make command, adding "V=1" to a docker build command,

   make docker-test-quick@centos7 V=1

will enable verbose output of the building process, from where you can see more information about the docker run command line, and the test script.

The docker instance is automatically removed as "--rm" is used in the "docker run" command. If you want to debug within the building environment, add "DEBUG=1" to the command line,

   make docker-test-quick@centos7 DEBUG=1

which will ask the script to pause right before compiling and drop you to a shell prompt, after printing some hints about the next steps.

linux-user Docker targets

Since v3.0 there us a dedicated build target *docker-binfmt-image-debian-%* for boostraping Debian images. For example:

  make docker-binfmt-image-debian-sid-riscv64 DEB_TYPE=sid DEB_ARCH=riscv64 DEB_URL=http://ftp.ports.debian.org/debian-ports/ EXECUTABLE=./riscv64-linux-user/qemu-riscv64 V=1

The debian-bootstrap docker target supports linux-user emulation. For example to build a Debian armhf docker image:

   make docker-image-debian-bootstrap V=1 J=9 DEB_ARCH=armhf DEB_TYPE=stable EXECUTABLE=./arm-linux-user/qemu-arm

This docker image can then be used for cross build testing with the normal docker test stanzas:

   make docker-test-quick@debian-bootstrap J=9 V=1

You can update the installed QEMU using the docker.py helper script:

   ./tests/docker/docker.py update qemu:debian-bootstrap ./arm-linux-user/qemu-arm

This needs binfmt support enabled on your host set as appropriate for /usr/bin/qemu-$ARCH

The GitLab Registry

Most of these images are built as part of our main CI loop and are available at the container registery. This is automatically used and in most cases will pull cached pre-built layers when you run the test. You can disable this with the NOCACHE variable.

Manually uploading an image

Someone with appropriate privileges can manually upload an image. This only needs to be done with images not built in the CI loop, usually because they take too long because they need to build a compiler.

The steps to upload are:

   make docker-image-debian-hexagon-cross V=1 J=30
   docker login registry.gitlab.example.com
   docker tag qemu/debian-hexagon-cross registry.gitlab.com/qemu-project/qemu/qemu/debian-hexagon-cross
   docker push registry.gitlab.com/qemu-project/qemu/qemu/debian-hexagon-cross

Note if you want to test images you will want to push them to your personal copy of the GitLab registry as well.