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
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
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
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.
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
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 NOCACHE=1 NOUSER=1 docker login registry.gitlab.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.