1# User-configuration 2 3This page describes how to add a custom layout or option so that it will be 4parsed by libxkbcommon. 5 6**The below requires libxkbcommon as keymap compiler and does not work in X**. 7 8## Data locations 9 10libxkbcommon searches the following paths for XKB configuration files: 11- `$XDG_CONFIG_HOME/xkb/`, or `$HOME/.config/xkb/` if the `$XDG_CONFIG_HOME` 12 environment variable is not defined 13- `$HOME/.xkb/` 14- `$XKB_CONFIG_EXTRA_PATH` if set, otherswise `<sysconfdir>/xkb` (on most 15 distributions this is `/etc/xkb`) 16- `$XKB_CONFIG_ROOT` if set, otherwise `<datadir>/X11/xkb/` (path defined by the 17 `xkeyboard-config` package, on most distributions this is 18 `/usr/share/X11/xkb`) 19 20A keymap created with `xkb_keymap_new_from_names()` will look up those paths in 21order until the required data is found. 22 23**Note: Where libxkbcommon runs in a privileged context, only the system 24(datadir) path is available.** 25 26Each directory should have one or more of the following subdirectories: 27- `compat` 28- `geometry` (libxkbcommon ignores this directory) 29- `keycodes` 30- `rules` 31- `symbols` 32- `types` 33 34The majority of user-specific configuration involve modifying key symbols and 35this is what this document focuses on. For use-cases where a user may need to 36add new key types or compat entries the general approach remains the same. A 37detailed description for how to add those types or compat entries is out of 38scope for this document. 39 40You should never need to add user-specific keycodes. Where a keycode is missing, 41the addition should be filed in the upstream xkeyboard-config project. 42 43## RMLVO vs KcCGST 44 45Due to how XKB is configured, there is no such thing as a "layout" in XKB 46itself, or, indeed, any of the rules, models, variant, options (RMLVO) decribed 47in `struct xkb_rule_names`. RMLVO names are merely lookup keys in the 48rules file provided by xkeyboard-config to map to the correct keycode, compat, 49geometry (ignored by libxkbcommon), symbols and types (KcCGST). The KcCGST data 50is the one used by XKB and libxbkcommon to map keys to actual symbols. 51 52For example, a common RMLVO configuration is layout "us", variant "dvorak" and 53option "terminate:ctrl_alt_bksp". Using the default rules file and model 54this maps into the following KcCGST components: 55 56``` 57xkb_keymap { 58 xkb_keycodes { include "evdev+aliases(qwerty)" }; 59 xkb_types { include "complete" }; 60 xkb_compat { include "complete" }; 61 xkb_symbols { include "pc+us(dvorak)+inet(evdev)+terminate(ctrl_alt_bksp)" }; 62 xkb_geometry { include "pc(pc105)" }; 63}; 64``` 65 66A detailed explanation of how rules files convert RMLVO to KcCGST is out of 67scope for this document. See [the rules file](md_doc_rules-format.html) page 68instead. 69 70 71## Adding a layout 72 73Adding a layout requires that the user adds **symbols** in the correct location. 74 75The default rules files (usually `evdev`) have a catch-all to map a layout, say 76"foo", and a variant, say "bar", into the "bar" section in the file 77`$xkb_base_dir/symbols/foo`. 78This is sufficient to define a new keyboard layout. The example below defines 79the keyboard layout "banana" with an optional variant "orange" 80 81``` 82$ cat $XDG_CONFIG_HOME/xkb/symbols/banana 83// Like a US layout but swap the top row so numbers are on Shift 84default partial alphanumeric_keys 85xkb_symbols "basic" { 86 include "us(basic)" 87 name[Group1]= "Banana (US)"; 88 89 key <AE01> { [ exclam, 1] }; 90 key <AE02> { [ at, 2] }; 91 key <AE03> { [ numbersign, 3] }; 92 key <AE04> { [ dollar, 4] }; 93 key <AE05> { [ percent, 5] }; 94 key <AE06> { [ asciicircum, 6] }; 95 key <AE07> { [ ampersand, 7] }; 96 key <AE08> { [ asterisk, 8] }; 97 key <AE09> { [ parenleft, 9] }; 98 key <AE10> { [ parenright, 0] }; 99 key <AE11> { [ underscore, minus] }; 100 key <AE12> { [ plus, equal] }; 101}; 102 103// Same as banana but map the euro sign to the 5 key 104partial alphanumeric_keys 105xkb_symbols "orange" { 106 include "banana(basic)" 107 name[Group1] = "Banana (Eurosign on 5)"; 108 include "eurosign(5)" 109}; 110``` 111 112The `default` section is loaded when no variant is given. The first example 113sections uses ``include`` to populate with a symbols list defined elsewhere 114(here: section `basic` from the file `symbols/us`, aka. the default US keyboard 115layout) and overrides parts of these 116symbols. The effect of this section is to swap the numbers and symbols in the 117top-most row (compared to the US layout) but otherwise use the US layout. 118 119The "orange" variant uses the "banana" symbols and includes a different section 120to define the eurosign. It does not specificially override any symbols. 121 122The exact details of how `xkb_symbols` work is out of scope for this document. 123 124## Adding an option 125 126For technical reasons, options do **not** have a catch-all to map option names 127to files and sections and must be specifically mapped by the user. This requires 128a custom rules file. As the `evdev` ruleset is hardcoded in many clients, the 129custom rules file must usually be named `evdev`. 130 131``` 132$ cat $XDG_CONFIG_HOME/xkb/rules/evdev 133! option = symbols 134 custom:foo = +custom(bar) 135 custom:baz = +other(baz) 136 137! include %S/evdev 138``` 139 140This rules file maps the RMLVO option "custom:foo" to the "bar" section in the 141`symbols/custom` file and the "custom:baz" option to the "baz" section in the 142`symbols/other` file. Note how the RMLVO option name may be different to the 143file or section name. 144 145The `include` statement includes the system-provided `evdev` ruleset. This 146allows users to only override those options they need. 147 148The files themselves are similar to the layout examples in the previous section: 149 150``` 151$ cat $XDG_CONFIG_HOME/xkb/symbols/custom 152// map the Tilde key to nothing on the first shift level 153partial alphanumeric_keys 154xkb_symbols "bar" { 155 key <TLDE> { [ VoidSymbol ] }; 156}; 157 158$ cat $XDG_CONFIG_HOME/xkb/symbols/other 159// map first key in bottom row (Z in the US layout) to k/K 160partial alphanumeric_keys 161xkb_symbols "baz" { 162 key <AB01> { [ k, K ] }; 163}; 164``` 165 166With these in place, a user may select any layout/variant together with 167the "custom:foo" and/or "custom:baz" options. 168 169## Discoverable layouts 170 171**The below requires libxkbregistry as XKB lookup tool and does not work where 172clients parse the XML file directly**. 173 174The above sections apply only to the data files and require that the user knows 175about the existence of the new entries. To make custom entries discoverable by 176the configuration tools (e.g. the GNOME Control Center), the new entries must 177also be added to the XML file that is parsed by libxkbregistry. In most cases, 178this is the `evdev.xml` file in the rules directory. The example below shows the 179XML file that would add the custom layout and custom options as outlined above 180to the XKB registry: 181 182``` 183$ cat $XDG_CONFIG_HOME/xkb/rules/evdev.xml 184<?xml version="1.0" encoding="UTF-8"?> 185<!DOCTYPE xkbConfigRegistry SYSTEM "xkb.dtd"> 186<xkbConfigRegistry version="1.1"> 187 <layoutList> 188 <layout> 189 <configItem> 190 <name>banana</name> 191 <shortDescription>ban</shortDescription> 192 <description>Banana</description> 193 </configItem> 194 <variantList> 195 <variant> 196 <configItem> 197 <name>orange</name> 198 <shortDescription>or</shortDescription> 199 <description>Orange (Banana)</description> 200 </configItem> 201 </variant> 202 </variantList> 203 </layout> 204 </layoutList> 205 <optionList> 206 <group allowMultipleSelection="true"> 207 <configItem> 208 <name>custom</name> 209 <description>Custom options</description> 210 </configItem> 211 <option> 212 <configItem> 213 <name>custom:foo</name> 214 <description>Map Tilde to nothing</description> 215 </configItem> 216 </option> 217 <option> 218 <configItem> 219 <name>custom:baz</name> 220 <description>Map Z to K</description> 221 </configItem> 222 </option> 223 </group> 224 </optionList> 225</xkbConfigRegistry> 226``` 227 228The default behavior of libxkbregistry ensures that the new layout and options 229are added to the system-provided layouts and options. 230 231For details on the XML format, see DTD in `<datadir>/X11/xkb/rules/xkb.dtd` 232and the system-provided XML files in `<datadir>/X11/xkb/rulies/xkb.dtd`. 233