Platforms and Testing

SBCL

cl-xkbcommon runs on SBCL, and CI runs the suite on SBCL 2.6.9. What it takes from SBCL beyond standard Common Lisp, a lock and the environment's variables, lives in the internal package cl-xkbcommon/sys.

Operating systems and architectures

cl-xkbcommon runs wherever libxkbcommon does, which in practice means Linux and the BSDs.

On x86-64, cl-xkbcommon collects libxkbcommon's log messages, which go into xkb-error messages and take-log-messages. libxkbcommon hands its log function a C va_list, and only on the x86-64 System V ABI does that arrive in a form cl-xkbcommon can format. On other architectures, such as AArch64, the messages go to standard error instead. Everything else works the same.

libxkbcommon versions

cl-xkbcommon needs libxkbcommon 1.10 or newer. active-modifiers asks which real modifiers each modifier is mapped to, through xkb_keymap_mod_get_mask, which 1.10 added. With an older libxkbcommon, make-context signals an xkb-error that says so. Debian forky has 1.13; Debian bookworm (1.5) and Ubuntu 24.04 (1.6) are too old.

The modifier keywords look up modifiers by their virtual names, such as Alt and Super. In a keymap that does not name them, the real modifier they conventionally sit on is used instead, such as Mod1 and Mod4. libxkbcommon 1.13 names them. CI runs on Debian forky, which has it. If modifier-active-p picks the wrong modifier on your system, please open an issue with the output of keymap-modifiers.

Running the tests

The tests use Parachute, and the dependencies are pinned in the stiftfile with stift. From the repository:

stift test

test-system signals an error if any test fails.

The tests compile real keymaps and compose tables, so they need libxkbcommon, the xkeyboard-config layouts and the X11 compose tables. On Debian:

sudo apt install libxkbcommon0 xkb-data libx11-data

The tests make their contexts with :environment nil, so the user's XKB_DEFAULT_* variables do not affect them. They use the us and se layouts, and a minimal keymap compiled from text.

From a REPL:

(asdf:load-system :cl-xkbcommon/test)
(parachute:test :cl-xkbcommon/test)

Writing tests for code that uses cl-xkbcommon

Code built on cl-xkbcommon can be tested without a window system. Make the keymap from layout names with :environment nil, and drive a keyboard state with update-key or update-modifiers:

(xkb:with-context (context :environment nil)
  (xkb:with-keymap (keymap context :layout "us")
    (xkb:with-keyboard-state (state keymap)
      (xkb:update-key state 37 :press)                ; Control
      (is eq 'select-all (find-binding state 38)))))  ; A

For compose sequences, make the compose table with make-compose-table-from-string. The test then does not depend on the system's compose files or the user's ~/.XCompose.