gitlab/README

   1 =====================
   2 vkd3d testing scripts
   3 =====================
   4
   5 These scripts are used by the GitLab CI feature to automatically run
   6 the vkd3d tests on each merge request.
   7
   8 The CI target image-linux, in the file image.yml, builds a Docker
   9 image based on Debian bookworm with all the packages required for
  10 testing, and uploads it to the GitLab container registry. The Docker
  11 script is in the file image.docker. Most of the dependencies are
  12 installed directly from the Debian repositories, with a few
  13 exceptions:
  14
  15  * widl is compiled from Wine sources, because installing it from the
  16    Debian repositories would carry all the rest of Wine and make the
  17    Docker image quite larger;
  18
  19  * SPIRV-Tools are recompiled from sources, because the packages in
  20    Debian do not ship shared objects and are not multiarch-compatible;
  21    in order to make the packages multiarch-compatible, the utilities
  22    are dropped (they're not used by the CI anyway);
  23
  24  * llvmpipe from Mesa 24.0.1 is compiled (in addition to version
  25    22.3.6 available in Debian bookworm), because some Vulkan features
  26    required by vkd3d are not available in Mesa 22.3.6.
  27
  28 The file build.yml contains the actual testing targets. Currently
  29 vkd3d is tested on Linux, on x86-64 and i386, each architecture with
  30 two different Vulkan drivers (both from Mesa): llvmpipe (a software
  31 implementation) and RADV (a hardware implementation backed by an AMD
  32 GPU). vkd3d is also tested on macOS, with an Intel processor, using
  33 MoltenVK as the Vulkan driver. The llvmpipe and macOS jobs are
  34 currently allowed to fail.
  35
  36 Additionally, MinGW is used to build PE binaries for both vkd3d and
  37 its crosstests, for both 32 and 64 bit. The PE crosstests are executed
  38 on Windows 10 to check that behavior imposed by the tests corresponds
  39 to Microsoft's D3D12 implementation. The rendering backend is
  40 currently Window's WARP software implementation.
  41
  42 The testing logs are available as CI artifacts, as well as the PE
  43 modules built by the crosstest and MinGW jobs.
  44
  45 Some custom runner configuration is required in order to run the tests
  46 on an AMD GPU. Specifically, a runner tagged with `amd-gpu' must be
  47 available with the following features:
  48
  49  * of course a sufficiently recent AMD GPU must be available to the
  50    host;
  51
  52  * the host kernel must have the appropriate driver and firmware
  53    installed;
  54
  55  * the runner must forward the DRI nodes to the guest; this can be
  56    configured by adding the line
  57
  58      devices = ["/dev/dri"]
  59
  60    to the relevant [runners.docker] section in the config.toml file;
  61
  62  * the DRI render nodes must be readable and writable by GID 800,
  63    either because they belong to that group (e.g. because the group
  64    `render', which typically owns those files, has GID 800) or via a
  65    FS ACL; such stipulation is needed because in Debian group `render'
  66    is created dynamically, therefore has no predictable GID: the use
  67    of a fixed GID enables the guest system to be set up so that the
  68    user running the tests can access the render nodes.
  69
  70 A runner on an Intel macOS system tagged with `mac' must also be
  71 available to run the macOS tests. Unfortunately a system like Docker
  72 is not available in this case to provide an isolated standard
  73 environment for running the tests. All the software required to
  74 compile and run the tests will therefore have to be installed directly
  75 on the host system. Complete instructions to setup the macOS are
  76 currently not available.
  77
  78 Finally, a runner tagged with `win10-21h2' must be available and
  79 submit jobs to a Windows 10 virtual machine.