libxkbcommon

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.

Quick Guide

Introduction to XKB

See Introduction to XKB for the essentials of XKB concepts and how a keymap is built.

Using the library

Library quick guide

Introduction on how to use this library

API Documentation

Full API reference

Release notes

History of the libxkbcommon changes by version

FAQ

Frequently Asked Questions

Developing keyboard layouts

Custom layouts

Quick start for adding a *custom layout* or option

Keymap format

Documentation of keymap components and keymap text syntax

Tools

Introduction to the `xkbcli` application

FAQ

Frequently Asked Questions

Building

libxkbcommon requires:

• a C compiler supporting C11
• XKB registry (optional): libxml2
• X11 features (optional): libxcb and libxcb-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 build

Complete list of user options

@include meson.options

API

While 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.

Tools

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.

Layouts database

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.

Compatibility with X11

libxkbcommon is compatible with X11, except for some obscure features.

See the Compatibility page for further details.

Development

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

• Pierre Le Marre
• Ran Benita
• Daniel Stone

License

See the LICENSE file.

Credits

Many thanks are due to Dan Nicholson for his heroic work in getting xkbcommon off the ground initially.