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
  For single-user setups, see also User-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`
     A 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.