https://github.com/xkbcommon/libxkbcommon
keymap handling library for toolkits and window systems
https://github.com/xkbcommon/libxkbcommon
keyboard keyboard-layout keymap wayland x11 xkb xkbcommon
Last synced: 6 months ago
JSON representation
keymap handling library for toolkits and window systems
- Host: GitHub
- URL: https://github.com/xkbcommon/libxkbcommon
- Owner: xkbcommon
- License: other
- Created: 2013-04-01T17:31:10.000Z (about 13 years ago)
- Default Branch: master
- Last Pushed: 2025-10-17T14:47:43.000Z (6 months ago)
- Last Synced: 2025-10-18T17:24:57.154Z (6 months ago)
- Topics: keyboard, keyboard-layout, keymap, wayland, x11, xkb, xkbcommon
- Language: C
- Homepage: https://xkbcommon.org
- Size: 8.61 MB
- Stars: 321
- Watchers: 20
- Forks: 135
- Open Issues: 49
-
Metadata Files:
- Readme: README.md
- Changelog: NEWS.md
- License: LICENSE
Awesome Lists containing this project
README
# libxkbcommon
**libxkbcommon** is a keyboard keymap compiler and support library which
processes a reduced subset of keymaps as defined by the [XKB] \(X Keyboard
Extension) specification. 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*.
[XKB]: doc/introduction-to-xkb.md
## Quick Guide
- [Introduction to XKB][XKB]: to learn the essentials of XKB.
- [User-configuration](doc/user-configuration.md): instructions to add
a *custom layout* or option.
- [Keymap format](doc/keymap-text-format-v1-v2.md): keymap components and keymap
text syntax documentation.
- [Library quick Guide](doc/quick-guide.md): introduction on how to use
this library.
- [Tools](./README.md#tools): introduction to the `xkbcli` application.
- [Release notes](doc/release-notes.md).
- [Frequently Asked Question (FAQ)](doc/faq.md).
## Building
libxkbcommon is built with [Meson](http://mesonbuild.com):
```bash
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:
```bash
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.txt
## 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](https://xkbcommon.org/doc/current/topics.html).
## Tools
Libxkbcommon has a fair 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 a XKB keymap from a Wayland compositor
xkbcli dump-keymap-x11- Dump a XKB keymap from a X server
xkbcli list- List available layouts and more
It may require the installation of the package `libxkbcommon-tools` or similar
name.
## Dataset
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 X11 XKB data. Further information
on xkeyboard-config is available at its [homepage][xkeyboard-config-home] and at
its [repository][xkeyboard-config-repo].
The dataset for *Compose* is distributed in [libX11], as part of the X locale
data.
[xkeyboard-config-home]: https://www.freedesktop.org/wiki/Software/XKeyboardConfig
[xkeyboard-config-repo]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config
[libX11]: https://gitlab.freedesktop.org/xorg/lib/libx11
## Relation to X11
See [Compatibility](doc/compatibility.md) notes.
## Development
An project’s homepage can be found at https://xkbcommon.org.
xkbcommon is maintained in git at: https://github.com/xkbcommon/libxkbcommon
Patches are always welcome, and may be sent to either
or
or in a [GitHub](https://github.com/xkbcommon/libxkbcommon) pull request.
Bug reports (and usage questions) are also welcome, and may be filed at
[GitHub](https://github.com/xkbcommon/libxkbcommon/issues).
The maintainers are:
- [Daniel Stone](mailto:daniel@fooishbar.org)
- [Ran Benita](mailto:ran@unusedvar.com)
- [Pierre Le Marre](mailto:dev@wismill.eu)
## License
See the [LICENSE](doc/license.md) file.
## Credits
Many thanks are due to Dan Nicholson for his heroic work in getting xkbcommon
off the ground initially.