From e5ab270390c92007f3ee2337aac5ad818fba476d Mon Sep 17 00:00:00 2001 From: Alejandro Saucedo Date: Sun, 24 Jan 2021 17:26:15 +0000 Subject: [PATCH] Added documentation for images & CI --- docs/index.rst | 1 + docs/overview/build-system.rst | 2 +- docs/overview/ci-tests.rst | 66 ++++++++++++++++++++++++++++++++++ 3 files changed, 68 insertions(+), 1 deletion(-) create mode 100644 docs/overview/ci-tests.rst diff --git a/docs/index.rst b/docs/index.rst index 340b3458b..ff31c3f1c 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,6 +19,7 @@ Index Converting GLSL/HLSL Shaders to C++ Headers Mobile App Integration (Android) Game Engine Integration (Godot Engine) + CI, Docker Images & Tests Python Class Documentation & Reference C++ Class Documentation & Reference Code Index diff --git a/docs/overview/build-system.rst b/docs/overview/build-system.rst index dd4f8e8b9..6f5a602cf 100644 --- a/docs/overview/build-system.rst +++ b/docs/overview/build-system.rst @@ -1,5 +1,5 @@ -Build System Deep Dive +C++ Build System Deep Dive ====================== The recommended approach to build the project is as out-of-source build in the ``build`` folder. This project comes with a ``Makefile`` that provides a set of commands that help with developer workflows. You can see some of the commands if you want to add some of the more advanced commands. diff --git a/docs/overview/ci-tests.rst b/docs/overview/ci-tests.rst new file mode 100644 index 000000000..81443ec86 --- /dev/null +++ b/docs/overview/ci-tests.rst @@ -0,0 +1,66 @@ + +CI, Docker Images & Tests +====================== + +This section contains an overview of the steps run on CI, as well as the tools used to simplify the testing (such as running Vulkan on CPU). + +We use Github Actions to run the tests, which simplifies the workflows significantly for contributors. + +The tests run on CPU, and can be triggered using the ACT command line interface (https://github.com/nektos/act) - once you install the command line (And start the Docker daemon) you just have to type: + +.. code-block:: + + $ act + + [Python Tests/python-tests] 🚀 Start image=axsauze/kompute-builder:0.2 + [C++ Tests/cpp-tests ] 🚀 Start image=axsauze/kompute-builder:0.2 + [C++ Tests/cpp-tests ] 🐳 docker run image=axsauze/kompute-builder:0.2 entrypoint=["/usr/bin/tail" "-f" "/dev/null"] cmd=[] + [Python Tests/python-tests] 🐳 docker run image=axsauze/kompute-builder:0.2 entrypoint=["/usr/bin/tail" "-f" "/dev/null"] cmd=[] + ... + + +CI Commands Triggered +~~~~~~~~~~~~~ + +The simplest way to see how this works is by looking at the github actions commands that are run. + +These can be found through the following files: + +* `CPP Tests `_ +* `Python Tests `_ + +When submitting a PR or merging a PR into master, both of these will run - you can see the logs through the github interface. + + + +Running Vulkan on the CPU +~~~~~~~~~~~~~ + +We use `Swiftshader `_ to enable us to run the Vulkan Kompute framework directly on the CPU for the CI tests. + +Even though Swiftshader is optimized to function as a high-performance CPU backend for Vulkan, there are several limitations, the most notable in context of Kompute are: + +* Loading files (spirv or text) leads to segfault +* Loading raw text string shaders leads to segfault + +This is one of the main reason why only a subset of the tests are run in the CI. + +Dockerfiles +~~~~~~~~~~~~~ + +The dockerfiles created provide functionality to simplify the interaction with the system. + +.. list-table:: + :header-rows: 1 + + * - Image + - Description + * - axsauze/kompute-builder:0.2 + - Main CI builder image with all required dependencies to build and run C++ & Python tests. + * - axsauze/swiftshader:0.1 + - Image building Swiftshader libraries only to reduce time via multi-staged builds + * - axsauze/vulkan-sdk:0.1 + - Image contained a linux build of the full Vulkan SDK to reduce time via multi-staged builds + + +