Platforms and Testing

Requirements

Lisp	SBCL
Vulkan	1.4 or newer: a loader and a driver
Run-time library	the Vulkan loader, libvulkan.so.1 on Linux, vulkan-1.dll on Windows
Lisp dependencies	cl-ffi; xmls for cl-vk/generator only; Parachute for the tests
Build	nothing: no C compiler, no Vulkan headers

Platforms

cl-vk itself knows no window system. The raw layer includes the surface extensions of Wayland (VK_KHR_wayland_surface), Windows (VK_KHR_win32_surface) and X11 (VK_KHR_xcb_surface, VK_KHR_xlib_surface, VK_EXT_acquire_xlib_display), so a window system library can create surfaces and hand them to adopt-surface. Extensions for other platforms (Android, Metal, Fuchsia and the like) are left out of the bindings, as are provisional ones.

Headless surfaces (VK_EXT_headless_surface) work everywhere Mesa's drivers do, and let programs and tests present with no display.

SBCL

cl-vk runs on SBCL, and CI tests it there. What it takes from SBCL beyond standard Common Lisp and cl-ffi, a lock for the debug message queue, lives in one small internal package, cl-vk/sys.

Running the tests

From the cl-vk directory:

stift test

asdf:test-system signals an error if any test fails, so the command exits unsuccessfully.

The suite, cl-vk/test, covers the raw layer, the struct layouts, the struct macros, the objects, the C syntax parser, the registry reader and the generator.

The object tests need the Vulkan loader and a Vulkan 1.4 driver with VK_EXT_headless_surface. A software driver is enough, so no GPU is needed: on Debian and Ubuntu, install libvulkan1 and mesa-vulkan-drivers, which provides lavapipe.

When the Khronos validation layer is installed (vulkan-validationlayers), the tests create their instances with validation, and fail if it reports any error.

The layout test compares the cl-ffi layout of every struct with tests/layout.sexp, the output of a C program compiled against the Vulkan headers on x86-64. The generator tests compare the generated files with the committed ones; see Generator and Registry.

Continuous integration

CI runs the suite on SBCL in a Debian container, with libvulkan1, mesa-vulkan-drivers and vulkan-validationlayers installed, so the object tests run on lavapipe under validation.

Testing your own program

The same set-up tests a program that uses cl-vk: a headless surface in place of a window, lavapipe in place of a GPU, and validation with the synchronization checks to catch misuse:

(vk:with-instance (instance :extensions '("VK_KHR_surface" "VK_EXT_headless_surface")
                            :validation-checks '(:synchronization))
  (let ((surface (vk:create-headless-surface instance)))
    (unwind-protect
         (progn
           (render-some-frames instance surface)
           (assert (notany (lambda (message) (eq (vk:debug-message-severity message) :error))
                           (vk:take-debug-messages instance))))
      (vk:destroy-surface surface))))

The frame loop in Recipes is tested this way.

To pick lavapipe on a machine that also has a GPU, select it with the loader's environment variable, for example VK_LOADER_DRIVERS_SELECT='*lvp*', or choose the physical device whose type is :cpu.