libxkbcommon: libxkbcommon

libxkbcommon 1.13.2 Library implementing the XKB specification for parsing keyboard descriptions and handling keyboard state

Loading...
Searching...
No Matches
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
FAQFAQ
  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
ToolsTools
  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
option(
'xkb-config-root',
type: 'string',
description: 'The XKB config root [default=xkeyboard-config install path]',
)
option(
'xkb-config-versioned-extensions-path',
type: 'string',
description: 'Lookup path for system-wide XKB versioned data extensions [default=xkeyboard-config install path + .d]',
)
option(
'xkb-config-unversioned-extensions-path',
type: 'string',
description: 'Lookup path for system-wide XKB unversioned data extensions [default=xkeyboard-config install path - version + .d]',
)
option(
'xkb-config-extra-path',
type: 'string',
description: 'Extra lookup path for system-wide XKB data [default=$sysconfdir/xkb]',
)
option(
'x-locale-root',
type: 'string',
description: 'The X locale root [default=$datadir/X11/locale]',
)
option(
'bash-completion-path',
type: 'string',
description: 'Directory for bash completion scripts'
)
option(
'default-rules',
type: 'string',
value: 'evdev',
description: 'Default XKB ruleset',
)
option(
'default-model',
type: 'string',
value: 'pc105',
description: 'Default XKB model',
)
option(
'default-layout',
type: 'string',
value: 'us',
description: 'Default XKB layout',
)
option(
'default-variant',
type: 'string',
value: '',
description: 'Default XKB variant',
)
option(
'default-options',
type: 'string',
value: '',
description: 'Default XKB options',
)
option(
'enable-tools',
type: 'boolean',
value: true,
description: 'Enable building tools',
)
option(
'enable-x11',
type: 'boolean',
value: true,
description: 'Enable building the xkbcommon-x11 library',
)
option(
'enable-docs',
type: 'boolean',
value: false,
description: 'Enable building the documentation',
)
option(
'enable-cool-uris',
type: 'boolean',
value: false,
description: 'Enable creating redirections to maintain stable documentation pages',
)
option(
'enable-wayland',
type: 'boolean',
value: true,
description: 'Enable support for Wayland utility programs (requires enable-tools)',
)
option(
'enable-xkbregistry',
type: 'boolean',
value: true,
description: 'Enable building libxkbregistry',
)
option(
'enable-bash-completion',
type: 'boolean',
value: true,
description: 'Enable installing bash completion scripts',
)

# 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

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)
  - wayla.nosp@m.nd-d.nosp@m.evel@.nosp@m.list.nosp@m.s.fre.nosp@m.edes.nosp@m.ktop..nosp@m.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.