Platforms and Testing

Requirements

What	Needed for
libwayland-client 1.20 or newer (libwayland-client0)	cl-wl at run time
libwayland-cursor (libwayland-cursor0), which comes with libwayland-client	cl-wl/cursor, and the test suite
libwayland-server (libwayland-server0)	cl-wl/test-compositor and the test suite
cl-ffi	everything
cl-threads	cl-wl/test-compositor and the test suite
xmls	cl-wl/scanner only
Parachute	the test suite

No C compiler, no Wayland headers and no wayland-scanner is needed. The shared libraries are loaded through cl-ffi at load time.

SBCL

cl-wl runs on SBCL. It has no implementation-specific code of its own: what it needs beyond standard Common Lisp, errno and pointers to addresses, comes from cl-ffi.

Operating systems

Wayland is a Linux technology first, and cl-wl is developed and tested on Linux. The libc constants it uses (POLLIN, POLLOUT, EINTR, EPIPE, the mmap flags and MFD_CLOEXEC) have the same values on the BSDs, where libwayland also runs, and O_CLOEXEC, which pipes are made with, is spelled for Linux and FreeBSD each; shared memory needs memfd_create, which FreeBSD has from version 13. The test compositor uses Linux's socketpair constants.

It also works under WSLg, whose Weston compositor serves Wayland clients on Windows. The examples in this wiki were run there. The exceptions are the decoration and fractional-scale recipes: WSLg offers neither global, so those recipes were only compiled. The clipboard recipe follows cl-windowing's Wayland clipboard, which its tests run.

Running the tests

From the cl-wl directory:

stift test

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

The suite runs against the in-process test compositor, so it needs no running compositor and no display. It prints one line to standard error on purpose: wl_surface#4: error 2: bad size is libwayland reporting the protocol error that a test provokes.

Current result, on SBCL 2.6.9: 684 passed, 0 failed, 0 skipped.

What the suite covers

File	Covers
tests/ffi-test.lisp	the raw layer loads and links
tests/reader-test.lisp	the protocol reader: the model it builds, the parts a model built by hand must have, every protocol-error, and the path and file each error carries, complete before anything unwinds
tests/generator-test.lisp	generated forms, names, documentation, array element types, destructor events, the shipped protocols and their array element types, where the generator's errors say they are, and that the committed bindings match the scanner's output
tests/runtime-test.lisp	connecting, requests and events of every wire type, enums and bitfields, versions, introspection, version-aware destroy-proxy, destructor events, globals, their order and follow-globals, the dispatch functions, define-request's refusals, read-events from a second thread, every error condition, broken connections, shared memory and keymaps, the test compositor's pump and misuse, and zero allocation in steady state, waiting for events included
tests/transfer-test.lisp	text through pipes, as the clipboard moves it: round trips, text longer than a pipe holds, null bytes, readers and writers that close early or never come, and timeouts
tests/cursor-test.lisp	cursor themes through libwayland-cursor: loading, finding cursors, images and their buffers, animation frames, destroying, and the built-in cursors when no theme is installed

CI

.forgejo/workflows/ci.yml runs the suite on every push to main and on every pull request. It uses a Debian forky container with libwayland-client0, libwayland-server0 and libwayland-cursor0 and the shared fakehacker/actions/stift-ci action, which runs stift test on SBCL.

Contributing

• A change without tests is not finished.
• If you change the generator or a protocol file, run (cl-wl/scanner:regenerate-bindings) and commit the regenerated files. The test committed-bindings fails until you do.
• Keep implementation-specific code out of cl-wl: it belongs in cl-ffi.
• Foreign callbacks only queue. Never signal or unwind through libwayland's frames.
• Code that runs every frame must not allocate. The allocation tests check the request and event paths and shared-memory writes.