diff options
Diffstat (limited to 'src/3rdparty/xkbcommon/README.md')
-rw-r--r-- | src/3rdparty/xkbcommon/README.md | 112 |
1 files changed, 39 insertions, 73 deletions
diff --git a/src/3rdparty/xkbcommon/README.md b/src/3rdparty/xkbcommon/README.md index 2627a324a6..b8ae50de77 100644 --- a/src/3rdparty/xkbcommon/README.md +++ b/src/3rdparty/xkbcommon/README.md @@ -1,100 +1,66 @@ # libxkbcommon -xkbcommon is a keymap compiler and support library which processes a -reduced subset of keymaps as defined by the XKB specification. Primarily, -a keymap is created from a set of Rules/Model/Layout/Variant/Options names, -processed through an XKB ruleset, and compiled into a struct xkb_keymap, -which is the base type for all xkbcommon operations. - -From an xkb_keymap, an xkb_state object is created which holds the current -state of all modifiers, groups, LEDs, etc, relating to that keymap. All -key events must be fed into the xkb_state object using xkb_state_update_key(). -Once this is done, the xkb_state object will be properly updated, and the -keysyms to use can be obtained with xkb_state_key_get_syms(). - -libxkbcommon does not distribute a dataset itself, other than for testing -purposes. The most common dataset is xkeyboard-config, as used by all -current distributions for their X11 XKB data. More information on -xkeyboard-config is available here: - http://www.freedesktop.org/wiki/Software/XKeyboardConfig +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. ## Quick Guide See [Quick Guide](doc/quick-guide.md). +## Building + +libxkbcommon is built with [Meson](http://mesonbuild.com/): + + meson setup build + ninja -C build + +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 + ninja -C build + ## API -While xkbcommon's API is somewhat derived from the classic XKB API as found +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. The supported API is available -in the xkbcommon/xkbcommon-*.h files. Additional support is provided for -X11 (XCB) clients, in the xkbcommon-x11 library, xkbcommon/xkbcommon-x11.h. - -The xkbcommon API and ABI are stable. We will attempt to not break ABI during -a minor release series, so applications written against 0.1.0 should be -completely compatible with 0.5.3, but not necessarily with 1.0.0. However, new -symbols may be introduced in any release. Thus, anyone packaging xkbcommon -should make sure any package depending on it depends on a release greater than -or equal to the version it was built against (or earlier, if it doesn't use -any newly-introduced symbols), but less than the next major release. +expose fewer internal details to clients. + +See the [API Documentation](https://xkbcommon.org/doc/current/modules.html). + +## Dataset + +libxkbcommon does not distribute a keymap 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. More information on +xkeyboard-config is available here: + https://www.freedesktop.org/wiki/Software/XKeyboardConfig + +The dataset for Compose is distributed in libX11, as part of the X locale +data. ## Relation to X11 -Relative to the XKB 1.1 specification implemented in current X servers, -xkbcommon has removed support for some parts of the specification which -introduced unnecessary complications. Many of these removals were in fact -not implemented, or half-implemented at best, as well as being totally -unused in the standard dataset. - -Notable removals: -- geometry support - + there were very few geometry definitions available, and while - xkbcommon was responsible for parsing this insanely complex format, - it never actually did anything with it - + hopefully someone will develop a companion library which supports - keyboard geometries in a more useful format -- KcCGST (keycodes/compat/geometry/symbols/types) API - + use RMLVO instead; KcCGST is now an implementation detail - + including pre-defined keymap files -- XKM support - + may come in an optional X11 support/compatibility library -- around half of the interpret actions - + pointer device, message and redirect actions in particular -- non-virtual modifiers - + core and virtual modifiers have been collapsed into the same - namespace, with a 'significant' flag that largely parallels the - core/virtual split -- radio groups - + completely unused in current keymaps, never fully implemented -- overlays - + almost completely unused in current keymaps -- key behaviors - + used to implement radio groups and overlays, and to deal with things - like keys that physically lock; unused in current keymaps -- indicator behaviours such as LED-controls-key - + the only supported LED behaviour is key-controls-LED; again this - was never really used in current keymaps - -Notable additions: -- 32-bit keycodes -- extended number of modifiers -- extended number of groups -- multiple keysyms per level - + this requires incompatible dataset changes, such that X11 would - not be able to parse these +See [Compatibility](doc/compat.md) notes. ## Development An extremely rudimentary homepage can be found at - http://xkbcommon.org + https://xkbcommon.org xkbcommon is maintained in git at https://github.com/xkbcommon/libxkbcommon Patches are always welcome, and may be sent to either <xorg-devel@lists.x.org> or <wayland-devel@lists.freedesktop.org> +or through github. -Bugs are also welcome, and may be reported either at +Bug reports are also welcome, and may be filed either at Bugzilla https://bugs.freedesktop.org/describecomponents.cgi?product=libxkbcommon or Github https://github.com/xkbcommon/libxkbcommon/issues |