vkd3d/gitlab/README

=====================
vkd3d testing scripts
=====================

These scripts are used by the GitLab CI feature to automatically run
the vkd3d tests on each merge request.

The CI target image-linux, in the file image.yml, builds a Docker
image based on Debian bookworm with all the packages required for
testing, and uploads it to the GitLab container registry. The Docker
script is in the file image.docker.

The file build.yml contains the actual testing targets. Currently
vkd3d is tested on Linux, on x86-64 and i386, each architecture with
two different Vulkan drivers (both from Mesa): llvmpipe (a software
implementation) and RADV (a hardware implementation backed by an AMD
GPU). vkd3d is also tested on macOS, with an Intel processor, using
MoltenVK as the Vulkan driver. The llvmpipe and macOS jobs are
currently allowed to fail.

Additionally, MinGW is used to build PE binaries for both vkd3d and
its crosstests, for both 32 and 64 bit. The PE crosstests are executed
on Windows 10 to check that behavior imposed by the tests corresponds
to Microsoft's D3D12 implementation. The rendering backend is
currently Window's WARP software implementation.

The testing logs are available as CI artifacts, as well as the PE
modules built by the crosstest and MinGW jobs.

Some custom runner configuration is required in order to run the tests
on an AMD GPU. Specifically, a runner tagged with `amd-gpu' must be
available with the following features:

 * of course a sufficiently recent AMD GPU must be available to the
   host;

 * the host kernel must have the appropriate driver and firmware
   installed;

 * the runner must forward the DRI nodes to the guest; this can be
   configured by adding the line

     devices = ["/dev/dri"]

   to the relevant [runners.docker] section in the config.toml file;

 * the DRI render nodes must be readable and writable by GID 800,
   either because they belong to that group (e.g. because the group
   `render', which typically owns those files, has GID 800) or via a
   FS ACL; such stipulation is needed because in Debian group `render'
   is created dynamically, therefore has no predictable GID: the use
   of a fixed GID enables the guest system to be set up so that the
   user running the tests can access the render nodes.

A runner on an Intel macOS system tagged with `mac' must also be
available to run the macOS tests. Unfortunately a system like Docker
is not available in this case to provide an isolated standard
environment for running the tests. All the software required to
compile and run the tests will therefore have to be installed directly
on the host system. Complete instructions to setup the macOS are
currently not available.

Finally, a runner tagged with `win10-21h2' must be available and
submit jobs to a Windows 10 virtual machine.