libxkbcommon  1.8.0
Debugging

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

Advanced tools

Note
An erroneous XKB configuration may make your keyboard unusable. Therefore it is advised to try custom configurations safely with the following workflow:
  1. 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.
  2. Create the relevant sub-directories and files, e.g. ~/xkb-test/symbols/my-layout.
  3. Test if your changes compile successfully:
1 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.

  1. Test if it behaves correctly. Note that you may need to add your user to the input group or run as root.
1 xkbcli interactive-evdev --include ~/xkb-test --include-defaults --enable-compose --layout my-layout
  1. Repeat steps 3 and 4 with your full keyboard configuration, i.e. all your model, layouts and options.
  2. If everything works as expected, it is time to test in real conditions:
    • Wayland: , move ~/xkb-test to one of the user-configuration locations, restart your session, update the keyboard configuration using your usual UI and enjoy your XKB customization!
    • X11: Unfortunately Xorg does not support alternative paths, so the next best option is to use the venerable xkbcomp tool.

      ```bash xkbcli compile-keymap –include ~/xkb-test –include-defaults –layout my-layout \ | xkbcomp - $DISPLAY ```

Happy hacking!