libxkbcommon: Packaging keyboard layouts

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

Loading...
Searching...
No Matches
Packaging keyboard layouts

Since version 1.13 xkbcommon facilitates installing keyboard layout packages using a new mechanism: the XKB extensions directories. It provides a proper way for keyboard layout packages to install their files, which otherwise resorted to hacking the xkeyboard-config system directory.

Note
  See also the following alternatives without packaging:
  Single-user setups
    user-configuration
  System-wide setups
    system-configuration

# The extensions directories

There are 2 root extensions directories, both optional:

Unversioned directory: `XKB_CONFIG_UNVERSIONED_EXTENSIONS_PATH`

  It is intended as the default extensions path and for forward compatibility.

  It defaults to: <xkeyboard-config-root> - version suffix + .d, e.g. /usr/share/xkeyboard-config.d.

Versioned directory: `XKB_CONFIG_VERSIONED_EXTENSIONS_PATH`

  It is intended for backward compatibility with older xkeyboard-config packages.

  It defaults to: <xkeyboard-config-root> + .d, e.g. /usr/share/xkeyboard-config-2.d.

Note
  XKB_CONFIG_VERSIONED_EXTENSIONS_PATH has higher priority than XKB_CONFIG_UNVERSIONED_EXTENSIONS_PATH.

# Lookup mechanism

When appending the default include paths, after the extra path but before the canonical XKB root, for each extensions directory hereinabove: its subdirectories are appended in lexicographic order to the include paths; unversioned subdirectories are appended only if there is no corresponding versioned subdirectory.

Example: given the following setup:

- XKEYBOARD_CONFIG_ROOT = /usr/share/xkeyboard-config-2
- /usr/share/xkeyboard-config-2.d tree:
  - p1 (installed by package p1)
    - rules/evdev.xml
    - symbols/a
  - p2 (installed by package p2)
    - rules/evdev.xml
    - symbols/b
- /usr/share/xkeyboard-config.d tree:
  - p1 (installed by package p1)
    - rules/evdev.xml
    - symbols/a
  - p3 (installed by package p3)
    - rules/evdev.xml
    - symbols/c

then the include path list may be:

1. ~/.config/xkb (user path)
2. ~/.xkb (alternative user path)
3. /etc/xkb (extra path)
4. /usr/share/xkeyboard-config-2.d/p1
5. /usr/share/xkeyboard-config-2.d/p2
6. /usr/share/xkeyboard-config.d/p3
7. /usr/share/xkeyboard-config-2 (canonical root)

In this example:

- Package p1 distributes a layout with specific compatibility files for xkeyboard-config v2 and fallback files for v3+. In this case the versioned files have priority, so the unversioned /usr/share/xkeyboard-config.d/p1 path is not included.
- Package p2 distributes only a layout specific to xkeyboard-config v2.
- Package p3 distributes a layout for any xkeyboard-config version.

# Instructions for keyboard layout packagers

1. Add a dependency to libxkbcommon 1.13+ and xkeyboard-config 2.45+ using their pkg-config files. The libxkbcommon dependency will be necessary until xkeyboard-config ships a pkg-config file with the needed variables (see hereinafter).
2. Remove any installation step that modifies the xkeyboard-config directories, unless there is a need to provide the layout for X11-only sessions, because they do not support XKB directories other than the hard-coded one in the X server.

3. Install the XKB files in: <XKB_CONFIG_UNVERSIONED_EXTENSIONS_PATH>/<PACKAGE_NAME>/<KCCGST_DIR>, where:

   `XKB_CONFIG_UNVERSIONED_EXTENSIONS_PATH`
     Set from the variable xkb_unversioned_extensions_path from the libxkbcommon or xkeyboard-config pkg-config file
   `PACKAGE_NAME`
     A unique identifier, typically the layout or package name.
   `KCCGST_DIR`
     An XKB KcCGST component directory, such as symbols, types, etc.
   Note
     If a custom rules file is required (e.g. to add an option), name it <ruleset>.post (note the .post suffix) to enable composability with other packages. See RMLVO resolution process for further details.

4. Install the registry file at: <XKB_CONFIG_UNVERSIONED_EXTENSIONS_PATH>/<PACKAGE_NAME>/rules/evdev.xml.

   See Discoverable layouts for further information.

5. When xkeyboard-config v3 is out:
   - If the keymap is updated to use features incompatible with xkeyboard-config v2, the v2 files are installed in <XKB_CONFIG_VERSIONED_EXTENSIONS_PATH_V2> (previously <XKB_CONFIG_UNVERSIONED_EXTENSIONS_PATH>) and then install the v3 files with the new features in <XKB_CONFIG_UNVERSIONED_EXTENSIONS_PATH>.
   - Otherwise no change is required.
6. When xkeyboard-config v4+ is out, proceed similarly to step 5 with the corresponding xkeyboard-config version.