mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-20 15:41:38 +01:00
feat(cli): komorebic
The daemon answers on its socket, but a person has no way to write a message on it. komorebic is that way: each subcommand that asks something of the daemon is one message, sent with komorebi-client, and a question's answer is printed. komorebic is a separate program because the daemon takes no input but its socket, so a key binding, a script and a terminal all drive it the same way. It has what the daemon can answer so far: state, monitor-information, query, retile and stop. Around them, start runs the komorebi on the PATH in the background and passes it what follows a --, such as --fake-backend to try it without a compositor; log follows the daemon's log, which the daemon now writes to a file a day in LOG_DIR as well as to stdout; data-directory shows where the socket is; completions prints a shell completion script. The hidden docgen writes each subcommand's help to docs/cli, in fences that name their language and wrapped at 100 columns whatever the width of the terminal, so that the pages are the same wherever they are generated; just docgen runs it. The user guide starts here: docs/index.md for KDE Plasma, and a page on running komorebi. tests/cli.rs runs each subcommand against a socket the test serves in place of the daemon. In the VM tests the guests get komorebic next to the daemon, and vm-core-e2e reads the daemon's state with it (the windows it manages, the one it focuses, after KWin restarts too) and stops it with komorebic stop, which unloads the bridge and removes the socket. In the VM test library, Kde.state asks again, a second (times the scale) after an empty answer or a failed command, up to 10 times. The daemon drops a query when it cannot take hold of the window manager within a second, and komorebic then prints an empty line and succeeds; komorebic itself gives the daemon a second to answer and fails when that is not enough. A daemon busy with the first windows does either on a machine that is loaded or slow, and a suite that polled the state died on JSONDecodeError. An answer that is not JSON still fails at once.
This commit is contained in:
1 parent
88aa78b874
commit
6f657e53e3
36 files changed
+1320
-39
No files matched your search
@@ -223,6 +223,10 @@ status 0. `SIGINT` and `SIGTERM` do the same from `main.rs`, with the exit statu
|
||||
- [`state`](../../komorebi/src/state.rs): the [`State`] a `State` message is answered with.
|
||||
- [`komorebi-client`](../../komorebi-client/src/lib.rs): a library that writes messages on
|
||||
the socket and reads the answers, for programs that talk to the daemon.
|
||||
- [`komorebic`](../../komorebic/src/main.rs): the command line. A subcommand that asks
|
||||
something of the daemon is one message, sent with `komorebi-client`; `start` runs the
|
||||
daemon, `log` follows its log file in [`LOG_DIR`], and the hidden `docgen` writes
|
||||
`docs/cli`.
|
||||
- [`main.rs`](../../komorebi/src/main.rs): the daemon. It connects to KWin, or installs the
|
||||
fake with `--fake-backend`, makes the window manager, which binds the socket, loads and
|
||||
tiles the desktop, starts the threads that listen on the socket and handle events, and
|
||||
@@ -325,10 +329,10 @@ A window is shown, and ends up on a tile:
|
||||
|
||||
## One message, end to end
|
||||
|
||||
A client asks for the state of the window manager:
|
||||
`komorebic state` asks for the state of the window manager:
|
||||
|
||||
1. [`send_query`] connects to `komorebi.sock` in [`DATA_DIR`], writes
|
||||
`{"type":"State"}`, and shuts down its side of the connection for writing.
|
||||
1. `komorebic` calls [`send_query`], which connects to `komorebi.sock` in [`DATA_DIR`],
|
||||
writes `{"type":"State"}`, and shuts down its side of the connection for writing.
|
||||
2. The thread that [`listen_for_commands`] started accepts the connection and starts a
|
||||
thread for it, which calls [`read_commands_uds`].
|
||||
3. `read_commands_uds` reads the line, parses it into [`SocketMessage`]`::State`, and locks
|
||||
@@ -339,7 +343,7 @@ A client asks for the state of the window manager:
|
||||
5. The state is written to the connection as pretty-printed JSON, and the index of managed
|
||||
windows is rebuilt, as after every message.
|
||||
6. There are no more lines, so `read_commands_uds` returns and the connection is closed.
|
||||
`send_query` has read to the end, and returns the JSON.
|
||||
`send_query` has read to the end, and returns the JSON, which `komorebic` prints.
|
||||
|
||||
## Where to look in the code
|
||||
|
||||
@@ -358,6 +362,8 @@ A client asks for the state of the window manager:
|
||||
each message does, and the tests that send messages through a real socket.
|
||||
- [`komorebi-client/src/lib.rs`](../../komorebi-client/src/lib.rs): the client side of the
|
||||
socket.
|
||||
- [`komorebic/src/main.rs`](../../komorebic/src/main.rs): the subcommands, and
|
||||
[`komorebic/tests/cli.rs`](../../komorebic/tests/cli.rs), what each writes on the socket.
|
||||
- [`komorebi/src/kwin/mod.rs`](../../komorebi/src/kwin/mod.rs): the KWin backend, its D-Bus
|
||||
service and the held call.
|
||||
- [`komorebi/src/kwin/state.rs`](../../komorebi/src/kwin/state.rs): the table, with the
|
||||
@@ -369,7 +375,7 @@ A client asks for the state of the window manager:
|
||||
- [`nix/tests/vm/suites/kwin-events`](../../nix/tests/vm/suites/kwin-events/test.py): the
|
||||
events of a real KWin, through the daemon.
|
||||
- [`nix/tests/vm/suites/core-e2e`](../../nix/tests/vm/suites/core-e2e/test.py): the daemon
|
||||
tiling a real KWin, checked against what KWin has.
|
||||
tiling a real KWin, checked against what KWin has, and read and stopped with `komorebic`.
|
||||
- [`nix/tests/vm/suites/kwin-restart`](../../nix/tests/vm/suites/kwin-restart/test.py): KWin
|
||||
restarting under the daemon.
|
||||
- [`komorebi/tests/wm_events.rs`](../../komorebi/tests/wm_events.rs): the window manager
|
||||
@@ -411,6 +417,7 @@ A client asks for the state of the window manager:
|
||||
[`bridge.test.js`]: ../../komorebi/src/kwin/bridge.test.js
|
||||
[`fixtures`]: ../../komorebi/src/kwin/fixtures
|
||||
[`DATA_DIR`]: ../../komorebi/src/lib.rs
|
||||
[`LOG_DIR`]: ../../komorebi/src/lib.rs
|
||||
[`SocketMessage`]: ../../komorebi/src/core/mod.rs
|
||||
[`StateQuery`]: ../../komorebi/src/core/mod.rs
|
||||
[`State`]: ../../komorebi/src/state.rs
|
||||
|
||||
@@ -164,3 +164,10 @@ an action is the job of another program, which runs a command that writes a mess
|
||||
socket. This is the architecture that bspwm made popular on Linux and yabai on macOS, and
|
||||
the one komorebi has on Windows and on macOS
|
||||
([the design notes of komorebi for Mac](https://github.com/LGUG2Z/komorebi-for-mac/blob/master/docs/design.md)).
|
||||
|
||||
## Why is `komorebic` a separate program?
|
||||
|
||||
Because the daemon takes no input but its socket. `komorebic` turns a command line into one
|
||||
message on the socket and, for a question, prints the answer. A key binding, a script and a
|
||||
person at a terminal all drive komorebi the same way, by running `komorebic` (the design
|
||||
notes of komorebi for Mac, linked above).
|
||||
+11
-6
@@ -144,9 +144,11 @@ What komorebi calls:
|
||||
|---|---|---|
|
||||
| `$XDG_RUNTIME_DIR/komorebi/bridge.js` | the script KWin loads, with its configuration (the D-Bus names and the hold time of `Poll`) on its first line | written at every start; the directory is removed at logout |
|
||||
| `$XDG_RUNTIME_DIR/komorebi/komorebi.sock` | the command socket | bound once the daemon is connected to KWin, after a file left there is removed; removed when the daemon stops |
|
||||
| `$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 |
|
||||
|
||||
Without `XDG_RUNTIME_DIR` the directory is `komorebi` in the local data directory instead
|
||||
(see [`XDG_DATA_HOME`](#xdg_data_home)).
|
||||
Without `XDG_RUNTIME_DIR` the bridge and the socket are in `komorebi` in the local data
|
||||
directory instead, with the logs (see [`XDG_DATA_HOME`](#xdg_data_home)).
|
||||
|
||||
## Environment variables
|
||||
|
||||
@@ -163,8 +165,10 @@ the `komorebi` directory in it, and binds its command socket there.
|
||||
|
||||
### `XDG_DATA_HOME`
|
||||
|
||||
Read only when `XDG_RUNTIME_DIR` is not set: the bridge and the socket then go to
|
||||
`$XDG_DATA_HOME/komorebi` (`~/.local/share/komorebi` if `XDG_DATA_HOME` is not set either).
|
||||
The logs are written to `$XDG_DATA_HOME/komorebi` (`~/.local/share/komorebi` if
|
||||
`XDG_DATA_HOME` is not set), which the daemon makes before anything else: a home it cannot
|
||||
write to stops it at once. When `XDG_RUNTIME_DIR` is not set, the bridge and the socket go
|
||||
there too.
|
||||
|
||||
### `RUST_LOG`
|
||||
|
||||
@@ -178,8 +182,9 @@ Whether an error carries a backtrace. komorebi sets it to `1` when it is not set
|
||||
|
||||
### `NO_COLOR`
|
||||
|
||||
When set to anything but the empty string, the log has no ANSI colors, which is what a log
|
||||
written to a file wants. The VM tests set it.
|
||||
When set to anything but the empty string, the log the daemon prints on its standard output
|
||||
has no ANSI colors, which is what standard output redirected to a file wants. The VM tests
|
||||
set it. The log files are not affected: one has colors and the other none.
|
||||
|
||||
## The bridge's environment
|
||||
|
||||
|
||||
@@ -54,8 +54,8 @@ own Wayland socket), so a test can run several sessions side by side and none
|
||||
touches another. A virtual KWin has no real output, so it cannot draw: it can
|
||||
place windows and answer questions about them, but it cannot take a screenshot.
|
||||
A third unit, `komorebi@NAME`, runs the daemon in a session, built from the
|
||||
commit under test and installed on the node; it is not bound to KWin's unit, so
|
||||
a test can restart KWin under a running daemon.
|
||||
commit under test and installed on the node with `komorebic`; it is not bound to
|
||||
KWin's unit, so a test can restart KWin under a running daemon.
|
||||
|
||||
KWin wants a DRM render node, which needs a GPU. The test driver gives every aarch64 guest one
|
||||
`virtio-gpu-pci`; on x86_64 the node adds it, unless `komorebi.vm.renderNode` is false.
|
||||
@@ -105,6 +105,11 @@ the run.
|
||||
started, and `script_loaded()` asks KWin whether it runs the bridge.
|
||||
`restart_kwin()` stops the session's KWin and starts a new one on the same
|
||||
bus, as when the compositor of a running session crashes, and waits for it.
|
||||
- `komorebic(*args)` runs `komorebic` in the session and returns what it
|
||||
printed, failing the test if it fails. `state()` is the daemon's state as
|
||||
`komorebic state` prints it, `managed(workspace)` the number of windows the
|
||||
daemon has on a workspace of the first monitor, and `focused_title(workspace)`
|
||||
the title of the window it has focused there.
|
||||
- `daemon` reads the daemon's view of the desktop from that log, started with
|
||||
`--log-level debug`: `daemon.events(log)` lists the window events it handled,
|
||||
in order, `daemon.window_ids(log)` maps a window's title to the daemon's id
|
||||
|
||||
Reference in new issue
Block a user