Package: kalamine
A text-based, cross-platform Keyboard Layout Maker.InstallTo install kalamine, all you need is a Python 3.8+ environment andpip:# to install kalaminepython3-mpipinstall--userkalamine# to upgrade kalaminepython3-mpipinstall--user--upgradekalamine# to uninstall kalaminepython3-mpipuninstall--userkalamineHowever, we recommend usingpipxrather thanpipas it providespyenvcontainment, which is a much saner approach and is becoming mandatory on many
operating systems (e.g. Arch Linux). It is even simpler from a user perspective:# to install kalaminepipxinstallkalamine# to upgrade kalaminepipxupgradekalamine# to uninstall kalaminepipxuninstallkalamineArch Linux users may use theAUR package:yay-Skalamine-gitDeveloper-specific installation instructions can be found in theCONTRIBUTING.mdfile.Building Distributable LayoutsCreate a keyboard layout withkalamine new:kalaminenewlayout.toml# basic layoutkalaminenewlayout.toml--altgr# layout with an AltGr layerkalaminenewlayout.toml--1dk# layout with a custom dead keykalaminenewlayout.toml--geometryERGO# apply an ortholinear geometryEdit this layout with your preferred text editor:theuser guideis available at the end of the*.tomlfilethe layout can be rendered and emulated withkalamine watch(see next section)Build your layout:kalaminebuildlayout.tomlGet all distributable keyboard drivers:dist/├─layout.ahk# Windows (user)├─layout.klc# Windows (admin)├─layout.keylayout# macOS├─layout.xkb_keymap# Linux (user)├─layout.xkb_symbols# Linux (root)├─layout.json# web└─layout.svgYou can also ask for a single target by specifying the file extension:kalaminebuildlayout.toml--outlayout.xkb_symbolsEmulating LayoutsYour layout can be emulated in a browser — including dead keys and an AltGr layer, if any.$kalaminewatchlayout.tomlServerstarted:http://localhost:1664Check your browser, type in the input area, test your layout. Changes on your TOML file are auto-detected and reloaded automatically.Press Ctrl-C when you’re done, and kalamine will write all platform-specific files.Using Distributable LayoutsWindows (user):*.ahkdownload theAHK 1.1 archiveload the*.ahkscript with it.The keyboard layout appears in the notification area. It can be enabled/disabled by pressing both Alt keys.You may also use Ahk2Exe to turn your*.ahkscript into an executable file. TheU32 Unicode 32-bit.binsetting seems to work fine.Windows (admin):*.klcNote: this applies only if you want to use the*.klcfile.
A better approach is to usewkalamine(see below).get a keyboard layout installer:MSKLC(freeware) orKbdEdit(shareware);load the*.klcfile with it;run this installer to generate a setup program;run the setup program;restart your session, even if Windows doesn’t ask you to.The keyboard layout appears in the language bar.Note: in some cases, custom dead keys may not be supported any more by MSKLC on Windows 10/11.
KbdEdit works fine, but its installers are not signed.
WKalamine works fine as well (see below) and its installers are signed.Basic developer info available in Kalamine’sKLC documentation page.macOS:*.keylayoutcopy your*.keylayoutfile into:either~/Library/Keyboard Layoutsfor the current user only,or/Library/Keyboard Layoutsfor all users;restart your session.The keyboard layout appears in the “Language and Text” preferences, “Input Methods” tab.Linux (root):*.xkb_symbolsThis is by far the simplest method to install a custom keyboard layout on Linux.Recent versions of XKB allowonecustom keyboard layout in root space:sudocplayout.xkb_symbols${XKB_CONFIG_ROOT:-/usr/share/X11/xkb}/symbols/customYour keyboard layout will be listed as “Custom” in the keyboard settings.
This works on both Wayland and X.Org. Depending on your system, you might have to relog to your session or to reboot X completely.On X.Org you can also select your keyboard layout from the command line:setxkbmapcustom# select your keyboard layoutsetxkbmapus# get back to QWERTYOn Wayland, this depends on your compositor. For Sway, tweak your keyboard input section like this:inputtype:keyboard {xkb_layout"custom"}Linux (user):*.xkb_keymap*.xkb_keymapkeyboard descriptions can be applied in user-space. The main limitation is that the keyboard layout won’t show up in the keyboard settings.On X.Org it is straight-forward withxkbcomp:xkbcomp-w10layout.xkb_keymap$DISPLAYAgain,setxkbmapcan be used to get back to the standard us-qwerty layout on X.Org:setxkbmapusOn Wayland, this depends on your compositor. For Sway, tweak your keyboard input section like this:inputtype:keyboard {xkb_file/path/to/layout.xkb_keymap}WKalaminewkalamineis a Windows-specific CLI tool to createMSKLCsetup packages.This is kind of a hack, but it provides an automatic way to build setup packages on Windows and more importantly, these setup packages overcome MSKLC’s limitations regarding chained dead keys and AltGr+Space combos.It is done by generating the C layout file, and tricking MSKLC to use it by setting it as read-only before.Make sure MSKLC is installed and build your installer:wkalaminebuildlayout.tomland you should get a[layout]\setup.exeexecutable to install the layout.Remember to log out and log back in to apply the changes.XKalaminexkalamineis a Linux-specific CLI tool for installing and managing keyboard layouts with XKB, so that they can be listed in the system’s keyboard preferences.Wayland (user)OnmostWayland environments, keyboard layouts can be installed in user-space:# Install a YAML/TOML keyboard layout into ~/.config/xkbxkalamineinstalllayout.toml# Uninstall Kalamine layouts from ~/.config/xkbxkalamineremoveus/prog# remove the kalamine 'prog' layoutxkalamineremovefr# remove all kalamine layouts for Frenchxkalamineremove"*"# remove all kalamine layouts# List available keyboard layoutsxkalaminelist# list all kalamine layoutsxkalaminelistfr# list all kalamine layouts for Frenchxkalaminelistus--all# list all layouts for US Englishxkalaminelist--all# list all layouts, ordered by localeOnce installed, layouts are selectable in the desktop environment’s keyboard preferences. On Sway, you can also select a layout like this:inputtype:keyboard {xkb_layout"us"xkb_variant"prog"}Note: some desktops like KDE Plasma, despite using Wayland, do not support
keyboards layouts in~/.config:xkbout of the box. In such cases, usingxkalamineassudois required, as described below.X.Org (root)On X.Org, a layout can be applied on the fly in user-space:# Equivalent to `xkbcomp -w10 layout.xkb_keymap $DISPLAY`xkalamineapplylayout.tomlHowever, installing a layout so it can be selected in the keyboard preferences requiressudoprivileges:# Install a YAML/TOML keyboard layout into /usr/share/X11/xkbsudoenv"PATH=$PATH"xkalamineinstalllayout.toml# Uninstall Kalamine layouts from /usr/share/X11/xkbsudoenv"PATH=$PATH"xkalamineremoveus/progsudoenv"PATH=$PATH"xkalamineremovefrsudoenv"PATH=$PATH"xkalamineremove"*"Once installed, you can apply a keyboard layout like this:setxkbmapus-variantprogNote that updating XKB will delete all layouts installed usingsudo xkalamine install.Sadly, it seems there’s no way to install keyboard layouts in~/.config/xkbfor X.Org. The system keyboard preferences will probably list user-space kayouts, but they won’t be usable on X.Org.If you want custom keymaps on your machine, switch to Wayland (and/or fix any remaining issues preventing you from doing so) instead of hoping this will ever work on X.—Peter HuttererResourcesXKB is a tricky piece of software. The following resources might be helpful if you want to dig in:https://www.charvolant.org/doug/xkb/html/https://wiki.archlinux.org/title/X_keyboard_extensionhttps://wiki.archlinux.org/title/Xorg/Keyboard_configurationhttps://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-format-text-v1.mdAlternativehttps://github.com/39aldo39/klfc