libxkbcommon is a keyboard keymap compiler and support library which processes keymaps as defined by the XKB (X Keyboard Extension) specification (minus some legacy features). It also contains a module for handling Compose and dead keys, a separate registry library for listing available keyboard layouts and a fair set of CLI tools to support keyboard layouts development.
libxkbcommon is the standard keymap handling library on Wayland and is used by compositors, toolkits, and applications to handle keyboard state and translate key events into characters and actions.
See Introduction to XKB for the essentials of XKB concepts and how a keymap is built.
- Introduction on how to use this library
- Full API reference
- History of the libxkbcommon changes by version
- Frequently Asked Questions
- Quick start for adding a *custom layout* or option
- Documentation of keymap components and keymap text syntax
- Introduction to the `xkbcli` application
- Frequently Asked Questions
libxkbcommon requires:
- a C compiler supporting C11
- XKB registry (optional):
libxml2 - X11 features (optional):
libxcbandlibxcb-xkb - Wayland features (optional):
wayland-client,wayland-protocols,wayland-scanner
libxkbcommon is built with Meson:
meson setup build
meson compile -C build
meson test -C build # Run the tests.To build for use with Wayland, you can disable X11 support while still using the X11 keyboard configuration resource files thusly:
meson setup build \
-Denable-x11=false \
-Dxkb-config-root=/usr/share/X11/xkb \
-Dx-locale-root=/usr/share/X11/locale
meson compile -C buildComplete list of user options
@include meson.optionsWhile libxkbcommon’s API is somewhat derived from the classic XKB API as found
in X11/extensions/XKB.h and friends, it has been substantially reworked to
expose fewer internal details to clients.
See the API Documentation.
Libxkbcommon offers a set of CLI
tools, grouped under the xkbcli application:
xkbcli compile-keymap- Compile an XKB keymap
xkbcli compile-compose- Compile a compose file
xkbcli how-to-type- Show how to type a given Unicode codepoint
xkbcli interactive-wayland- Interactive debugger for XKB keymaps for Wayland
xkbcli interactive-x11- Interactive debugger for XKB keymaps for X11
xkbcli interactive-evdev- Interactive debugger for XKB keymaps for evdev
xkbcli dump-keymap-wayland- Dump an XKB keymap from a Wayland compositor
xkbcli dump-keymap-x11- Dump an XKB keymap from an X server
xkbcli list- List available layouts and more
xkbcli info- Print information about libxkbcommon configuration, for debugging purposes
It may require the installation of the package libxkbcommon-tools or similar
name.
libxkbcommon does not distribute a keyboard layout dataset itself, other than for testing purposes. The most common dataset is xkeyboard-config, which is used by all current distributions for their XKB data. Further information on xkeyboard-config is available at its homepage and at its repository.
The dataset for Compose is distributed in libX11, as part of the X locale data.
libxkbcommon is compatible with X11, except for some obscure features.
See the Compatibility page for further details.
- Project’s homepage
- https://xkbcommon.org
- Repository
- https://github.com/xkbcommon/libxkbcommon
- Contributions
-
Patches are always welcome, and may be filed at:
- GitHub pull request (preferred)
- wayland-devel@lists.freedesktop.org
- Bug reports, questions
-
Bug reports and questions are also welcome, and may be filed at GitHub.
For general topics, prefer opening a discussion.
- Maintainers
See the LICENSE file.
Many thanks are due to Dan Nicholson for his heroic work in getting xkbcommon off the ground initially.