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 centos6 container. No other additional package is needed.
Besides "quick" and "centos6", 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@centos6 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@centos6 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@centos6 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@centos6 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
- 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