mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-20 23:51:40 +01:00
On NixOS, running komorebi should take one flake input and one module line. The flake exports `services.komorebi` as nixosModules.default (and .komorebi). It adds the flake's overlay, which gains komorebi-full, installs komorebi and komorebic, and runs the daemon in every Plasma session as a systemd user unit, wanted by plasma-workspace.target and ordered after plasma-core.target, which Plasma orders after KWin. systemd starts a daemon that fails again; the exit status of a SIGTERM (130) counts as success, so a stopped unit is not failed. The unit's PATH is the one a terminal in the session has, instead of the few store paths NixOS gives a unit. The options are enable, package, logLevel and a read-only execStart, the command line the unit runs. There is no configFile: the daemon reads no configuration file yet, and an option that linked one would do nothing. nixos-module-eval evaluates seven scenarios as real NixOS systems and checks their assertions, the unit and execStart, with builtins.tryEval for the two that must not evaluate. Nothing in it builds a Linux package, so it runs on a Mac as well. The VM nodes import the module, so every suite runs komorebi as the module installs it. The headless node's komorebi@NAME runs execStart, which has --log-level, so the nodes set logLevel to debug and the suites stop passing it; latency, which times the daemon, keeps the default level. The session node starts the module's unit at login; render-smoke turns it off, since a tiled terminal would cover the desktop it looks at. A new fast suite, vm-module, logs in to Plasma and checks that the unit runs the daemon with the module's log level and PATH, that a window opened in the session is tiled, that a killed daemon is started again, and that a stop is not a failure. docs/installation.md covers NixOS first, and building from source on other distributions. There is no binary cache: the Komorebi license does not allow third parties to redistribute binaries.
108 lines
4.6 KiB
Markdown
108 lines
4.6 KiB
Markdown
# Running komorebi
|
|
|
|
`komorebi` is the daemon that tiles your windows, and `komorebic` is the command line you
|
|
control it with. This page covers starting and stopping the daemon, asking it what it is
|
|
doing, and reading its log.
|
|
|
|
## Getting the two programs
|
|
|
|
[Installing komorebi](../installation.md) covers NixOS, where the flake's module installs both
|
|
and starts the daemon with every Plasma session, and building them from source. In a checkout of
|
|
the repository, on Linux, `nix build` leaves them in `result/bin`, and `nix profile install .`
|
|
puts them on your `PATH`. Without nix, build them with the Rust toolchain that
|
|
`rust-toolchain.toml` selects:
|
|
|
|
```sh
|
|
cargo build --release --locked
|
|
export PATH="$PWD/target/release:$PATH"
|
|
```
|
|
|
|
With the NixOS module, the daemon is the user unit `komorebi.service`, which starts when you log
|
|
in to Plasma. `systemctl --user start komorebi` starts it again after a `komorebic stop`, and
|
|
`journalctl --user -u komorebi` shows what it wrote. Everything else on this page applies to it
|
|
as it is.
|
|
|
|
## Starting and stopping
|
|
|
|
[`komorebic start`](../cli/start.md) runs the `komorebi` on your `PATH` in the background,
|
|
and checks three seconds later that it is running. It tries three times. If `komorebi` has
|
|
not started by then, `komorebic start` runs it once more in the foreground and prints what
|
|
it wrote on its standard error, which explains why it did not start. When a `komorebi` is
|
|
running already, `komorebic start` does nothing.
|
|
|
|
`komorebi` manages the windows of the Plasma Wayland session it is started in: it connects
|
|
to KWin on the session bus and loads a script into it, so start it from a terminal in that
|
|
session. Outside a Plasma session it exits with an error that says what is missing, which
|
|
`komorebic start` prints.
|
|
|
|
Everything after a `--` is passed to `komorebi`. `--fake-backend` runs it against an
|
|
in-memory desktop with one monitor and no windows instead of KWin, which is a way to try the
|
|
daemon and `komorebic` without a compositor:
|
|
|
|
```sh
|
|
komorebic start
|
|
komorebic start -- --log-level debug
|
|
komorebic start -- --fake-backend
|
|
```
|
|
|
|
[`komorebic stop`](../cli/stop.md) tells the daemon to stop. It asks KWin to unload its
|
|
script, removes its socket and exits. Stopping the process with `SIGINT` or `SIGTERM` does
|
|
the same.
|
|
|
|
## Asking komorebi what it is doing
|
|
|
|
The daemon answers questions on its socket, and these commands print the answers:
|
|
|
|
- [`komorebic state`](../cli/state.md): every monitor, with its workspaces, their
|
|
containers and the windows in them, as JSON.
|
|
- [`komorebic monitor-information`](../cli/monitor-information.md): the id, the name and
|
|
the bounds of every monitor, as JSON.
|
|
- [`komorebic query`](../cli/query.md): one value, the answer to one question: the index of
|
|
the focused monitor, workspace, container or window, the layout of the focused workspace,
|
|
whether the focused container is a single window or a stack, or the version of the
|
|
daemon.
|
|
|
|
```sh
|
|
komorebic query focused-workspace-index
|
|
komorebic state | jq '.monitors.elements[0].workspaces.elements[0].containers.elements | length'
|
|
```
|
|
|
|
[`komorebic retile`](../cli/retile.md) tiles the windows of every monitor again, which puts
|
|
a window that was moved by hand back on its tile.
|
|
|
|
When the daemon is not running, these commands fail: there is no socket to write to.
|
|
|
|
A program that wants to know what komorebi does without asking can subscribe to its
|
|
notifications instead ([Subscribing to notifications](subscribing-to-notifications.md)).
|
|
|
|
## The socket and the data directory
|
|
|
|
The daemon listens on `komorebi.sock` in its data directory, `$XDG_RUNTIME_DIR/komorebi`
|
|
(the local data directory, `~/.local/share/komorebi`, when there is no runtime directory).
|
|
[`komorebic data-directory`](../cli/data-directory.md) prints the directory, if it exists.
|
|
|
|
## The log
|
|
|
|
The daemon logs to its standard output and to a file a day in `~/.local/share/komorebi`
|
|
(`$XDG_DATA_HOME/komorebi` when that is set): `komorebi.log.YYYY-MM-DD`, with colors, and
|
|
`komorebi_plaintext.log.YYYY-MM-DD`, without. The day is the UTC date.
|
|
|
|
[`komorebic log`](../cli/log.md) follows the file of the current day, with colors, until
|
|
you press Ctrl-C. The `--log-level` of `komorebi` sets how much is logged: `error`, `warn`,
|
|
`info` (the default), `debug` or `trace`.
|
|
|
|
## Shell completions
|
|
|
|
[`komorebic completions`](../cli/completions.md) prints a completion script for bash,
|
|
elvish, fish, PowerShell or zsh:
|
|
|
|
```sh
|
|
komorebic completions fish > ~/.config/fish/completions/komorebic.fish
|
|
komorebic completions bash > ~/.local/share/bash-completion/completions/komorebic
|
|
```
|
|
|
|
## Every command
|
|
|
|
[`docs/cli`](../cli/start.md) has a page for every `komorebic` command, generated from its
|
|
help with `just docgen`.
|