diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1f2fb902..c4d97c2a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -80,6 +80,12 @@ say regenerates them in the same commit, and the check `schema-fresh` fails when it does not. The first line of the options file is the hash of the schema it was made from, which is how the check tells without running `schemars-nixgen`. +A change to what `komorebic hotkeys compile` prints for a key binding file shows +in `keybindings-fixtures`, which compares its output for every file of the +fixture corpus with `nix/tests/keybindings.expected`: write the file again with +the loop in `nix/tests/keybindings.nix`, and read the difference before +committing it. + ## VM tests A change that needs a real KWin to be checked comes with a VM test, next to diff --git a/README.md b/README.md index cb52f32b..9ae77d8e 100644 --- a/README.md +++ b/README.md @@ -143,13 +143,15 @@ The test of the signals for sleep and lock starts private D-Bus buses with `dbus-daemon`, which the dev shell has, and does nothing where there is none. `nix flake check` runs the same checks as derivations, plus `cargo deny`, the TOML and Nix formatting, the tests under `cargo nextest`, and -`nixos-module-eval`, which evaluates the NixOS module in real NixOS systems, on -Linux and on an Apple silicon Mac, `schema-fresh`, which compares the schemas and +`nixos-module-eval`, which evaluates the NixOS module in real NixOS systems, +`keybindings-fixtures`, which runs every key binding file of the fixture corpus +through `komorebic hotkeys compile` and compares what it prints with +`nix/tests/keybindings.expected`, `schema-fresh`, which compares the schemas and the options made from them with the Rust types, and `nix-options-validation`, -which checks the example configuration, in Nix and in JSON, against the schema. -On Linux it also builds the KWin effects and checks their files, and boots every -VM test, which needs KVM. A Mac runs the tests against the fake desktop, since -KWin only exists on Linux. `nix fmt` formats every file the checks look at. +which checks the example configuration, in Nix and in JSON, against the schema, +all on Linux and on an Apple silicon Mac. On Linux it also builds the KWin effects and checks +their files, and boots every VM test, which needs KVM. A Mac runs the tests against the fake +desktop, since KWin only exists on Linux. `nix fmt` formats every file the checks look at. The VM tests boot NixOS with Plasma and run a real KWin, on machines configured with the NixOS module, so every one of them runs komorebi as the module installs @@ -283,8 +285,8 @@ can be in files of their own, which `app_specific_configuration_path` names. workspace change layout with the number of windows it has, as the file's `layout_rules` do, and `generate-static-config` prints the settings the daemon has as a `komorebi.json`, and `replace-configuration` makes the daemon start over from -another file. `quickstart` writes an example configuration, and `enable-autostart` an -autostart entry that has Plasma start komorebi at login. The Rust types that read the file describe it as a JSON Schema +another file. `quickstart` writes an example configuration and sample key bindings, and +`enable-autostart` an autostart entry that has Plasma start komorebi at login. The Rust types that read the file describe it as a JSON Schema (`schema.json`, written by `just jsonschema` and printed by `static-config-schema`), and the module's `config` option is typed from that schema (`nix/komorebi-options.nix`, written by `just nixgen`), so a configuration written in Nix is checked when it is evaluated. @@ -328,7 +330,9 @@ which KDE runs by itself from a `.desktop` file, and those that need komorebi to register the keys and decide what each press does. `komorebic hotkeys compile` writes the static shortcuts, and the daemon runs the engine for the rest: it registers their keys with KWin's global shortcut daemon over the -session bus and runs the command of each press. +session bus and runs the command of each press. On NixOS, the module's +`keybindings` options do both: the static shortcuts go into the system profile, +and the unit starts the daemon with the file. ## Documentation @@ -336,6 +340,7 @@ The user guide starts at [`docs/index.md`](docs/index.md), [`docs/installation.md`](docs/installation.md) says how to install komorebi, [`docs/usage/configuration.md`](docs/usage/configuration.md) explains `komorebi.json`, [`docs/example-configurations.md`](docs/example-configurations.md) has an example of it, +[`docs/usage/keybindings.md`](docs/usage/keybindings.md) how to give komorebi key bindings, and [`docs/cli`](docs/cli) has a page for every `komorebic` subcommand, which `just docgen` writes from the subcommands' help. `cargo doc --workspace --no-deps --open` builds the API documentation. diff --git a/docs/dev/ARCHITECTURE.md b/docs/dev/ARCHITECTURE.md index 1c6886b8..12e9a991 100644 --- a/docs/dev/ARCHITECTURE.md +++ b/docs/dev/ARCHITECTURE.md @@ -929,8 +929,9 @@ reads as a [`StaticConfig`], pauses the old window manager and brings back the w ([`StaticConfig::preload`], [`WindowManager::init`], [`StaticConfig::reload`]) over the same command socket, and puts it where the old one was, so the daemon starts over from the file, with the windows the backend has, all of them in view, and a watcher on the new file. A file that does not read is logged and the old window manager stays. -`komorebic quickstart` writes the example file of the docs and `komorebic/applications.json` into -the config home, compiled into the binary, and asks before it writes over a file; +`komorebic quickstart` writes the example file of the docs, `komorebic/applications.json` and the +sample `skhdrc` of the docs into the config home, compiled into the binary, and asks before it +writes over a file; `komorebic enable-autostart` writes the XDG autostart entry that has Plasma start the daemon at login. The same types describe the file as a JSON Schema, which `schemars` derives: `komorebic @@ -1176,9 +1177,11 @@ The flake exports one module under two names, `nixosModules.default` and `configFile`, `config`, `applicationSpecificConfiguration`, `effects.borders.enable` and `effects.borders.package` (by default `pkgs.kde-rounded-corners-komorebi`, from the overlay), `effects.animation.enable` and `effects.animation.package` -(`pkgs.kwin-effect-geometry-change-komorebi`), and `execStart`, which is read-only: the module -sets it to `bin/komorebi` of the package with `--log-level`, and `--config` with a -`komorebi.json` when `configFile` or `config` is set. `config` is typed from +(`pkgs.kwin-effect-geometry-change-komorebi`), `keybindings` (`format`, `text` or `file`, `mode`, +`chordTimeout`, `layout`, `strict`, `appAliases`), and `execStart`, which is read-only: the module +sets it to `bin/komorebi` of the package with `--log-level`, `--config` with a `komorebi.json` +when `configFile` or `config` is set, and `--keybindings` and the options of the engine when there +are key bindings. `config` is typed from `nix/komorebi-options.nix`, the options `schemars-nixgen` makes from the schema of `komorebi.json`; the module writes it as JSON, with no null in it, and `configFile` and the written file both go through `check-jsonschema` against `schema.json` when the system is built (comment lines taken out @@ -1198,7 +1201,14 @@ With `services.komorebi.enable`, the module: `/run/current-system/sw/bin` instead of the store paths NixOS gives a unit; - runs `komorebic hotkeys release` after the daemon has stopped (`ExecStopPost`), which unregisters the keys a daemon that was killed left in kglobalaccel; -- asserts that Plasma 6 is enabled. +- asserts that Plasma 6 is enabled; +- with key bindings, asserts that exactly one of `text` and `file` is set, that `format` is, + and that an skhdrc has no `.load`; runs `komorebic hotkeys compile` on them at build time in + the package `komorebi-keybindings` (`--strict` with `strict`), whose + `share/kglobalaccel/*.desktop` (the static shortcuts) it installs in the system profile, with + the diagnostics in its `diagnostics.txt` and in the build log; and passes the file (a store + path), its format and mode, the chord timeout and the aliases to the daemon in `execStart`, + so that the daemon plans the file as the build did and runs the rest. The VM tests run on machines built with it ([vm-tests.md](vm-tests.md)). Their headless node runs the daemon in test sessions, with a template unit, `komorebi@NAME`, that runs the module's @@ -1222,6 +1232,10 @@ module's unit. | The keys of a daemon that was killed are given back | systemd: `ExecStopPost` runs `komorebic hotkeys release` | `nixos-module-eval` ("the unit releases the keys of the daemon when it stops"), `vm-restart-survival` | none | | A daemon that is told to stop stays stopped, and the unit is not failed | systemd: the exit statuses of `Stop` (0) and of `SIGTERM` (130) are successes | `vm-module` | none | | The daemon has the `PATH` of a terminal in the session | the unit's environment, with NixOS's default `PATH` turned off | `nixos-module-eval`, `vm-module` | none | +| The static shortcuts the module installs and the bindings its daemon runs are one plan of one file | framework path: the build and `execStart` get the same store file, format and mode, and `plan` is deterministic | `nixos-module-eval` (the key binding scenarios), `vm-keys-skhd`, `vm-keys-whkd`, `vm-keys-sxhkd` | none | +| Key bindings have one source, a format, and no skhd `.load` | evaluation error: assertions of the module | `nixos-module-eval` ("text and file together", "without a format", "skhd's .load") | none | +| `strict` fails the build on a warning or an error | `komorebic hotkeys compile --strict` exits non-zero before it writes anything, and the module's build of the key bindings passes `--strict` only when `strict` is set and fails when `komorebic` does | `strict_refuses_a_file_with_a_warning_and_writes_nothing`, `nixos-module-eval` ("with strict, the build of the key bindings runs komorebic hotkeys compile --strict", "without strict ... no --strict") | none | +| What `hotkeys compile` prints for every file of the corpus is what was reviewed | test: a diff against `nix/tests/keybindings.expected` | `keybindings-fixtures` | writing the file again | | The VM suites run komorebi as the module installs it | framework path: the test nodes import the module, and `komorebi@NAME` runs its `execStart` | every VM suite | a suite's `node` can set `services.komorebi.enable = false` (`vm-render-smoke` does) | ## The parts @@ -1940,6 +1954,9 @@ plan needs no engine. A failure to start is logged, and the window manager runs the keys when the daemon and KWin go away. - [`komorebi-hotkeys/tests`](../../komorebi-hotkeys/tests): the corpus test and the comparison with `whkd-parser`. +- [`nix/tests/keybindings.nix`](../../nix/tests/keybindings.nix): `keybindings-fixtures`, and + [`nix/tests/vm/keys-corpus.py`](../../nix/tests/vm/keys-corpus.py), the corpus case `vm` + pressed in the three formats on a machine the module configured. - [`nix/nixos-module.nix`](../../nix/nixos-module.nix): the NixOS module; [`nix/tests/nixos-module.nix`](../../nix/tests/nixos-module.nix), its scenarios, evaluated in real NixOS systems; and [`nix/tests/vm/suites/module`](../../nix/tests/vm/suites/module/test.py), diff --git a/docs/dev/DESIGN.md b/docs/dev/DESIGN.md index 19501b51..8a1815e5 100644 --- a/docs/dev/DESIGN.md +++ b/docs/dev/DESIGN.md @@ -748,7 +748,8 @@ and a komorebi process that was killed leaves its keys registered and dead until released. Which of the two is the default is still open for a decision. `PlanMode::default()` is the -one place it is set, and `komorebic hotkeys compile` takes its default from there. +one place it is set, and `komorebic hotkeys compile` and the daemon's `--keybindings-mode` +take their default from there; the NixOS module's `keybindings.mode` repeats it, `"engine"`. ## Why does the engine grab and give back keys, instead of using KDE's own key sequences? diff --git a/docs/dev/PLATFORM.md b/docs/dev/PLATFORM.md index 1b6791ac..c84c64ed 100644 --- a/docs/dev/PLATFORM.md +++ b/docs/dev/PLATFORM.md @@ -372,6 +372,7 @@ named after the combo (`Alt+H`); an action's id is `["komorebi", "Alt+H", "komor | `$XDG_CACHE_HOME/komorebi` (`~/.cache/komorebi`) | the palettes made from wallpapers, a file for each picture and variant, `NAME-HASH.base16.VARIANT.json` | never removed by komorebi; made again when the picture's path, size or time of last change differ | | `$XDG_DATA_HOME/komorebi/komorebi.log.YYYY-MM-DD` | the daemon's log, with colors, which `komorebic log` follows | a file a day (the UTC date), never removed by komorebi | | `$XDG_DATA_HOME/komorebi/komorebi_plaintext.log.YYYY-MM-DD` | the same log without colors | as above | +| `/run/current-system/sw/share/kglobalaccel/komorebi-*.desktop` | on NixOS, the static shortcuts of `services.komorebi.keybindings`, which the module compiles at build time into the package `komorebi-keybindings` | the system's: KWin reads them when the session starts | | `$XDG_DATA_HOME/kglobalaccel/komorebi-*.desktop` | the static shortcuts `komorebic hotkeys compile` and `komorebic export-kde-shortcuts` write, each with `X-Komorebi-Generated=true` | replaced at every write: the files with that key are removed, and no other | | `$KOMOREBI_CONFIG_HOME/{skhdrc,whkdrc,sxhkdrc}` | the key binding file `komorebic hotkeys compile` and the daemon read when they are given none (the first that exists), and the skhdrc of `export-kde-shortcuts` | the user's; the daemon reads it once, at start | diff --git a/docs/dev/vm-tests.md b/docs/dev/vm-tests.md index 3abf1968..aa71f603 100644 --- a/docs/dev/vm-tests.md +++ b/docs/dev/vm-tests.md @@ -41,7 +41,10 @@ A suite has two files: `services.komorebi`). - `test.py` is the test, a Python script for the NixOS test driver. It is prefixed with `SCALE = `, how many times slower than KVM the machine - is. + is. Suites that run the same test on different nodes set `script` to a file + they share instead, relative to their directory: `vm-keys-skhd`, + `vm-keys-whkd` and `vm-keys-sxhkd` run `../../keys-corpus.py`, each with the + key bindings of its format in its `node`. ## Nodes diff --git a/docs/example-configurations.md b/docs/example-configurations.md index c17942dc..842afa19 100644 --- a/docs/example-configurations.md +++ b/docs/example-configurations.md @@ -5,6 +5,11 @@ starting out easier, the repository has an example configuration, [`docs/komorebi.example.json`](komorebi.example.json), which is kept working: a test loads it with every change. +Besides `komorebi.json`, komorebi for KDE is configured by the NixOS module, which installs it and +starts it with every Plasma session ([Installing komorebi](installation.md)), and by a key binding +file in the format of skhd, whkd or sxhkd ([Key bindings](usage/keybindings.md)); examples of both +are further down. + ## komorebi.json The example sets some defaults and gives the first monitor eight workspaces, each with a @@ -73,8 +78,9 @@ different layout. This page has the file as it is: } ``` -`komorebic quickstart` writes it, and the `applications.json` below, where the daemon looks for -them ([Quickstart and autostart](usage/quickstart-and-autostart.md)). Or put it there yourself, +`komorebic quickstart` writes it, the `applications.json` below and an `skhdrc` of +[sample key bindings](#key-bindings), where the daemon looks for them +([Quickstart and autostart](usage/quickstart-and-autostart.md)). Or put it there yourself, `~/.config/komorebi/komorebi.json`, or give it to the daemon with `komorebic start --config`. [Configuration](usage/configuration.md) explains every key and where the daemon looks. The settings of a monitor with more than one entry in `monitors`, and of each workspace, are there too. @@ -196,3 +202,58 @@ The `grid` layout does not support resizing windows tiles. +-----+-----+ +---+---+---+ +---+---+---+ +---+---+---+ 4 windows 5 windows 6 windows 7 windows ``` + +## A NixOS configuration + +The module and the sample key bindings of the repository, with every binding a static shortcut +can be made one, and the engine for the rest: + +```nix +{ + services.desktopManager.plasma6.enable = true; + + services.komorebi = { + enable = true; + keybindings = { + format = "skhd"; + file = ./skhdrc; + mode = "auto"; + # the names an skhdrc gives applications are those of macOS + appAliases."Google Chrome" = [ "google-chrome" ]; + }; + }; +} +``` + +The key bindings can also be written in the configuration itself: + +```nix +{ + services.komorebi.keybindings = { + format = "sxhkd"; + text = '' + alt + {h,j,k,l} + komorebic focus {left,down,up,right} + alt + shift + {h,j,k,l} + komorebic move {left,down,up,right} + ''; + }; +} +``` + +## Key bindings + +[`skhdrc.sample`](skhdrc.sample), [`whkdrc.sample`](whkdrc.sample) and +[`sxhkdrc.sample`](sxhkdrc.sample) bind the same keys to the same `komorebic` commands in the +three formats: focusing, moving, stacking and resizing windows, the layouts, and the +workspaces. Each is a starting point for a file of your own, in the format you know. Their +bindings are all plain ones, so with `mode = "auto"` every one of them is a static shortcut, +and with the default mode, `engine`, the daemon runs every one. + +Copy one to `~/.config/komorebi`, where the daemon and `komorebic hotkeys compile` look for a +key binding file when they are given none, to use it without NixOS: + +```sh +mkdir -p ~/.config/komorebi +cp docs/skhdrc.sample ~/.config/komorebi/skhdrc +``` diff --git a/docs/index.md b/docs/index.md index ba795009..db750b70 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,8 +18,10 @@ files for `komorebi`, but these will always remain opt-in and off-by-default. _komorebi_ only responds to the events KWin reports about windows and to the messages it receives on a dedicated socket. _komorebic_ is a CLI that writes messages on _komorebi_'s -socket. _komorebi_ doesn't handle any keyboard or mouse inputs: a program that binds keys, -such as the custom shortcuts in Plasma's System Settings, runs _komorebic_ commands. +socket. _komorebi_ doesn't read the keyboard or the mouse: a key runs a _komorebic_ command, +as a global shortcut of KDE. komorebi makes those shortcuts from a key binding file in the +format of skhd, whkd or sxhkd ([Key bindings](usage/keybindings.md)); the custom shortcuts of +Plasma's System Settings work too. ```text PROCESS SOCKET @@ -32,6 +34,9 @@ key bindings --------> komorebic <------> komorebi the flake's module, which also starts komorebi with every Plasma session, and from source anywhere else. [Running komorebi](usage/running-komorebi.md) explains how to start and stop the daemon, ask it what it is doing and read its log. +[Key bindings](usage/keybindings.md) explains how to bind keys to `komorebic` commands with +an skhdrc, a whkdrc or an sxhkdrc, and [Example configurations](example-configurations.md) has +a NixOS configuration and sample key bindings in the three formats. [Focusing windows](usage/focusing-windows.md) explains how to give the focus to another window, [Moving windows](usage/moving-windows.md) how to move a window to another tile, [Stacking windows](usage/stacking-windows.md) how to put windows on one tile, have the others wait diff --git a/docs/installation.md b/docs/installation.md index 4f662c7a..795d6853 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -87,7 +87,16 @@ the repository's `rust-toolchain.toml` selects, whatever nixpkgs your system use | `services.komorebi.effects.borders.package` | `pkgs.kde-rounded-corners-komorebi` | The effect: KDE Rounded Corners 0.11.0, built against the KWin of the system and not loaded until komorebi asks. | | `services.komorebi.effects.animation.enable` | `true` | Installs the KWin effect that animates komorebi's windows going to their places. Whether windows are animated is komorebi's own setting ([Animation](usage/animation.md)). KWin finds effects when it starts: log in again after the first switch. | | `services.komorebi.effects.animation.package` | `pkgs.kwin-effect-geometry-change-komorebi` | The effect: Geometry Change, a scripted effect that is not loaded until komorebi asks. | -| `services.komorebi.execStart` | read only | The command line the unit starts komorebi with, built from `package`, `logLevel` and `configFile` or `config`. A unit of your own that runs komorebi uses it to start komorebi the same way. | +| `services.komorebi.execStart` | read only | The command line the unit starts komorebi with, built from `package`, `logLevel`, `configFile` or `config`, and `keybindings`. A unit of your own that runs komorebi uses it to start komorebi the same way. | +| `services.komorebi.keybindings.format` | `null` | `"skhd"`, `"whkd"` or `"sxhkd"`: the format of the key bindings. Required with `text` or `file`. | +| `services.komorebi.keybindings.text`, `.file` | `null` | The key bindings, or the file they are in: exactly one of the two. | +| `services.komorebi.keybindings.mode` | `"engine"` | Which bindings are static shortcuts, installed in the system profile, and which the daemon runs: `"engine"`, `"auto"` or `"static"`. | +| `services.komorebi.keybindings.chordTimeout` | `3000` | How long, in milliseconds, the daemon waits for the next key of a chord chain. | +| `services.komorebi.keybindings.layout` | `"us"` | The keyboard layout of positional key names; `"us"` is the only one. | +| `services.komorebi.keybindings.strict` | `false` | Fail the build when something in the key bindings is not realized as its own hotkey daemon realizes it. | +| `services.komorebi.keybindings.appAliases` | `{ }` | Other names of an application, for the bindings that are for one application. | + +[Key bindings](usage/keybindings.md) explains the key binding options. `config` takes the keys of `komorebi.json` ([Configuration](usage/configuration.md)) as Nix, and a value of the wrong kind, or a layout that does not exist, is an error when the configuration is diff --git a/docs/skhdrc.sample b/docs/skhdrc.sample new file mode 100644 index 00000000..36b68b79 --- /dev/null +++ b/docs/skhdrc.sample @@ -0,0 +1,71 @@ +# the komorebi sample configuration + +# Focus windows +alt - h : komorebic focus left +alt - j : komorebic focus down +alt - k : komorebic focus up +alt - l : komorebic focus right +alt + shift - 0x21 : komorebic cycle-focus previous # 0x21 is [ +alt + shift - 0x1E : komorebic cycle-focus next # 0x1E is ] + +# Move windows +alt + shift - h : komorebic move left +alt + shift - j : komorebic move down +alt + shift - k : komorebic move up +alt + shift - l : komorebic move right +alt + shift - return : komorebic promote + +# Stack windows +ctrl + alt - left : komorebic stack left +ctrl + alt - down : komorebic stack down +ctrl + alt - up : komorebic stack up +ctrl + alt - right : komorebic stack right +alt - 0x29 : komorebic unstack # 0x29 is ; +alt - 0x21 : komorebic cycle-stack previous # 0x21 is [ +alt - 0x1E : komorebic cycle-stack next # 0x1E is ] + +# Workspace layer +alt + shift - 0x29 : komorebic toggle-workspace-layer # 0x29 is ; + +# Resize +alt - 0x18 : komorebic resize-axis horizontal increase # 0x18 is + +alt - 0x1B : komorebic resize-axis horizontal decrease # 0x1B is - +alt + shift - 0x18 : komorebic resize-axis vertical increase +alt + shift - 0x1B : komorebic resize-axis vertical decrease + +# Manipulate windows +alt - t : komorebic toggle-float +alt + shift - t : komorebic toggle-workspace-float-override +alt + shift - f : komorebic toggle-monocle + +# Window manager options +alt + shift - r : komorebic retile +alt - p : komorebic toggle-pause +alt - 0 : komorebic toggle-window-container-behaviour + +# Layouts +alt - x : komorebic flip-layout horizontal +alt - y : komorebic flip-layout vertical +alt + shift - x : komorebic session-float-rule + +# Workspaces +alt - 1 : komorebic focus-workspace 0 +alt - 2 : komorebic focus-workspace 1 +alt - 3 : komorebic focus-workspace 2 +alt - 4 : komorebic focus-workspace 3 +alt - 5 : komorebic focus-workspace 4 +alt - 6 : komorebic focus-workspace 5 +alt - 7 : komorebic focus-workspace 6 +alt - 8 : komorebic focus-workspace 7 +alt - 9 : komorebic focus-workspace 8 + +# Move windows across workspaces +alt + shift - 1 : komorebic move-to-workspace 0 +alt + shift - 2 : komorebic move-to-workspace 1 +alt + shift - 3 : komorebic move-to-workspace 2 +alt + shift - 4 : komorebic move-to-workspace 3 +alt + shift - 5 : komorebic move-to-workspace 4 +alt + shift - 6 : komorebic move-to-workspace 5 +alt + shift - 7 : komorebic move-to-workspace 6 +alt + shift - 8 : komorebic move-to-workspace 7 +alt + shift - 9 : komorebic move-to-workspace 8 \ No newline at end of file diff --git a/docs/sxhkdrc.sample b/docs/sxhkdrc.sample new file mode 100644 index 00000000..e2cf288e --- /dev/null +++ b/docs/sxhkdrc.sample @@ -0,0 +1,121 @@ +# the komorebi sample configuration + +# Focus windows +alt + h + komorebic focus left +alt + j + komorebic focus down +alt + k + komorebic focus up +alt + l + komorebic focus right +alt + shift + bracketleft + komorebic cycle-focus previous +alt + shift + bracketright + komorebic cycle-focus next + +# Move windows +alt + shift + h + komorebic move left +alt + shift + j + komorebic move down +alt + shift + k + komorebic move up +alt + shift + l + komorebic move right +alt + shift + Return + komorebic promote + +# Stack windows +ctrl + alt + Left + komorebic stack left +ctrl + alt + Down + komorebic stack down +ctrl + alt + Up + komorebic stack up +ctrl + alt + Right + komorebic stack right +alt + semicolon + komorebic unstack +alt + bracketleft + komorebic cycle-stack previous +alt + bracketright + komorebic cycle-stack next + +# Workspace layer +alt + shift + semicolon + komorebic toggle-workspace-layer + +# Resize +alt + equal + komorebic resize-axis horizontal increase +alt + minus + komorebic resize-axis horizontal decrease +alt + shift + equal + komorebic resize-axis vertical increase +alt + shift + minus + komorebic resize-axis vertical decrease + +# Manipulate windows +alt + t + komorebic toggle-float +alt + shift + t + komorebic toggle-workspace-float-override +alt + shift + f + komorebic toggle-monocle + +# Window manager options +alt + shift + r + komorebic retile +alt + p + komorebic toggle-pause +alt + 0 + komorebic toggle-window-container-behaviour + +# Layouts +alt + x + komorebic flip-layout horizontal +alt + y + komorebic flip-layout vertical +alt + shift + x + komorebic session-float-rule + +# Workspaces +alt + 1 + komorebic focus-workspace 0 +alt + 2 + komorebic focus-workspace 1 +alt + 3 + komorebic focus-workspace 2 +alt + 4 + komorebic focus-workspace 3 +alt + 5 + komorebic focus-workspace 4 +alt + 6 + komorebic focus-workspace 5 +alt + 7 + komorebic focus-workspace 6 +alt + 8 + komorebic focus-workspace 7 +alt + 9 + komorebic focus-workspace 8 + +# Move windows across workspaces +alt + shift + 1 + komorebic move-to-workspace 0 +alt + shift + 2 + komorebic move-to-workspace 1 +alt + shift + 3 + komorebic move-to-workspace 2 +alt + shift + 4 + komorebic move-to-workspace 3 +alt + shift + 5 + komorebic move-to-workspace 4 +alt + shift + 6 + komorebic move-to-workspace 5 +alt + shift + 7 + komorebic move-to-workspace 6 +alt + shift + 8 + komorebic move-to-workspace 7 +alt + shift + 9 + komorebic move-to-workspace 8 diff --git a/docs/usage/keybindings.md b/docs/usage/keybindings.md new file mode 100644 index 00000000..69b965ab --- /dev/null +++ b/docs/usage/keybindings.md @@ -0,0 +1,120 @@ +# Key bindings + +komorebi reads key bindings from a file in the format of skhd (`skhdrc`), whkd (`whkdrc`) or +sxhkd (`sxhkdrc`), the hotkey daemons of komorebi on macOS and on Windows and of X11 window +managers, so an existing file can be used as it is. On Plasma under Wayland no program sees +the keys of another, so the keys are KDE's global shortcuts, in one of two ways: + +- **Static shortcuts**: KDE runs the command of the key by itself, from a `.desktop` file. A + static shortcut works when komorebi is not running and shows in System Settings, where it + can be changed, but it is one combo, pressed, the same in every application, and KDE takes + about 0.2 seconds to start its command. +- **The engine**: the komorebi daemon registers the keys with KDE and runs the command of each + press itself, a few milliseconds after the key. It realizes what a static shortcut cannot: + modes, chord chains, bindings that fire on release, bindings that do something else in each + application, a blacklist and a pause binding. It works only while the daemon runs. + +The mode decides which bindings go where: + +| Mode | Static shortcuts | The engine | +|---|---|---| +| `engine` (the default) | none | every binding | +| `auto` | every binding that can be one, in a file with no modes, blacklist or pause binding | the others | +| `static` | every binding that can be one | none: the others are left out, with a warning | + +[`skhdrc.sample`](../skhdrc.sample), [`whkdrc.sample`](../whkdrc.sample) and +[`sxhkdrc.sample`](../sxhkdrc.sample) are the same bindings in the three formats. + +## On NixOS + +The module's `keybindings` options take the file or its text, and do the rest: the static +shortcuts are installed in the system profile, where KDE finds them when you log in, and the +daemon is started with the file and the same mode. + +```nix +services.komorebi = { + enable = true; + keybindings = { + format = "skhd"; + file = ./skhdrc; + mode = "auto"; + }; +}; +``` + +| Option | Default | What it does | +|---|---|---| +| `keybindings.format` | none | `"skhd"`, `"whkd"` or `"sxhkd"`; required with `text` or `file`. | +| `keybindings.text`, `keybindings.file` | none | The bindings, or the file they are in: exactly one of the two. skhd's `.load` is refused, since the file it reads would not be in the store. | +| `keybindings.mode` | `"engine"` | The mode, as in the table above. | +| `keybindings.chordTimeout` | `3000` | How long, in milliseconds, the engine waits for the next key of a chord chain. | +| `keybindings.layout` | `"us"` | The keyboard layout positional key names are read with; `"us"` is the only one. | +| `keybindings.strict` | `false` | Fail the build when something in the file is not realized as its own daemon realizes it. | +| `keybindings.appAliases` | `{ }` | Other names of an application, for the bindings that are for one application: `{ firefox = [ "firefox-esr" ]; }`. | + +What `komorebic hotkeys compile` had to say about the file (its diagnostics, below) is in the +build log, and in `diagnostics.txt` of the `komorebi-keybindings` package. + +## Without NixOS + +[`komorebic hotkeys compile`](../cli/hotkeys-compile.md) writes the static shortcuts of a +file to `~/.local/share/kglobalaccel`, where KDE reads them at the next login (`--reload` +hands new ones over at once), and the daemon runs the engine for the rest when it is given +the same mode. Without a file name both read the first of `skhdrc`, `whkdrc` and `sxhkdrc` in +`~/.config/komorebi`, where [`komorebic quickstart`](quickstart-and-autostart.md#quickstart) +writes the sample `skhdrc`. + +```sh +komorebic hotkeys compile --mode auto --reload +komorebic start -- --keybindings-mode auto +``` + +The daemon's options are `--keybindings FILE`, `--keybindings-format skhd|whkd|sxhkd` (when +the name does not end with one of those), `--keybindings-mode`, `--chord-timeout MS` and +`--app-alias NAME=ALIAS[,ALIAS]...`. +[`komorebic export-kde-shortcuts`](../cli/export-kde-shortcuts.md) writes the static +shortcuts of an skhdrc and leaves the rest out, for a setup without the engine. + +## What is realized, and what is not + +Everything the three formats bind keys with is realized, by a static shortcut or by the +engine, except what follows. `komorebic hotkeys compile --dry-run` prints a diagnostic for +each case the file has, with its line, and `--strict` (`keybindings.strict`) turns a warning +into a failure. + +- **Approximated**: side-specific modifiers (`lalt`, `rwin`) are either side, since KDE does + not tell them apart. A capturing mode (skhd's `@`) lets the keys it has no binding for reach + the application. skhd's `->` and sxhkd's `~` do not pass the key on to the application. A + key that is not the next of an sxhkd chain does not end the chain: only Escape and the chord + timeout do. A release binding (sxhkd's `@`) fires when any key of its combo is released + first. `.shell` is not followed: commands run through `sh -c`. +- **Not supported**: skhd's `fn` modifier, `.load`, `.alias`, key forwarding and key + sequences; mouse buttons; keypad keys; the X modifiers KDE has no equivalent for (`hyper`, + `meta`, `mode_switch`, `lock`, `mod2`, `mod3`, `mod5`, `any`). +- **Applications**: a binding for an application matches the executable, the Wayland app id + (`org.kde.konsole`) or the desktop entry of the focused window, whatever the case. skhd + and whkd name applications as macOS and Windows do, so a name that differs on KDE needs an + alias. +- **Positional keys**: skhd's keycodes (`0x21`) and whkd's `oem_*` keys are read as on a US + keyboard, and a shifted symbol is the one a US keyboard types (`alt + shift - 1` is + `Alt+!`). + +## When something goes wrong + +- [`komorebic check`](../cli/check.md) reads the file as `hotkeys compile` does, and says how + many bindings it has, which lines it cannot read, and whether the shortcut files KDE reads are + the ones `hotkeys compile` would write now ([Checking the setup](checking-the-setup.md#the-key-bindings)). +- [`komorebic hotkeys state`](../cli/hotkeys-state.md) shows the keys komorebi has + registered with KDE and what the engine is doing: its mode, the keys it holds, and whether + a chord chain is being typed. +- The daemon's log says which file it read and how many bindings went where, and, at the + debug level, every diagnostic, every mode it enters and every application that takes the + focus. +- A key that another shortcut already has is not given to komorebi, and the daemon logs a + warning that names it. The same binding as a static shortcut and in the engine is one such + case: give `hotkeys compile` and the daemon the same mode. +- A daemon that was killed leaves its keys registered with KDE, doing nothing. + [`komorebic hotkeys release`](../cli/hotkeys-release.md) gives them back (the NixOS + module's unit runs it whenever the daemon stops), and so does the next start of the daemon. +- [`komorebic hotkeys reload`](../cli/hotkeys-reload.md) has the daemon read its file again + after a change. diff --git a/docs/usage/quickstart-and-autostart.md b/docs/usage/quickstart-and-autostart.md index 2b22f36a..67a38c80 100644 --- a/docs/usage/quickstart-and-autostart.md +++ b/docs/usage/quickstart-and-autostart.md @@ -2,14 +2,17 @@ ## Quickstart -[`komorebic quickstart`](../cli/quickstart.md) writes two example files into the config home +[`komorebic quickstart`](../cli/quickstart.md) writes three example files into the config home (`~/.config/komorebi`, or `$KOMOREBI_CONFIG_HOME`), which it makes if it has to: - `komorebi.json`, which is [`docs/komorebi.example.json`](../example-configurations.md): eight workspaces on the first monitor, each with another layout, and some padding; - `applications.json`, which is [`komorebic/applications.json`](application-specific-configuration.md#the-file-komorebi-ships), - the rules `komorebi.json` names for the applications that need them. + the rules `komorebi.json` names for the applications that need them; +- `skhdrc`, which is [`docs/skhdrc.sample`](../skhdrc.sample): the [key bindings](keybindings.md) + of the sample, in the format of skhd, which the daemon and `komorebic hotkeys compile` read from + there. When a file is there already, `quickstart` asks before it writes over it, and leaves the file alone unless the answer is `y` or `yes`. It prints the files it wrote, and then tells you to run diff --git a/docs/usage/running-komorebi.md b/docs/usage/running-komorebi.md index 8cab3147..c0c2554f 100644 --- a/docs/usage/running-komorebi.md +++ b/docs/usage/running-komorebi.md @@ -61,6 +61,9 @@ removes its socket and exits. Stopping the process with `SIGINT` or `SIGTERM` do ## Key bindings +[Key bindings](keybindings.md) is the guide to key bindings, and to the NixOS module's +options for them; this section is a summary for a daemon started by hand. + komorebi reads key bindings from a file in the format of skhd, whkd or sxhkd. The daemon looks for `skhdrc`, `whkdrc` or `sxhkdrc` in `~/.config/komorebi` (or in `$KOMOREBI_CONFIG_HOME`) and takes the first it finds; `--keybindings FILE` names another, diff --git a/docs/whkdrc.sample b/docs/whkdrc.sample new file mode 100644 index 00000000..54d3979e --- /dev/null +++ b/docs/whkdrc.sample @@ -0,0 +1,72 @@ +# the komorebi sample configuration +.shell pwsh + +# Focus windows +alt + h : komorebic focus left +alt + j : komorebic focus down +alt + k : komorebic focus up +alt + l : komorebic focus right +alt + shift + oem_4 : komorebic cycle-focus previous # oem_4 is [ +alt + shift + oem_6 : komorebic cycle-focus next # oem_6 is ] + +# Move windows +alt + shift + h : komorebic move left +alt + shift + j : komorebic move down +alt + shift + k : komorebic move up +alt + shift + l : komorebic move right +alt + shift + return : komorebic promote + +# Stack windows +ctrl + alt + left : komorebic stack left +ctrl + alt + down : komorebic stack down +ctrl + alt + up : komorebic stack up +ctrl + alt + right : komorebic stack right +alt + oem_1 : komorebic unstack # oem_1 is ; +alt + oem_4 : komorebic cycle-stack previous # oem_4 is [ +alt + oem_6 : komorebic cycle-stack next # oem_6 is ] + +# Workspace layer +alt + shift + oem_1 : komorebic toggle-workspace-layer # oem_1 is ; + +# Resize +alt + oem_plus : komorebic resize-axis horizontal increase # oem_plus is + +alt + oem_minus : komorebic resize-axis horizontal decrease # oem_minus is - +alt + shift + oem_plus : komorebic resize-axis vertical increase +alt + shift + oem_minus : komorebic resize-axis vertical decrease + +# Manipulate windows +alt + t : komorebic toggle-float +alt + shift + t : komorebic toggle-workspace-float-override +alt + shift + f : komorebic toggle-monocle + +# Window manager options +alt + shift + r : komorebic retile +alt + p : komorebic toggle-pause +alt + 0 : komorebic toggle-window-container-behaviour + +# Layouts +alt + x : komorebic flip-layout horizontal +alt + y : komorebic flip-layout vertical +alt + shift + x : komorebic session-float-rule + +# Workspaces +alt + 1 : komorebic focus-workspace 0 +alt + 2 : komorebic focus-workspace 1 +alt + 3 : komorebic focus-workspace 2 +alt + 4 : komorebic focus-workspace 3 +alt + 5 : komorebic focus-workspace 4 +alt + 6 : komorebic focus-workspace 5 +alt + 7 : komorebic focus-workspace 6 +alt + 8 : komorebic focus-workspace 7 +alt + 9 : komorebic focus-workspace 8 + +# Move windows across workspaces +alt + shift + 1 : komorebic move-to-workspace 0 +alt + shift + 2 : komorebic move-to-workspace 1 +alt + shift + 3 : komorebic move-to-workspace 2 +alt + shift + 4 : komorebic move-to-workspace 3 +alt + shift + 5 : komorebic move-to-workspace 4 +alt + shift + 6 : komorebic move-to-workspace 5 +alt + shift + 7 : komorebic move-to-workspace 6 +alt + shift + 8 : komorebic move-to-workspace 7 +alt + shift + 9 : komorebic move-to-workspace 8 diff --git a/flake.nix b/flake.nix index 2a4d2768..e9522876 100644 --- a/flake.nix +++ b/flake.nix @@ -55,6 +55,8 @@ || (pkgs.lib.hasSuffix "docs/example-configurations.md" path) # the example a test loads, to see that the docs show one that works || (pkgs.lib.hasSuffix "docs/usage/wallpapers.md" path) + # the sample key bindings that `komorebic quickstart` includes + || (pkgs.lib.hasSuffix "docs/skhdrc.sample" path) # the key binding files the komorebi-hotkeys tests read || (pkgs.lib.hasInfix "/komorebi-hotkeys/tests/fixtures/" path); }; @@ -253,6 +255,13 @@ # the options the module is typed with, evaluated against the example configuration nix-options-validation = import ./nix/tests/default.nix { inherit pkgs; }; + # every file of the key binding corpus through `komorebic hotkeys compile`, as the + # module runs it + keybindings-fixtures = import ./nix/tests/keybindings.nix { + inherit pkgs; + komorebic = build.fullBuild; + }; + # The NixOS module in real NixOS systems, evaluated and never built, so a Mac checks it # too. A VM suite, `vm-module`, runs it. nixos-module-eval = import ./nix/tests/nixos-module.nix { diff --git a/komorebi-hotkeys/tests/corpus.rs b/komorebi-hotkeys/tests/corpus.rs index 1781bc8c..d7de1c9c 100644 --- a/komorebi-hotkeys/tests/corpus.rs +++ b/komorebi-hotkeys/tests/corpus.rs @@ -41,6 +41,7 @@ const CASES: &[(&str, &[&str])] = &[ ("pause", &["whkdrc"]), ("chords", &["sxhkdrc"]), ("release", &["sxhkdrc"]), + ("vm", &["skhdrc", "whkdrc", "sxhkdrc"]), ]; /// The keymap of each case, as [`render`] writes it. @@ -133,6 +134,11 @@ mode Alt+R [Alt+R] Esc: mode default", ), ("release", "release Alt+Space: komorebic toggle-float"), + ( + "vm", + "Alt+J: touch /tmp/keys-corpus-alt-j +Alt+,: touch /tmp/keys-corpus-alt-comma", + ), ]; /// Writes a keymap out, one line per binding, mode, blacklist and pause binding. Where each binding diff --git a/komorebi-hotkeys/tests/fixtures/vm.skhdrc b/komorebi-hotkeys/tests/fixtures/vm.skhdrc new file mode 100644 index 00000000..9f7007c1 --- /dev/null +++ b/komorebi-hotkeys/tests/fixtures/vm.skhdrc @@ -0,0 +1,4 @@ +# the case the VM suites press: a binding KDE can run by itself, and one on the comma key, which a +# shortcut file cannot hold, so that the engine runs it +alt - j : touch /tmp/keys-corpus-alt-j +alt - 0x2B : touch /tmp/keys-corpus-alt-comma diff --git a/komorebi-hotkeys/tests/fixtures/vm.sxhkdrc b/komorebi-hotkeys/tests/fixtures/vm.sxhkdrc new file mode 100644 index 00000000..3d70ccd5 --- /dev/null +++ b/komorebi-hotkeys/tests/fixtures/vm.sxhkdrc @@ -0,0 +1,6 @@ +# the case the VM suites press: a binding KDE can run by itself, and one on the comma key, which a +# shortcut file cannot hold, so that the engine runs it +alt + j + touch /tmp/keys-corpus-alt-j +alt + comma + touch /tmp/keys-corpus-alt-comma diff --git a/komorebi-hotkeys/tests/fixtures/vm.whkdrc b/komorebi-hotkeys/tests/fixtures/vm.whkdrc new file mode 100644 index 00000000..ee6ca5c0 --- /dev/null +++ b/komorebi-hotkeys/tests/fixtures/vm.whkdrc @@ -0,0 +1,6 @@ +# the case the VM suites press: a binding KDE can run by itself, and one on the comma key, which a +# shortcut file cannot hold, so that the engine runs it +.shell pwsh + +alt + j : touch /tmp/keys-corpus-alt-j +alt + oem_comma : touch /tmp/keys-corpus-alt-comma diff --git a/komorebi-hotkeys/tests/whkd_parser.rs b/komorebi-hotkeys/tests/whkd_parser.rs index f5431207..edcd0c34 100644 --- a/komorebi-hotkeys/tests/whkd_parser.rs +++ b/komorebi-hotkeys/tests/whkd_parser.rs @@ -96,7 +96,7 @@ fn every_whkdrc_of_the_corpus_reads_as_whkd_reads_it() { compared += 1; } } - assert_eq!(compared, 9); + assert_eq!(compared, 10); } #[test] diff --git a/komorebic/src/main.rs b/komorebic/src/main.rs index 414c528d..99c2c053 100644 --- a/komorebic/src/main.rs +++ b/komorebic/src/main.rs @@ -98,8 +98,8 @@ //! on a socket in the daemon's data directory, to which the daemon sends a notification after each //! event and each message it handles. //! -//! The others work without the daemon: `quickstart` writes an example `komorebi.json` and -//! `applications.json` in the config home, `enable-autostart` and `disable-autostart` write and +//! The others work without the daemon: `quickstart` writes an example `komorebi.json`, +//! `applications.json` and `skhdrc` in the config home, `enable-autostart` and `disable-autostart` write and //! remove the entry that has Plasma start komorebi at login, `start` runs `komorebi` in the //! background, with the `komorebi.json` it is given with `--config`, `check` reads the //! `komorebi.json` the daemon would and the key binding file, looks at the desktop, and reports @@ -1432,6 +1432,7 @@ fn main() -> eyre::Result<()> { let komorebi_json = include_str!("../../docs/komorebi.example.json").to_string(); let komorebi_path = HOME_DIR.join("komorebi.json"); let applications_path = HOME_DIR.join("applications.json"); + let skhdrc_path = HOME_DIR.join("skhdrc"); let mut written_files = Vec::new(); @@ -1439,6 +1440,9 @@ fn main() -> eyre::Result<()> { let applications_json = include_str!("../applications.json"); write_file_with_prompt(&applications_path, applications_json, &mut written_files)?; + + let skhdrc = include_str!("../../docs/skhdrc.sample"); + write_file_with_prompt(&skhdrc_path, skhdrc, &mut written_files)?; if written_files.is_empty() { println!("\nNo files were written.") } else { diff --git a/komorebic/tests/cli.rs b/komorebic/tests/cli.rs index 2e2775c3..1b942386 100644 --- a/komorebic/tests/cli.rs +++ b/komorebic/tests/cli.rs @@ -854,6 +854,10 @@ fn quickstart_writes_the_example_files_and_asks_before_it_overwrites_one() { std::fs::read_to_string(home.join("applications.json")).unwrap(), include_str!("../applications.json") ); + assert_eq!( + std::fs::read_to_string(home.join("skhdrc")).unwrap(), + include_str!("../../docs/skhdrc.sample") + ); assert!(stdout(&output).contains("The following example files were written")); assert!(stdout(&output).contains("komorebic start")); @@ -870,6 +874,11 @@ fn quickstart_writes_the_example_files_and_asks_before_it_overwrites_one() { std::fs::read_to_string(home.join("applications.json")).unwrap(), include_str!("../applications.json") ); + // the third question has no answer, which is not a yes + assert_eq!( + std::fs::read_to_string(home.join("skhdrc")).unwrap(), + include_str!("../../docs/skhdrc.sample") + ); assert!(stdout(&output).contains("Skipping")); } diff --git a/nix/nixos-module.nix b/nix/nixos-module.nix index cf5ffa56..f5ee757f 100644 --- a/nix/nixos-module.nix +++ b/nix/nixos-module.nix @@ -88,6 +88,42 @@ let } else null; + + kb = cfg.keybindings; + + # key bindings are configured when any of the three is set; the assertions say what is missing + keybindingsSet = kb.format != null || kb.text != null || kb.file != null; + # the file the daemon reads, named after its format so that it reads as one + keybindingsFile = + if kb.file != null then kb.file else pkgs.writeText "komorebi-${toString kb.format}rc" kb.text; + + # `komorebic hotkeys compile`: the static shortcuts of the file, in share/kglobalaccel, where KWin + # finds them in the system profile, and what komorebic had to say about the file + compiled = pkgs.runCommand "komorebi-keybindings" { } '' + mkdir -p $out/share/kglobalaccel + if ! ${lib.getExe' cfg.package "komorebic"} hotkeys compile \ + --format ${toString kb.format} --mode ${kb.mode} ${lib.optionalString kb.strict "--strict"} \ + ${keybindingsFile} --output $out/share/kglobalaccel 2> $out/diagnostics.txt; then + cat $out/diagnostics.txt >&2 + exit 1 + fi + cat $out/diagnostics.txt >&2 + ''; + + keybindingsArgs = [ + "--keybindings" + "${keybindingsFile}" + "--keybindings-format" + (toString kb.format) + "--keybindings-mode" + kb.mode + "--chord-timeout" + (toString kb.chordTimeout) + ] + ++ lib.concatMap (name: [ + "--app-alias" + (lib.escapeShellArg "${name}=${lib.concatStringsSep "," kb.appAliases.${name}}") + ]) (lib.attrNames kb.appAliases); in { options.services.komorebi = { @@ -279,12 +315,111 @@ in readOnly = true; description = '' The command line the unit starts komorebi with: `bin/komorebi` of `package`, with - `logLevel`, and with `--config` and the checked `komorebi.json` when `configFile` or - `config` is set. The module sets it, and setting it anywhere else is an error. A unit of your own that runs komorebi somewhere - else, as the VM tests do in their headless sessions, starts it with this, the way the - module does. + `logLevel`, with `--config` and the checked `komorebi.json` when `configFile` or `config` is + set, and with the key bindings when there are some. The module sets it, and setting it + anywhere else is an error. A unit of your own that runs komorebi somewhere else, as the VM + tests do in their headless sessions, starts it with this, the way the module does. ''; }; + + keybindings = { + format = lib.mkOption { + type = lib.types.nullOr ( + lib.types.enum [ + "skhd" + "whkd" + "sxhkd" + ] + ); + default = null; + example = "skhd"; + description = '' + The format of the key bindings: that of skhd's skhdrc, whkd's whkdrc or sxhkd's sxhkdrc. + Required with `text` or `file`. + ''; + }; + + text = lib.mkOption { + type = lib.types.nullOr lib.types.lines; + default = null; + example = '' + alt - h : komorebic focus left + alt - l : komorebic focus right + ''; + description = '' + The key bindings, written in `format`. Set this or `file`, not both. skhd's `.load`, + which reads another file, is refused: the file would not be in the store. + ''; + }; + + file = lib.mkOption { + type = lib.types.nullOr lib.types.path; + default = null; + example = lib.literalExpression "./skhdrc"; + description = "A file of key bindings, written in `format`. Set this or `text`, not both."; + }; + + mode = lib.mkOption { + type = lib.types.enum [ + "auto" + "engine" + "static" + ]; + default = "engine"; + description = '' + Which bindings KDE runs by itself, as static shortcuts that the module installs in the + system profile, and which the daemon registers and runs (the engine). `engine`: every + binding is the engine's. `auto`: every binding that can be a static shortcut is one (one + combo, pressed, the same in every application, in a file with no modes, blacklist or + pause binding), and the engine runs the others. `static`: only static shortcuts; what + needs the engine is left out, with a warning. A static shortcut works with no komorebi + running and shows in System Settings, but takes about 0.2 s to run its command; the + engine takes a few milliseconds. + ''; + }; + + chordTimeout = lib.mkOption { + type = lib.types.ints.positive; + default = 3000; + description = "How long, in milliseconds, the engine waits for the next key of a chord chain."; + }; + + layout = lib.mkOption { + type = lib.types.enum [ "us" ]; + default = "us"; + description = '' + The keyboard layout positional key names are read with: skhd's macOS keycodes (`0x21`) + and whkd's `oem_*` keys, and the symbol a shifted key types. `us` is the only one. + ''; + }; + + strict = lib.mkOption { + type = lib.types.bool; + default = false; + description = '' + Fail the build when something in the key bindings is not realized the way the file's own + hotkey daemon realizes it: a diagnostic of `komorebic hotkeys compile` that is a warning + or an error. The diagnostics are in the build log and in `diagnostics.txt` of the + `komorebi-keybindings` package either way. + ''; + }; + + appAliases = lib.mkOption { + type = lib.types.attrsOf (lib.types.listOf lib.types.str); + default = { }; + example = { + firefox = [ + "firefox-esr" + "librewolf" + ]; + }; + description = '' + Other names of an application, for the bindings that are for one application: an skhdrc + or a whkdrc names applications as macOS or Windows does, and KDE knows them by their + executable, app id or desktop entry. + ''; + }; + }; }; config = lib.mkMerge [ @@ -299,6 +434,7 @@ in "--config" "${komorebiConfigFile}" ] + ++ lib.optionals keybindingsSet keybindingsArgs ); services.komorebi.internal.configAttrs = configAttrs; } @@ -312,6 +448,33 @@ in session starts it. Set services.desktopManager.plasma6.enable = true. ''; } + { + assertion = keybindingsSet -> (kb.text != null) != (kb.file != null); + message = '' + services.komorebi.keybindings needs exactly one of text and file: the key bindings + themselves, or the file they are in. + ''; + } + { + assertion = keybindingsSet -> kb.format != null; + message = '' + services.komorebi.keybindings needs a format: "skhd", "whkd" or "sxhkd". + ''; + } + { + assertion = + !( + keybindingsSet + && kb.format == "skhd" + && lib.any (line: lib.hasPrefix ".load" (lib.trim line)) ( + lib.splitString "\n" (if kb.text != null then kb.text else builtins.readFile kb.file) + ) + ); + message = '' + services.komorebi.keybindings: skhd's .load is not supported. It reads another file, + which would not be in the store; put its bindings in this one. + ''; + } ]; warnings = @@ -335,7 +498,8 @@ in cfg.package ] ++ lib.optional cfg.effects.borders.enable cfg.effects.borders.package - ++ lib.optional cfg.effects.animation.enable cfg.effects.animation.package; + ++ lib.optional cfg.effects.animation.enable cfg.effects.animation.package + ++ lib.optional keybindingsSet compiled; # A user unit, so it runs for every user who logs in to Plasma. plasma-workspace.target is # the target of a Plasma session's services, and plasma-core.target, which it requires, is diff --git a/nix/tests/keybindings.expected b/nix/tests/keybindings.expected new file mode 100644 index 00000000..208a525b --- /dev/null +++ b/nix/tests/keybindings.expected @@ -0,0 +1,368 @@ +== blacklist.skhdrc +blacklist.skhdrc: line 7: note: every binding goes through the engine: the file has a blacklist +0 shortcuts would be written to shortcuts (0 new, 0 changed, 0 removed), 1 bindings need the engine + +== braces.skhdrc +Alt+H komorebic focus left +Alt+J komorebic focus down +Alt+K komorebic focus up +Alt+L komorebic focus right +Alt+1 komorebic focus-workspace 0 +Alt+2 komorebic focus-workspace 1 +Alt+3 komorebic focus-workspace 2 +Alt+! komorebic move-to-workspace 0 +Alt+@ komorebic move-to-workspace 1 +Alt+# komorebic move-to-workspace 2 +10 shortcuts would be written to shortcuts (10 new, 0 changed, 0 removed), 0 bindings need the engine + +== braces.sxhkdrc +Alt+H komorebic focus left +Alt+J komorebic focus down +Alt+K komorebic focus up +Alt+L komorebic focus right +Alt+1 komorebic focus-workspace 0 +Alt+2 komorebic focus-workspace 1 +Alt+3 komorebic focus-workspace 2 +Alt+! komorebic move-to-workspace 0 +Alt+@ komorebic move-to-workspace 1 +Alt+# komorebic move-to-workspace 2 +10 shortcuts would be written to shortcuts (10 new, 0 changed, 0 removed), 0 bindings need the engine + +== braces.whkdrc +braces.whkdrc: line 2: note: commands run through `sh -c`, not `pwsh` +Alt+H komorebic focus left +Alt+J komorebic focus down +Alt+K komorebic focus up +Alt+L komorebic focus right +Alt+1 komorebic focus-workspace 0 +Alt+2 komorebic focus-workspace 1 +Alt+3 komorebic focus-workspace 2 +Alt+! komorebic move-to-workspace 0 +Alt+@ komorebic move-to-workspace 1 +Alt+# komorebic move-to-workspace 2 +10 shortcuts would be written to shortcuts (10 new, 0 changed, 0 removed), 0 bindings need the engine + +== chords.sxhkdrc +chords.sxhkdrc: line 2: warning: in sxhkd a key that is not in the chain after `Alt+W` ends it; here only Escape and the chord timeout do +chords.sxhkdrc: line 2: note: every binding goes through the engine: the file declares modes +chords.sxhkdrc: line 6: warning: in sxhkd a key that is not in the chain after `Alt+R` ends it; here only Escape does +0 shortcuts would be written to shortcuts (0 new, 0 changed, 0 removed), 6 bindings need the engine + +== comments.skhdrc +Alt+H komorebic focus left +Alt+X komorebic flip-layout horizontal +2 shortcuts would be written to shortcuts (2 new, 0 changed, 0 removed), 0 bindings need the engine + +== comments.sxhkdrc +Alt+H komorebic focus left +Alt+X komorebic flip-layout horizontal +2 shortcuts would be written to shortcuts (2 new, 0 changed, 0 removed), 0 bindings need the engine + +== comments.whkdrc +comments.whkdrc: line 2: note: commands run through `sh -c`, not `pwsh` +Alt+H komorebic focus left +Alt+X komorebic flip-layout horizontal +2 shortcuts would be written to shortcuts (2 new, 0 changed, 0 removed), 0 bindings need the engine + +== define.skhdrc +define.skhdrc: line 5: note: Alt+B goes through the engine: it does something else in each application +Alt+H komorebic focus left +Alt+L komorebic focus right +2 shortcuts would be written to shortcuts (2 new, 0 changed, 0 removed), 1 bindings need the engine + +== define.whkdrc +define.whkdrc: line 2: note: commands run through `sh -c`, not `pwsh` +define.whkdrc: line 4: note: Alt+B goes through the engine: it does something else in each application +Alt+H komorebic focus left +Alt+L komorebic focus right +2 shortcuts would be written to shortcuts (2 new, 0 changed, 0 removed), 1 bindings need the engine + +== keycodes.skhdrc +Alt+[ komorebic cycle-stack previous +Alt+] komorebic cycle-stack next +Alt+; komorebic unstack +Alt+= komorebic resize-axis horizontal increase +Alt+- komorebic resize-axis horizontal decrease +Alt+{ komorebic cycle-focus previous +6 shortcuts would be written to shortcuts (6 new, 0 changed, 0 removed), 0 bindings need the engine + +== keycodes.sxhkdrc +Alt+[ komorebic cycle-stack previous +Alt+] komorebic cycle-stack next +Alt+; komorebic unstack +Alt+= komorebic resize-axis horizontal increase +Alt+- komorebic resize-axis horizontal decrease +Alt+{ komorebic cycle-focus previous +6 shortcuts would be written to shortcuts (6 new, 0 changed, 0 removed), 0 bindings need the engine + +== keycodes.whkdrc +keycodes.whkdrc: line 2: note: commands run through `sh -c`, not `pwsh` +Alt+[ komorebic cycle-stack previous +Alt+] komorebic cycle-stack next +Alt+; komorebic unstack +Alt+= komorebic resize-axis horizontal increase +Alt+- komorebic resize-axis horizontal decrease +Alt+{ komorebic cycle-focus previous +6 shortcuts would be written to shortcuts (6 new, 0 changed, 0 removed), 0 bindings need the engine + +== modes.skhdrc +modes.skhdrc: line 2: warning: `resize` captures every key in skhd; here the keys it has no binding for reach the application +modes.skhdrc: line 3: note: every binding goes through the engine: the file declares modes +0 shortcuts would be written to shortcuts (0 new, 0 changed, 0 removed), 6 bindings need the engine + +== modifiers.skhdrc +Meta+Return konsole +Ctrl+Alt+Left komorebic stack left +Alt+Shift+H komorebic move left +Ctrl+Shift+Right komorebic resize-edge right increase +Alt+! komorebic move-to-workspace 0 +Ctrl+Alt+( komorebic move-to-workspace 8 +Meta+Ctrl+Alt+Shift+A komorebic retile +Ctrl+Alt+Shift+M komorebic toggle-monocle +8 shortcuts would be written to shortcuts (8 new, 0 changed, 0 removed), 0 bindings need the engine + +== modifiers.sxhkdrc +Meta+Return konsole +Ctrl+Alt+Left komorebic stack left +Alt+Shift+H komorebic move left +Ctrl+Shift+Right komorebic resize-edge right increase +Alt+! komorebic move-to-workspace 0 +Ctrl+Alt+( komorebic move-to-workspace 8 +Meta+Ctrl+Alt+Shift+A komorebic retile +Ctrl+Alt+Shift+M komorebic toggle-monocle +8 shortcuts would be written to shortcuts (8 new, 0 changed, 0 removed), 0 bindings need the engine + +== modifiers.whkdrc +modifiers.whkdrc: line 2: note: commands run through `sh -c`, not `pwsh` +Meta+Return konsole +Ctrl+Alt+Left komorebic stack left +Alt+Shift+H komorebic move left +Ctrl+Shift+Right komorebic resize-edge right increase +Alt+! komorebic move-to-workspace 0 +Ctrl+Alt+( komorebic move-to-workspace 8 +Meta+Ctrl+Alt+Shift+A komorebic retile +Ctrl+Alt+Shift+M komorebic toggle-monocle +8 shortcuts would be written to shortcuts (8 new, 0 changed, 0 removed), 0 bindings need the engine + +== pause.whkdrc +pause.whkdrc: line 2: note: commands run through `sh -c`, not `pwsh` +pause.whkdrc: line 6: note: every binding goes through the engine: the file has a pause binding +0 shortcuts would be written to shortcuts (0 new, 0 changed, 0 removed), 1 bindings need the engine + +== plain.skhdrc +Alt+H komorebic focus left +Alt+J komorebic focus down +Alt+K komorebic focus up +Alt+L komorebic focus right +Alt+Q komorebic close +5 shortcuts would be written to shortcuts (5 new, 0 changed, 0 removed), 0 bindings need the engine + +== plain.sxhkdrc +Alt+H komorebic focus left +Alt+J komorebic focus down +Alt+K komorebic focus up +Alt+L komorebic focus right +Alt+Q komorebic close +5 shortcuts would be written to shortcuts (5 new, 0 changed, 0 removed), 0 bindings need the engine + +== plain.whkdrc +plain.whkdrc: line 2: note: commands run through `sh -c`, not `pwsh` +Alt+H komorebic focus left +Alt+J komorebic focus down +Alt+K komorebic focus up +Alt+L komorebic focus right +Alt+Q komorebic close +5 shortcuts would be written to shortcuts (5 new, 0 changed, 0 removed), 0 bindings need the engine + +== release.sxhkdrc +release.sxhkdrc: line 2: warning: a release binding fires when any key of its combo is released first +release.sxhkdrc: line 2: note: Alt+Space goes through the engine: it fires when the key is released +0 shortcuts would be written to shortcuts (0 new, 0 changed, 0 removed), 1 bindings need the engine + +== sample.skhdrc +Alt+H komorebic focus left +Alt+J komorebic focus down +Alt+K komorebic focus up +Alt+L komorebic focus right +Alt+{ komorebic cycle-focus previous +Alt+} komorebic cycle-focus next +Alt+Shift+H komorebic move left +Alt+Shift+J komorebic move down +Alt+Shift+K komorebic move up +Alt+Shift+L komorebic move right +Alt+Shift+Return komorebic promote +Ctrl+Alt+Left komorebic stack left +Ctrl+Alt+Down komorebic stack down +Ctrl+Alt+Up komorebic stack up +Ctrl+Alt+Right komorebic stack right +Alt+; komorebic unstack +Alt+[ komorebic cycle-stack previous +Alt+] komorebic cycle-stack next +Alt+: komorebic toggle-workspace-layer +Alt+= komorebic resize-axis horizontal increase +Alt+- komorebic resize-axis horizontal decrease +Alt++ komorebic resize-axis vertical increase +Alt+_ komorebic resize-axis vertical decrease +Alt+T komorebic toggle-float +Alt+Shift+T komorebic toggle-workspace-float-override +Alt+Shift+F komorebic toggle-monocle +Alt+Shift+R komorebic retile +Alt+P komorebic toggle-pause +Alt+0 komorebic toggle-window-container-behaviour +Alt+X komorebic flip-layout horizontal +Alt+Y komorebic flip-layout vertical +Alt+Shift+X komorebic session-float-rule +Alt+1 komorebic focus-workspace 0 +Alt+2 komorebic focus-workspace 1 +Alt+3 komorebic focus-workspace 2 +Alt+4 komorebic focus-workspace 3 +Alt+5 komorebic focus-workspace 4 +Alt+6 komorebic focus-workspace 5 +Alt+7 komorebic focus-workspace 6 +Alt+8 komorebic focus-workspace 7 +Alt+9 komorebic focus-workspace 8 +Alt+! komorebic move-to-workspace 0 +Alt+@ komorebic move-to-workspace 1 +Alt+# komorebic move-to-workspace 2 +Alt+$ komorebic move-to-workspace 3 +Alt+% komorebic move-to-workspace 4 +Alt+^ komorebic move-to-workspace 5 +Alt+& komorebic move-to-workspace 6 +Alt+* komorebic move-to-workspace 7 +Alt+( komorebic move-to-workspace 8 +50 shortcuts would be written to shortcuts (50 new, 0 changed, 0 removed), 0 bindings need the engine + +== sample.sxhkdrc +Alt+H komorebic focus left +Alt+J komorebic focus down +Alt+K komorebic focus up +Alt+L komorebic focus right +Alt+{ komorebic cycle-focus previous +Alt+} komorebic cycle-focus next +Alt+Shift+H komorebic move left +Alt+Shift+J komorebic move down +Alt+Shift+K komorebic move up +Alt+Shift+L komorebic move right +Alt+Shift+Return komorebic promote +Ctrl+Alt+Left komorebic stack left +Ctrl+Alt+Down komorebic stack down +Ctrl+Alt+Up komorebic stack up +Ctrl+Alt+Right komorebic stack right +Alt+; komorebic unstack +Alt+[ komorebic cycle-stack previous +Alt+] komorebic cycle-stack next +Alt+: komorebic toggle-workspace-layer +Alt+= komorebic resize-axis horizontal increase +Alt+- komorebic resize-axis horizontal decrease +Alt++ komorebic resize-axis vertical increase +Alt+_ komorebic resize-axis vertical decrease +Alt+T komorebic toggle-float +Alt+Shift+T komorebic toggle-workspace-float-override +Alt+Shift+F komorebic toggle-monocle +Alt+Shift+R komorebic retile +Alt+P komorebic toggle-pause +Alt+0 komorebic toggle-window-container-behaviour +Alt+X komorebic flip-layout horizontal +Alt+Y komorebic flip-layout vertical +Alt+Shift+X komorebic session-float-rule +Alt+1 komorebic focus-workspace 0 +Alt+2 komorebic focus-workspace 1 +Alt+3 komorebic focus-workspace 2 +Alt+4 komorebic focus-workspace 3 +Alt+5 komorebic focus-workspace 4 +Alt+6 komorebic focus-workspace 5 +Alt+7 komorebic focus-workspace 6 +Alt+8 komorebic focus-workspace 7 +Alt+9 komorebic focus-workspace 8 +Alt+! komorebic move-to-workspace 0 +Alt+@ komorebic move-to-workspace 1 +Alt+# komorebic move-to-workspace 2 +Alt+$ komorebic move-to-workspace 3 +Alt+% komorebic move-to-workspace 4 +Alt+^ komorebic move-to-workspace 5 +Alt+& komorebic move-to-workspace 6 +Alt+* komorebic move-to-workspace 7 +Alt+( komorebic move-to-workspace 8 +50 shortcuts would be written to shortcuts (50 new, 0 changed, 0 removed), 0 bindings need the engine + +== sample.whkdrc +sample.whkdrc: line 2: note: commands run through `sh -c`, not `pwsh` +Alt+H komorebic focus left +Alt+J komorebic focus down +Alt+K komorebic focus up +Alt+L komorebic focus right +Alt+{ komorebic cycle-focus previous +Alt+} komorebic cycle-focus next +Alt+Shift+H komorebic move left +Alt+Shift+J komorebic move down +Alt+Shift+K komorebic move up +Alt+Shift+L komorebic move right +Alt+Shift+Return komorebic promote +Ctrl+Alt+Left komorebic stack left +Ctrl+Alt+Down komorebic stack down +Ctrl+Alt+Up komorebic stack up +Ctrl+Alt+Right komorebic stack right +Alt+; komorebic unstack +Alt+[ komorebic cycle-stack previous +Alt+] komorebic cycle-stack next +Alt+: komorebic toggle-workspace-layer +Alt+= komorebic resize-axis horizontal increase +Alt+- komorebic resize-axis horizontal decrease +Alt++ komorebic resize-axis vertical increase +Alt+_ komorebic resize-axis vertical decrease +Alt+T komorebic toggle-float +Alt+Shift+T komorebic toggle-workspace-float-override +Alt+Shift+F komorebic toggle-monocle +Alt+Shift+R komorebic retile +Alt+P komorebic toggle-pause +Alt+0 komorebic toggle-window-container-behaviour +Alt+X komorebic flip-layout horizontal +Alt+Y komorebic flip-layout vertical +Alt+Shift+X komorebic session-float-rule +Alt+1 komorebic focus-workspace 0 +Alt+2 komorebic focus-workspace 1 +Alt+3 komorebic focus-workspace 2 +Alt+4 komorebic focus-workspace 3 +Alt+5 komorebic focus-workspace 4 +Alt+6 komorebic focus-workspace 5 +Alt+7 komorebic focus-workspace 6 +Alt+8 komorebic focus-workspace 7 +Alt+9 komorebic focus-workspace 8 +Alt+! komorebic move-to-workspace 0 +Alt+@ komorebic move-to-workspace 1 +Alt+# komorebic move-to-workspace 2 +Alt+$ komorebic move-to-workspace 3 +Alt+% komorebic move-to-workspace 4 +Alt+^ komorebic move-to-workspace 5 +Alt+& komorebic move-to-workspace 6 +Alt+* komorebic move-to-workspace 7 +Alt+( komorebic move-to-workspace 8 +50 shortcuts would be written to shortcuts (50 new, 0 changed, 0 removed), 0 bindings need the engine + +== scopes.skhdrc +scopes.skhdrc: line 2: note: Alt+N goes through the engine: it does something else in each application +Alt+H komorebic focus left +1 shortcuts would be written to shortcuts (1 new, 0 changed, 0 removed), 1 bindings need the engine + +== scopes.whkdrc +scopes.whkdrc: line 2: note: commands run through `sh -c`, not `pwsh` +scopes.whkdrc: line 4: note: Alt+N goes through the engine: it does something else in each application +Alt+H komorebic focus left +1 shortcuts would be written to shortcuts (1 new, 0 changed, 0 removed), 1 bindings need the engine + +== vm.skhdrc +vm.skhdrc: line 4: note: Alt+, goes through the engine: a comma cannot be written in `X-KDE-Shortcuts` +Alt+J touch /tmp/keys-corpus-alt-j +1 shortcuts would be written to shortcuts (1 new, 0 changed, 0 removed), 1 bindings need the engine + +== vm.sxhkdrc +vm.sxhkdrc: line 5: note: Alt+, goes through the engine: a comma cannot be written in `X-KDE-Shortcuts` +Alt+J touch /tmp/keys-corpus-alt-j +1 shortcuts would be written to shortcuts (1 new, 0 changed, 0 removed), 1 bindings need the engine + +== vm.whkdrc +vm.whkdrc: line 3: note: commands run through `sh -c`, not `pwsh` +vm.whkdrc: line 6: note: Alt+, goes through the engine: a comma cannot be written in `X-KDE-Shortcuts` +Alt+J touch /tmp/keys-corpus-alt-j +1 shortcuts would be written to shortcuts (1 new, 0 changed, 0 removed), 1 bindings need the engine + diff --git a/nix/tests/keybindings.nix b/nix/tests/keybindings.nix new file mode 100644 index 00000000..3cc2fbfe --- /dev/null +++ b/nix/tests/keybindings.nix @@ -0,0 +1,38 @@ +# `keybindings-fixtures`: every key binding file of the fixture corpus +# (komorebi-hotkeys/tests/fixtures) through `komorebic hotkeys compile --mode auto --dry-run`, +# the command the NixOS module runs, compared with `keybindings.expected`: the static shortcuts of +# each file, the bindings left to the engine, and the diagnostics, as the build log of the module +# shows them. After a change that means to change them, write the file again with the loop below, +# run in the fixtures directory, and read the difference. The sample files of the user guide, +# docs/*.sample, are the corpus's case `sample`, which this checks too. +{ + pkgs, + # a package with bin/komorebic + komorebic, +}: +let + inherit (pkgs) lib; +in +pkgs.runCommand "keybindings-fixtures" + { + fixtures = ../../komorebi-hotkeys/tests/fixtures; + expected = ./keybindings.expected; + samples = lib.fileset.toSource { + root = ../../docs; + fileset = lib.fileset.fileFilter (file: file.hasExt "sample") ../../docs; + }; + } + '' + for format in skhdrc whkdrc sxhkdrc; do + diff -u $fixtures/sample.$format $samples/$format.sample + done + cd $fixtures + for file in $(ls | sort); do + echo "== $file" + ${komorebic}/bin/komorebic hotkeys compile --mode auto --dry-run "$file" --output shortcuts 2>&1 + echo + done > $TMPDIR/got + diff -u $expected $TMPDIR/got + echo "$(ls $fixtures | wc -l) files plan as expected" + touch $out + '' diff --git a/nix/tests/nixos-module.nix b/nix/tests/nixos-module.nix index d85c7d43..2316f728 100644 --- a/nix/tests/nixos-module.nix +++ b/nix/tests/nixos-module.nix @@ -321,6 +321,82 @@ let }; }; + keybindings = + settings: + eval { + imports = [ plasma ]; + services.komorebi = { + enable = true; + keybindings = settings; + }; + }; + + withText = keybindings { + format = "skhd"; + text = "alt - h : komorebic focus left\n"; + mode = "auto"; + chordTimeout = 1500; + appAliases.terminal = [ + "foot" + "konsole" + ]; + }; + + withFile = keybindings { + format = "sxhkd"; + file = ../../komorebi-hotkeys/tests/fixtures/plain.sxhkdrc; + }; + + textAndFile = keybindings { + format = "skhd"; + text = "alt - h : komorebic focus left\n"; + file = ../../komorebi-hotkeys/tests/fixtures/plain.skhdrc; + }; + + # the typed `config` and the key bindings are two parts of one command line + withConfigAndKeybindings = eval { + imports = [ plasma ]; + services.komorebi = { + enable = true; + config.default_workspace_padding = 20; + keybindings = { + format = "skhd"; + text = "alt - h : komorebic focus left\n"; + }; + }; + }; + + withoutFormat = keybindings { text = "alt - h : komorebic focus left\n"; }; + + withLoad = keybindings { + format = "skhd"; + text = ".load \"/home/me/.config/skhd/more\"\nalt - h : komorebic focus left\n"; + }; + + # a file with a line komorebic cannot read, which the build only reports unless `strict` is set. + # Evaluation does not read the bindings the way komorebic does (it looks for skhd's .load and no + # more), so what `strict` changes is the build of the compiled key bindings: its script is what + # these checks read, and the build that fails is not run here. + unreadableLine = "alt - h : komorebic focus left\nalt - nosuchkey : komorebic focus up\n"; + + withStrict = keybindings { + format = "skhd"; + text = unreadableLine; + strict = true; + }; + + withoutStrict = keybindings { + format = "skhd"; + text = unreadableLine; + }; + + # the package that compiles the key bindings, and the script that builds it + compiled = + config: lib.findFirst (p: p.name == "komorebi-keybindings") null config.environment.systemPackages; + compileScript = config: (compiled config).buildCommand; + + installed = config: map (p: p.name) config.environment.systemPackages; + failed = config: map (a: a.message) (lib.filter (a: !a.assertion) config.assertions); unit = config: config.systemd.user.services.komorebi; evaluates = value: (builtins.tryEval value).success; @@ -578,6 +654,102 @@ let name = "execStart cannot be set"; ok = !(evaluates execStartSet.services.komorebi.execStart); } + { + name = "without key bindings, nothing is compiled"; + ok = !(lib.elem "komorebi-keybindings" (installed enabled)); + got = installed enabled; + } + { + name = "key bindings as text: every assertion holds"; + ok = failed withText == [ ]; + got = failed withText; + } + { + name = "key bindings as text reach execStart, with the mode, the chord timeout and the aliases"; + # a regular expression cannot refer to a store path, so both lose their context + ok = + builtins.match ( + lib.escapeRegex ( + builtins.unsafeDiscardStringContext "${withText.services.komorebi.package}/bin/komorebi" + ) + + " --log-level info" + + " --keybindings /nix/store/[a-z0-9]+-komorebi-skhdrc --keybindings-format skhd" + + " --keybindings-mode auto --chord-timeout 1500 --app-alias 'terminal=foot,konsole'" + ) (builtins.unsafeDiscardStringContext withText.services.komorebi.execStart) != null; + got = withText.services.komorebi.execStart; + } + { + name = "the compiled key bindings are installed in the system profile"; + ok = lib.elem "komorebi-keybindings" (installed withText); + got = installed withText; + } + { + name = "key bindings from a file reach execStart, in the default mode, engine"; + ok = lib.hasInfix "-plain.sxhkdrc --keybindings-format sxhkd --keybindings-mode engine --chord-timeout 3000" withFile.services.komorebi.execStart; + got = withFile.services.komorebi.execStart; + } + { + name = "a typed config and key bindings reach execStart together: the checked file, then the keys"; + ok = + failed withConfigAndKeybindings == [ ] + && + builtins.match ( + ".* --log-level info --config /nix/store/[a-z0-9]+-validated-komorebi.json" + + " --keybindings /nix/store/[a-z0-9]+-komorebi-skhdrc --keybindings-format skhd" + + " --keybindings-mode engine --chord-timeout 3000" + ) (builtins.unsafeDiscardStringContext withConfigAndKeybindings.services.komorebi.execStart) != null + && withConfigAndKeybindings.services.komorebi.internal.configAttrs.default_workspace_padding == 20; + got = withConfigAndKeybindings.services.komorebi.execStart; + } + { + name = "text and file together: an assertion fails"; + ok = lib.any (lib.hasInfix "exactly one of text and file") (failed textAndFile); + got = failed textAndFile; + } + { + name = "key bindings without a format: an assertion fails"; + ok = lib.any (lib.hasInfix "needs a format") (failed withoutFormat); + got = failed withoutFormat; + } + { + name = "skhd's .load: an assertion fails"; + ok = lib.any (lib.hasInfix ".load is not supported") (failed withLoad); + got = failed withLoad; + } + { + name = "with strict, the build of the key bindings runs komorebic hotkeys compile --strict, and fails when it does"; + ok = + failed withStrict == [ ] + && lib.hasInfix "hotkeys compile" (compileScript withStrict) + && lib.hasInfix "--strict" (compileScript withStrict) + && lib.hasInfix "exit 1" (compileScript withStrict); + got = compileScript withStrict; + } + { + name = "without strict, a line komorebic cannot read is a warning in the build log: no --strict"; + ok = + failed withoutStrict == [ ] + && lib.hasInfix "hotkeys compile" (compileScript withoutStrict) + && !(lib.hasInfix "--strict" (compileScript withoutStrict)) + && lib.hasInfix "cat $out/diagnostics.txt >&2" (compileScript withoutStrict); + got = compileScript withoutStrict; + } + { + name = "strict is for the build: the daemon is started with the same command line either way"; + ok = withStrict.services.komorebi.execStart == withoutStrict.services.komorebi.execStart; + got = withStrict.services.komorebi.execStart; + } + { + name = "a layout other than us does not evaluate"; + ok = + !(evaluates + (keybindings { + format = "skhd"; + text = ""; + layout = "de"; + }).services.komorebi.keybindings.layout + ); + } ]; failures = lib.filter (check: !check.ok) checks; diff --git a/nix/tests/vm/keys-corpus.py b/nix/tests/vm/keys-corpus.py new file mode 100644 index 00000000..af216a76 --- /dev/null +++ b/nix/tests/vm/keys-corpus.py @@ -0,0 +1,40 @@ +# vm-keys-skhd, vm-keys-whkd and vm-keys-sxhkd: the case `vm` of the key binding corpus +# (komorebi-hotkeys/tests/fixtures/vm.*), in the format of the suite, installed by the NixOS module +# (`services.komorebi.keybindings`, mode auto). Alt+J can be a static shortcut, which KWin runs +# from the system profile; Alt+, cannot, so the module's daemon registers it and runs it. The Rust +# tests and `keybindings-fixtures` check the plan; only a real session can say that what the +# module builds and starts runs on a key, from each of the three formats. +from komorebi_vm import Checks, Kde, Keys + +start_all() +machine.wait_for_unit("multi-user.target") + +checks = Checks() +kde = Kde.session(machine, scale=SCALE) +keys = Keys(machine) + + +def ran(marker: str) -> bool: + return machine.execute(f"test -e /tmp/{marker}")[0] == 0 + + +def press(combo: str, marker: str) -> bool: + keys.send(combo) + return kde.wait_for(lambda: ran(marker), timeout=10) + + +shortcuts = machine.succeed("ls /run/current-system/sw/share/kglobalaccel") +checks.check( + "the module installed the static shortcut in the system profile", + "komorebi-touch-tmp-keys-corpus-alt-j.desktop" in shortcuts.split(), +) +checks.check( + "the module's daemon registered the key of the engine, and only that one", + kde.wait_for(lambda: kde.shortcut_actions() == ["Alt+,"], timeout=60), +) +checks.check("Alt+J runs its command, as a static shortcut", press("alt-j", "keys-corpus-alt-j")) +checks.check( + "Alt+, runs its command, through the engine", press("alt-comma", "keys-corpus-alt-comma") +) + +checks.finish() diff --git a/nix/tests/vm/suites/keys-skhd/default.nix b/nix/tests/vm/suites/keys-skhd/default.nix new file mode 100644 index 00000000..a445123d --- /dev/null +++ b/nix/tests/vm/suites/keys-skhd/default.nix @@ -0,0 +1,12 @@ +{ + tier = "slow"; + kind = "session"; + timeoutMinutes = 10; + # the same test for the three formats + script = "../../keys-corpus.py"; + node.services.komorebi.keybindings = { + format = "skhd"; + file = ../../../../../komorebi-hotkeys/tests/fixtures/vm.skhdrc; + mode = "auto"; + }; +} diff --git a/nix/tests/vm/suites/keys-sxhkd/default.nix b/nix/tests/vm/suites/keys-sxhkd/default.nix new file mode 100644 index 00000000..7aa495f6 --- /dev/null +++ b/nix/tests/vm/suites/keys-sxhkd/default.nix @@ -0,0 +1,12 @@ +{ + tier = "slow"; + kind = "session"; + timeoutMinutes = 10; + # the same test for the three formats + script = "../../keys-corpus.py"; + node.services.komorebi.keybindings = { + format = "sxhkd"; + file = ../../../../../komorebi-hotkeys/tests/fixtures/vm.sxhkdrc; + mode = "auto"; + }; +} diff --git a/nix/tests/vm/suites/keys-whkd/default.nix b/nix/tests/vm/suites/keys-whkd/default.nix new file mode 100644 index 00000000..a6cfdf89 --- /dev/null +++ b/nix/tests/vm/suites/keys-whkd/default.nix @@ -0,0 +1,12 @@ +{ + tier = "slow"; + kind = "session"; + timeoutMinutes = 10; + # the same test for the three formats + script = "../../keys-corpus.py"; + node.services.komorebi.keybindings = { + format = "whkd"; + file = ../../../../../komorebi-hotkeys/tests/fixtures/vm.whkdrc; + mode = "auto"; + }; +}