Testing/DockerBuild: Difference between revisions

From QEMU
 
(5 intermediate revisions by 2 users not shown)
Line 7: Line 7:
Once docker is installed on your machine, running
Once docker is installed on your machine, running


     make docker-test-quick@centos6
     make docker-test-quick@centos7


from the QEMU git tree will start a quick compiling in a centos6 container. No other additional package is needed.
from the QEMU git tree will start a quick compiling in a centos7 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
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
     make docker
Line 33: Line 33:
It is possible to override the target list in the configure option, with TARGET_LIST make variable:
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
     make docker-test-quick@centos7 TARGET_LIST=ppc-softmmu,ppc64-softmmu


==== Multiple jobs ====
==== Multiple jobs ====
Line 39: Line 39:
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:
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
     make docker-test-quick@centos7 J=8


==== Debugging a docker build failure ====
==== Debugging a docker build failure ====
Line 45: Line 45:
Similar to the usual make command, adding "V=1" to a docker build command,
Similar to the usual make command, adding "V=1" to a docker build command,


     make docker-test-quick@centos6 V=1
     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.
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.
Line 51: Line 51:
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,
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
     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.
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.
Line 59: Line 59:
Since v3.0 there us a dedicated build target *docker-binfmt-image-debian-%* for boostraping Debian images. For example:
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-po
   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
rts/ EXECUTABLE=./riscv64-linux-user/qemu-riscv64 V=1




Line 76: Line 75:


'''This needs binfmt support enabled on your host set as appropriate for /usr/bin/qemu-$ARCH'''
'''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 [https://gitlab.com/qemu-project/qemu/container_registry 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.

Latest revision as of 09:54, 26 April 2021

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 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.