Available tools
xkbcommon provides multiple tools for debugging. Please consult the manual pages man xkbcli for the complete documentation of each tool.
- Note
- These tools may not be installed by default; please ensure you have the libxkbcommon-tools package installed.
Basic tools
- Interactive:
- xkbcli interactive-x11 to test your current configuration in an X11 session.
- xkbcli interactive-wayland to test your current configuration in a Wayland session. You may want to use the flag --enable-compose if your layouts use dead keys.
- xkbcli how-to-type: to find the key combinations to type in order to get a specific character or keysym.
Advanced tools
- xkbcli interactive-evdev: to test a configuration without affecting your current configuration. This requires access to the /dev/input/event* devices, you may need to add your user to the input group or run as root.
- xkbcli compile-keymap: to check the resulting compiled keymap for some configuration.
- xkbcli compile-compose: to check the resulting Compose file.
Testing a custom configuration
- Note
- An erroneous XKB configuration may make your keyboard unusable. Therefore it is advised to try custom configurations safely with the following workflow:
- Create a directory for the custom configuration, e.g. ~/xkb-test. Note that in order to test it safely, it should not be one of the locations that xkbcommon searches.
- Create the relevant sub-directories and files, e.g. ~/xkb-test/symbols/my-layout.
Test if your changes compile successfully:
xkbcli compile-keymap --include ~/xkb-test --include-defaults --test --layout my-layout
- Note
- The order of the --include* arguments is important here.
If it does not compile, you may add the flag --verbose for additional information.
Test if it behaves correctly. Note that you may need to add your user to the input group or run as root.
xkbcli interactive-evdev --include ~/xkb-test --include-defaults --enable-compose --layout my-layout
- Repeat steps 3 and 4 with your full keyboard configuration, i.e. all your model, layouts and options.
- If everything works as expected, it is time to test in real conditions:
Happy hacking!