mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-19 15:18:40 +01:00
refactor(repo): move the platform READMEs, contributing guides and old CI files under docs/ (pure move)
komorebi-for-kde/README.md, CONTRIBUTING.md -> docs/linux/ komorebi-for-mac/README.md, CONTRIBUTING.md -> docs/macos/ komorebi-for-kde/.github/* -> docs/dev/old-ci/linux/ komorebi-for-mac/.github/*, mkdocs.yml, check_schema_docs.py, dependencies.json, formula.template.rb -> docs/dev/old-ci/macos/ The CI workflows, dependabot files, issue templates, the macOS Homebrew formula template and docs-site configuration of the two old repositories are kept for the CI and release plan that follows (one workflow set, one release); under docs/ GitHub ignores them, as it did under the subdirectories, so no KDE or macOS workflow runs on this branch. Renames only (19 files); the Windows .github and files at the root are untouched.
This commit is contained in:
1 parent
73c43239b5
commit
4653986f0e
19 files changed
No files matched your search
@@ -0,0 +1,240 @@
|
||||
# Contributing to the Project
|
||||
|
||||
The project is a collection of contributions from both the project leaders and
|
||||
community members. There are many ways to contribute, this can include content
|
||||
in the project repositories, as well as contributing in public and private
|
||||
conversation, assisting users, writing blog posts, and many other ways.
|
||||
|
||||
## How contributions are made
|
||||
|
||||
Contributions to the project primarily happen in the project source
|
||||
repositories, but may also occur in other places, such as discussion forums and
|
||||
public and private discourse.
|
||||
|
||||
## Contributing content to the Project
|
||||
|
||||
In order for the project leaders to manage sustained progress toward the
|
||||
project goals and maintain project velocity, focus and quality, the project may
|
||||
adjust the license terms over time.
|
||||
|
||||
Content contributed to the project must therefore be provided under
|
||||
sufficiently liberal terms to allow these operations to proceed unimpeded. As
|
||||
such contributions are accepted with the following understanding:
|
||||
|
||||
* Contributed content is licensed under the terms of the 0-BSD license
|
||||
* Contributors accept the terms of the project license at the time of
|
||||
contribution
|
||||
|
||||
By making a contribution, you accept both the current project license terms,
|
||||
and that all contributions that you have made are provided under the terms of
|
||||
the 0-BSD license.
|
||||
|
||||
## Working on the code
|
||||
|
||||
`nix develop` (or [direnv](https://direnv.net), through the [`.envrc`](.envrc))
|
||||
provides the Rust toolchain, a nightly `rustfmt` and the tools the checks use.
|
||||
[`rustfmt.toml`](rustfmt.toml) uses an unstable option, which is why the
|
||||
formatter is a nightly one.
|
||||
|
||||
`just check` runs everything a change has to pass before it is pushed: the
|
||||
formatting check, clippy with warnings denied, the tests, rustdoc with warnings
|
||||
denied, the checks of the bridge, and `just lint`: the macros the code does not
|
||||
use, and actionlint (with shellcheck) over the workflows. `just fmt` formats the Rust sources, and `nix fmt` every file
|
||||
type the repository has. `nix flake check` builds the same checks, plus
|
||||
`cargo deny`, as derivations; on Linux it also boots every VM test, which needs
|
||||
KVM.
|
||||
|
||||
## The bridge
|
||||
|
||||
[`bridge.js`](komorebi/src/kwin/bridge.js), the script komorebi loads into
|
||||
KWin, is JavaScript that KWin runs as it is: there is no package.json and no
|
||||
build step. Its types are JSDoc comments, which `tsc` checks against
|
||||
[`kwin-api.d.ts`](komorebi/src/kwin/kwin-api.d.ts), the part of KWin's
|
||||
scripting API the bridge uses; something the bridge starts to use is declared
|
||||
there first. Its tests, [`bridge.test.js`](komorebi/src/kwin/bridge.test.js),
|
||||
run under `node --test` against a fake KWin. `just check-js` runs both, with the
|
||||
`tsc` and `node` of the dev shell.
|
||||
|
||||
The messages between the bridge and the daemon are in
|
||||
[`komorebi/src/kwin/fixtures`](komorebi/src/kwin/fixtures), which the tests of
|
||||
both sides read. A change to a message changes the fixture, the bridge and the
|
||||
daemon in the same commit.
|
||||
|
||||
## The NixOS module
|
||||
|
||||
[`nix/nixos-module.nix`](nix/nixos-module.nix) is `services.komorebi`, which the
|
||||
flake exports as `nixosModules.default` with its overlay. A change to it comes
|
||||
with a scenario in [`nix/tests/nixos-module.nix`](nix/tests/nixos-module.nix),
|
||||
the `nixos-module-eval` check: each scenario is a real NixOS system that is
|
||||
evaluated and never built, and its checks read the assertions, the unit and
|
||||
the options it evaluates to. It runs on a Mac too, with `nix build
|
||||
.#checks.aarch64-darwin.nixos-module-eval`. A change to what the unit does in a
|
||||
session also changes the VM suite `module`, which logs in to Plasma on a machine
|
||||
with the module and checks the daemon the unit runs. Every other VM suite runs
|
||||
on machines built with the module too.
|
||||
|
||||
Three files are generated from the Rust types and committed: `schema.json` and
|
||||
`schema.asc.json` (`just jsonschema`), and `nix/komorebi-options.nix`, which types the
|
||||
module's `config` (`just nixgen`, which needs `schemars-nixgen`, `cargo install
|
||||
schemars-nixgen`). A change to what `komorebi.json` or an `applications.json` can
|
||||
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.
|
||||
|
||||
[`nix/supported-kwin.nix`](nix/supported-kwin.nix) has the oldest KWin komorebi
|
||||
supports, `min`, and the newest one every VM suite has passed against,
|
||||
`testedMax`, which the module checks a system's KWin against. `testedMax` is
|
||||
raised by hand, once every suite has passed against a newer KWin: in the weekly
|
||||
canary job, or on a branch whose `flake.lock` has it. The commit changes
|
||||
`testedMax` and the dated comment above it (the date, the nixpkgs revision and
|
||||
the KWin), and its message says which run that was and which suites ran.
|
||||
`nix eval --raw --file nix/supported-kwin.nix testedMax` reads it without the
|
||||
flake. `min` changes with the code, in the commit that starts to use something an
|
||||
older KWin does not have.
|
||||
|
||||
## The comparison
|
||||
|
||||
[`docs/dev/COMPARE.md`](docs/dev/COMPARE.md) compares komorebi for KDE with komorebi
|
||||
for Windows and komorebi for Mac, and its tables are generated by
|
||||
[`scripts/compare-gen.py`](scripts/compare-gen.py) (Python 3 and nothing else) from
|
||||
this checkout and from checkouts of the other two: the komorebi repository around it and its
|
||||
`komorebi-for-mac/` when this is `komorebi-for-kde/` of that repository, else `~/komorebi` and
|
||||
`~/komorebi-for-mac`, unless `--kfw` and `--kfm` say otherwise. Continuous
|
||||
integration has neither checkout, so it does not run the script. A change to a
|
||||
`komorebic` command, a `SocketMessage`, a key of `komorebi.json`, a
|
||||
`WindowManagerEvent`, a method of `Backend` or a list of keys in `check.rs` is
|
||||
followed by `python3 -I scripts/compare-gen.py --check docs/dev/COMPARE.md`, and
|
||||
by `--update` when it reports a stale block, in the same commit. The script stops
|
||||
and says what when a command, key, event or method has no note about why it
|
||||
differs, and when a sentence of the document stops being true; the text around an
|
||||
updated block is read again each time.
|
||||
|
||||
## VM tests
|
||||
|
||||
A change that needs a real KWin to be checked comes with a VM test, next to
|
||||
the Rust test that covers the same behavior against the fake desktop.
|
||||
[`docs/dev/vm-tests.md`](docs/dev/vm-tests.md) says how they are laid out, how
|
||||
to run one (`just vm NAME`) and how to add one.
|
||||
|
||||
## The KWin effects
|
||||
|
||||
The patches in [`nix`](nix) change the KWin effects komorebi drives. Each one
|
||||
is a derivative work of its effect, which is under the GNU General Public
|
||||
License version 3, and is under the same license. A patch starts with a header
|
||||
that describes the change and carries the license notice; `patch` skips the
|
||||
text before the first `diff` line. To change a patch, make the change in the
|
||||
effect's source at the version the package pins, and write the whole diff again
|
||||
with `diff -ruN a b` below the header. The check of each package, named after
|
||||
it (in [`nix/tests/effects.nix`](nix/tests/effects.nix)), builds the package
|
||||
and checks the files it installs, and for a patched package that the patch is
|
||||
in them:
|
||||
|
||||
```sh
|
||||
nix build .#checks.x86_64-linux.kde-rounded-corners-komorebi-install
|
||||
nix build .#checks.x86_64-linux.kwin-effect-geometry-change-komorebi-install
|
||||
```
|
||||
|
||||
## Plasma guests to develop in
|
||||
|
||||
[`nix/dev`](nix/dev) has NixOS guests with Plasma for trying a change by hand,
|
||||
on an Apple silicon Mac (two that QEMU runs and a disk image for UTM) and on a
|
||||
Linux machine with KVM (the same two QEMU guests, for `x86_64` and for
|
||||
`aarch64`, and a demo guest, [`nix/dev/run-kde.nix`](nix/dev/run-kde.nix)).
|
||||
[`docs/dev/utm.md`](docs/dev/utm.md) says how to build and run them,
|
||||
and what a builder has to be for a Mac. They install komorebi with the NixOS
|
||||
module, and carry nothing of the person who uses them: a key, a password or a
|
||||
configuration of yours goes into the guest when it runs, never into these files.
|
||||
The `plasma-guests-eval` check evaluates them, the VM suite `rdp` runs their
|
||||
RDP server, [`nix/dev/krdp.nix`](nix/dev/krdp.nix), and the VM suite `run-kde`
|
||||
boots the demo guest. The demo guest has no
|
||||
password and no key in its closure: the host shares a directory with them, and
|
||||
`run-kde` ([`scripts/run-kde`](scripts/run-kde)) starts it. The script is
|
||||
shellchecked when the package is built, and `run-kde-dry-run` and
|
||||
`run-kde-doctor` compare what it prints for made-up machines with the texts in
|
||||
[`nix/tests/run-kde`](nix/tests/run-kde): change one with the other.
|
||||
|
||||
## Continuous integration
|
||||
|
||||
[`ci.yaml`](.github/workflows/ci.yaml) runs on every pull request and on every
|
||||
push to `master`, `feature/*` and `hotfix/*`, in this repository only. The
|
||||
`lint` job builds every check that needs no virtual machine and runs
|
||||
`just lint`, `cargo-deny` checks licenses and advisories, and
|
||||
the VM tests run on KVM in two jobs: `vm-fast` on every pull request and
|
||||
`vm-slow` on `master`, every week, and on pull requests labeled `ci:vm-slow`. A weekly
|
||||
[workflow](.github/workflows/update-flake-lock.yaml) opens a pull request that
|
||||
moves `flake.lock`, and the same jobs run on it.
|
||||
|
||||
The flake follows the tip of nixpkgs-unstable, so KWin and Plasma change
|
||||
whenever `flake.lock` moves. The `canary` job of `ci.yaml` runs every week, and
|
||||
when the workflow is started by hand: it runs `nix flake update nixpkgs` in a
|
||||
copy of the checkout and builds every check against the result, the VM suites
|
||||
of both tiers included. When a check fails, it opens an issue titled "Canary: a
|
||||
check fails against the tip of nixpkgs-unstable" with the failed checks, the
|
||||
nixpkgs revision and its KWin version, or comments on that issue if it is
|
||||
still open. The job changes nothing in the repository. To reproduce a failure,
|
||||
run `nix flake update nixpkgs` in a checkout and build the check the issue
|
||||
names (`just vm NAME` for a VM suite). The fix goes in a commit of its own;
|
||||
nixpkgs is not pinned back.
|
||||
|
||||
## Releases
|
||||
|
||||
A release is a tag. Set `version` in
|
||||
[`komorebi/Cargo.toml`](komorebi/Cargo.toml) (which the flake reads) to the new version, commit it, and push the tag
|
||||
`vVERSION` on that commit. For every run, the `build` job of `ci.yaml` builds
|
||||
`komorebi` and `komorebic` with nix on an x86_64 and an arm64 runner, and keeps
|
||||
them as an artifact of the run for 14 days. On a tag, once `lint`, `vm-fast` and
|
||||
`build` have passed, the `publish` job makes the GitHub release of that tag
|
||||
with:
|
||||
|
||||
- `komorebi-VERSION-x86_64-unknown-linux-gnu.zip` and
|
||||
`komorebi-VERSION-aarch64-unknown-linux-gnu.zip`, each with the two binaries;
|
||||
- `checksums.txt`, the SHA-256 sum of every other file of the release;
|
||||
- `schema.json`, the schema of `komorebi.json`, when the repository has one;
|
||||
- release notes that [kokai](https://github.com/Joxit/kokai) writes from the
|
||||
commit messages since the previous version tag.
|
||||
|
||||
The scheduled run on `master` every week, and a run of the workflow started by
|
||||
hand on `master`, replace the `nightly` prerelease the same way: `nightly`
|
||||
takes the place of the version in the file names, and the notes list the
|
||||
commits since the last version tag. The arm64 job may fail without failing the
|
||||
run; the release then has no arm64 zip.
|
||||
|
||||
nix builds a binary that loads glibc from the nix store, so the build job
|
||||
points each binary at the system's dynamic loader, at the standard path for its
|
||||
architecture, with no library path, and runs it on the Ubuntu runner to check
|
||||
that it starts. A release binary therefore uses the glibc of the system it runs
|
||||
on.
|
||||
|
||||
## Commits
|
||||
|
||||
Commit messages follow the
|
||||
[Conventional Commits](https://www.conventionalcommits.org/) specification:
|
||||
`type(scope): description`. The scope is the Rust module the change is in
|
||||
(`wm`, `kwin`, `layouts`), `repo` for repository files and markdown, `nix` for
|
||||
the flake and `github` for workflows. Every line of a message, the header
|
||||
included, is at most 80 columns, and the body says why the change is made.
|
||||
|
||||
Documentation lands in the commit that changes the behavior it describes, not
|
||||
in a later one. A change to a `komorebic` subcommand regenerates its page in
|
||||
[`docs/cli`](docs/cli) with `just docgen`.
|
||||
|
||||
## Zero-Clause BSD
|
||||
|
||||
```text
|
||||
Permission to use, copy, modify, and/or distribute this software for
|
||||
any purpose with or without fee is hereby granted.
|
||||
|
||||
THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL
|
||||
WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
|
||||
OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE
|
||||
FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY
|
||||
DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
|
||||
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
|
||||
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
```
|
||||
@@ -0,0 +1,414 @@
|
||||
# komorebi for KDE
|
||||
|
||||
A tiling window manager for KDE Plasma on Wayland, in the family of
|
||||
[komorebi](https://github.com/LGUG2Z/komorebi) for Windows and
|
||||
[komorebi for Mac](https://github.com/LGUG2Z/komorebi-for-mac). The daemon
|
||||
decides where each window goes, and KWin, the window manager of Plasma, does the
|
||||
moving and the drawing.
|
||||
|
||||
## Installing it
|
||||
|
||||
On NixOS, the flake's module, `services.komorebi`, installs `komorebi` and
|
||||
`komorebic` and starts komorebi with every Plasma session: one flake input,
|
||||
one module line and `services.komorebi.enable = true`. Elsewhere, both are
|
||||
built from source, or taken from a release of this repository
|
||||
([Binaries](#binaries)). [`docs/installation.md`](docs/installation.md) has the
|
||||
module and the build from source. The Komorebi license does not allow anyone
|
||||
else to redistribute binaries.
|
||||
|
||||
## Running it locally
|
||||
|
||||
```sh
|
||||
nix develop
|
||||
cargo run --bin komorebi --locked -- --version
|
||||
cargo run --bin komorebi --locked -- --log-level debug
|
||||
cargo run --bin komorebi --locked -- --fake-backend
|
||||
```
|
||||
|
||||
Inside a Plasma Wayland session, `komorebi` loads a script into KWin, reads the
|
||||
monitors and the windows that are open, tiles them, and tiles the windows again
|
||||
whenever one opens, closes, takes the focus, is minimized or comes back, until
|
||||
it is stopped with Ctrl-C. It needs KWin 6.8 or newer, which the NixOS module
|
||||
checks against [`nix/supported-kwin.nix`](nix/supported-kwin.nix);
|
||||
[`docs/dev/PLATFORM.md`](docs/dev/PLATFORM.md) has what it expects of the
|
||||
session. Outside a Plasma session it exits with an error that says what is
|
||||
missing. `--fake-backend` runs the window manager against an in-memory desktop
|
||||
with one monitor and no windows instead.
|
||||
|
||||
While it runs, the daemon takes messages on a Unix socket, `komorebi.sock` in
|
||||
`$XDG_RUNTIME_DIR/komorebi` (the local data directory when there is no runtime
|
||||
directory): a message can ask for the state of the window manager, ask which
|
||||
monitor, workspace or container has the focus, give the focus to another
|
||||
window, move the focused window to another tile, change the layout, resize a
|
||||
tile, float a window, give one window the whole work area or have KWin maximize it, retile every
|
||||
monitor, or stop the daemon. [`komorebi-client`](komorebi-client) writes them, and `komorebic`,
|
||||
the command line, is how a person sends them. `komorebic start` runs the
|
||||
`komorebi` on the `PATH`, and passes it what follows a `--`. In a Plasma
|
||||
session:
|
||||
|
||||
```sh
|
||||
cargo build --locked
|
||||
export PATH="$PWD/target/debug:$PATH"
|
||||
komorebic start
|
||||
komorebic state
|
||||
komorebic stop
|
||||
```
|
||||
|
||||
`komorebic start -- --fake-backend` tries the daemon and `komorebic` without a
|
||||
compositor, against the in-memory desktop.
|
||||
|
||||
`nix develop` provides the Rust toolchain that [`rust-toolchain.toml`](rust-toolchain.toml)
|
||||
selects, a nightly `rustfmt`, and the tools `just check` and the flake's checks
|
||||
use. With [direnv](https://direnv.net), the [`.envrc`](.envrc) does it on
|
||||
`cd`. On Linux, `nix run .#komorebi -- --version` builds and runs the daemon
|
||||
without a checkout of the toolchain.
|
||||
|
||||
## Trying it in a virtual machine
|
||||
|
||||
On a Linux machine with KVM, which includes NixOS in WSL 2 on Windows 11, one command starts a
|
||||
Plasma guest in which komorebi tiles a few windows, in a window of your desktop:
|
||||
|
||||
```sh
|
||||
nix run .#run-kde
|
||||
```
|
||||
|
||||
`run-kde --doctor` checks the machine and says how to fix what is missing.
|
||||
[`docs/trying-it.md`](docs/trying-it.md) says what you need, what you see, the key bindings to try
|
||||
and what to do when it does not start.
|
||||
|
||||
## Binaries
|
||||
|
||||
The [releases](https://github.com/LGUG2Z/komorebi-for-kde/releases) of this
|
||||
repository have `komorebi` and `komorebic` for x86_64 and aarch64 Linux, one zip
|
||||
per architecture, with a `checksums.txt` of SHA-256 sums. The `nightly`
|
||||
prerelease is built from `master` every week. CI builds the binaries;
|
||||
[`CONTRIBUTING.md`](CONTRIBUTING.md#releases) says how. They use the glibc of
|
||||
the system they run on, which has to be 2.39 or newer at time of writing
|
||||
(2026-10-28). NixOS cannot run them without
|
||||
[nix-ld](https://github.com/nix-community/nix-ld); on NixOS, build komorebi
|
||||
from this flake instead.
|
||||
|
||||
The [Komorebi License](LICENSE.md) allows anyone to distribute the source code,
|
||||
but not binaries built from it. The releases of this repository are the only
|
||||
binaries, and there is no public binary cache for the flake: nix builds
|
||||
komorebi from source.
|
||||
|
||||
## Crates
|
||||
|
||||
- [`komorebi`](komorebi): the daemon, and the library behind it. The library has
|
||||
the vocabulary the window manager is written in (`core`), the `Backend` trait
|
||||
through which it reaches a compositor and the in-memory desktop the tests use
|
||||
(`backend`), the backend that reaches KWin through a script it runs and edits
|
||||
the settings of KWin's it needs in the user's `kwinrc`, the parking desktop it
|
||||
hides the back of a stack and the windows behind a monocle on, and the borders
|
||||
and animations it has KWin draw (`kwin`), the border and animation settings and
|
||||
the look they make (`border_manager`, `animation`), the colors a theme gives the
|
||||
borders (`theme_manager`), the wallpapers of monitors and workspaces, which it has
|
||||
the Plasma shell show (`kwin::wallpaper`), the opacity of the windows that do not
|
||||
have the focus (`transparency_manager`),
|
||||
the model of what it tiles (`monitor`, `workspace`, `container`, `window`), the
|
||||
window manager that keeps the model (`window_manager`), loads it from the
|
||||
backend (`desktop`) and changes it when the compositor reports an event
|
||||
(`window_manager_event`, `window_manager_event_listener`, `process_event`), the
|
||||
`Ring` that holds monitors, workspaces and containers, and the lists in which
|
||||
some elements are locked in place. It answers the messages on the daemon's
|
||||
socket (`core::SocketMessage`, `process_command`), shows its state (`state`),
|
||||
keeps the monitors in step with the compositor's outputs as they change size
|
||||
and are unplugged and plugged in, and when the machine wakes or the screen is
|
||||
unlocked (`monitor_reconciliator`, `reconcile`, `kwin::power`), sends its
|
||||
subscribers a notification of each event, message and change of the monitors
|
||||
it handles (`notify_subscribers`), and is configured by a `komorebi.json` that
|
||||
it reads and reads again when it changes (`static_config`), and checks it, the
|
||||
key binding file, and the desktop it runs on, for mistakes without the daemon
|
||||
(`check`). With a key binding file, it registers keys with KWin's global
|
||||
shortcut daemon and runs their commands (`kwin::hotkeys`).
|
||||
- [`komorebi-client`](komorebi-client): a library that sends messages to the
|
||||
daemon, reads its answers, subscribes to its notifications, and re-exports
|
||||
the types they are made of.
|
||||
- [`komorebi-hotkeys`](komorebi-hotkeys): reads the key binding files of skhd,
|
||||
whkd and sxhkd into one model, with the keys as KDE stores them, plans each
|
||||
binding as a KDE shortcut file or as a key komorebi registers itself, and has
|
||||
the engine that decides, with no I/O of its own, which keys komorebi holds
|
||||
and what each press does. It does not depend on the daemon. Its tests read the files in
|
||||
[`komorebi-hotkeys/tests/fixtures`](komorebi-hotkeys/tests/fixtures), where
|
||||
each case is written in every format that can express it.
|
||||
- [`komorebic`](komorebic): the command line. A subcommand that asks something
|
||||
of the daemon is one message on its socket, and the others work without the daemon:
|
||||
`start` and the autostart commands start it, `check` looks at the files and the
|
||||
desktop, `quickstart` writes files, `export-kde-shortcuts` and `hotkeys compile`
|
||||
write the bindings of a key binding file that KDE can run by itself as shortcut
|
||||
files, and `configuration`, `log`, `data-directory`, `completions`, the schema
|
||||
printers and the hidden `docgen` print.
|
||||
- [`version`](version): the version string every binary reports.
|
||||
|
||||
The layouts, which turn a work area and a number of containers into a rectangle
|
||||
for each, are `komorebi-layouts` from [komorebi](https://github.com/LGUG2Z/komorebi),
|
||||
a git dependency at the revision `Cargo.toml` pins.
|
||||
|
||||
## KWin effects
|
||||
|
||||
The flake also builds the KWin effects komorebi drives, which are not part of
|
||||
KWin:
|
||||
|
||||
- `kde-rounded-corners-komorebi`
|
||||
([`nix/kde-rounded-corners.nix`](nix/kde-rounded-corners.nix)): KDE Rounded
|
||||
Corners 0.11.0, which draws an outline around each window, built so that KWin
|
||||
does not load it until it is asked to, and with a patch that lets komorebi
|
||||
give each window a color of its own.
|
||||
- `kwin-effect-geometry-change-komorebi`
|
||||
([`nix/kwin-effect-geometry-change.nix`](nix/kwin-effect-geometry-change.nix)):
|
||||
Geometry Change 1.5, a scripted effect that animates a window that a program
|
||||
or a script moves or resizes, with a patch that makes its easing curve a
|
||||
setting.
|
||||
|
||||
Each one is a package for Linux and an attribute of `overlays.default`, built
|
||||
with the KWin of the nixpkgs the overlay is applied to.
|
||||
[`nix/tests/effects.nix`](nix/tests/effects.nix) checks the files each package
|
||||
installs. [`docs/dev/PLATFORM.md`](docs/dev/PLATFORM.md#kwin-effects) has what
|
||||
they need from KWin.
|
||||
|
||||
## Checks
|
||||
|
||||
`just check` runs the formatting check, clippy with warnings denied, the tests,
|
||||
rustdoc with warnings denied, and the type check and tests of the bridge (no
|
||||
package.json: `tsc` and `node` come from the dev shell), inside `nix develop`.
|
||||
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,
|
||||
`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,
|
||||
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
|
||||
it. `just vm NAME` runs one; [`docs/dev/vm-tests.md`](docs/dev/vm-tests.md) has
|
||||
the details, including how to run them on a Mac.
|
||||
|
||||
To try komorebi by hand in a real Plasma session, the flake has Plasma guests
|
||||
to develop in. For an Apple silicon Mac there are two that QEMU runs, one with a
|
||||
session that can be reached over RDP, and a disk image for UTM, which renders on
|
||||
the Mac's GPU. For a Linux machine with KVM there are the same two QEMU guests,
|
||||
for `x86_64` and for `aarch64`, and a demo guest of the session guest, which
|
||||
shows komorebi tiling a few windows in the first minute. On Linux,
|
||||
`nix run .#run-kde` (or `just run-kde`) starts the demo in a window, and
|
||||
`run-kde --doctor` says what the machine lacks.
|
||||
[`docs/dev/utm.md`](docs/dev/utm.md) says how to build and run them;
|
||||
`plasma-guests-eval` evaluates them on every system, and `run-kde-dry-run` and
|
||||
`run-kde-doctor` run the command against machines that a test makes up.
|
||||
|
||||
## How it fits together
|
||||
|
||||
The daemon decides where every window goes and asks the compositor to put it
|
||||
there. Everything it needs from the compositor is behind one trait, `Backend`,
|
||||
so the window manager logic runs against a real compositor and against an
|
||||
in-memory fake desktop alike. [`docs/dev/ARCHITECTURE.md`](docs/dev/ARCHITECTURE.md)
|
||||
describes the trait and where each of its rules is enforced.
|
||||
|
||||
On KDE Plasma the backend is in two parts. A script that komorebi loads into
|
||||
KWin, the bridge, reports what KWin sees over the session bus, and carries out
|
||||
the commands it is given as the answer to a call it holds open. The daemon keeps
|
||||
a table of the windows and monitors from those reports, answers the window
|
||||
manager's questions from it, and turns each report into an event for the window
|
||||
manager. If KWin restarts, the daemon loads the bridge into the new one.
|
||||
|
||||
komorebi's workspaces are KWin's own virtual desktops: workspace `i` is desktop
|
||||
`i`, and each monitor shows a desktop of its own, which the daemon has KWin do by
|
||||
turning on its per-output virtual desktops (the setting is put back when the
|
||||
daemon stops). Showing a workspace is a request to KWin, which shows the
|
||||
windows of that desktop, hides the others, and gives the focus to one of them.
|
||||
When something else switches a monitor to another desktop (a pager, a shortcut,
|
||||
an application raising a window of another desktop), or puts a window on
|
||||
another desktop, the window manager follows.
|
||||
|
||||
When a monitor changes size (a resolution, a scale, a panel that takes more room),
|
||||
the bridge reports the outputs again and the monitor reconciliator, a thread of
|
||||
the daemon, reads the size and the work area of every monitor and tiles the
|
||||
workspace in front of the focused monitor in the area it now has. When an output
|
||||
is unplugged, KWin takes its windows to the outputs that are left, and the
|
||||
daemon takes the monitor's containers over to the monitors the windows are on,
|
||||
tiles them there, and keeps the monitor, with its settings, for when it is
|
||||
plugged in again. A window that something else moves to another output (a
|
||||
shortcut, an application, KWin itself) is followed to the workspace of the same
|
||||
number on that monitor and tiled there.
|
||||
|
||||
While the screen is locked or the machine is asleep KWin sends its clients no
|
||||
frame callbacks, so what the daemon asked for in that time is not done. The
|
||||
daemon watches for the machine waking up (logind's `PrepareForSleep`) and for
|
||||
the lock screen going away (`org.freedesktop.ScreenSaver`), and then looks at
|
||||
the monitors and at where every window is, and puts each in its tile. The lock
|
||||
screen is a window of KWin's that the bridge does not report as an application
|
||||
window, so it has no tile.
|
||||
|
||||
The window manager models the desktop as monitors, each with a ring of
|
||||
workspaces, each with a ring of containers, each with a ring of windows. A
|
||||
workspace's layout gives each of its containers a tile of the monitor's work
|
||||
area, and every window of a container is moved onto its tile. At startup the
|
||||
window manager loads the monitors and the windows that are open from the
|
||||
backend and tiles them; after that it changes the model when the compositor
|
||||
reports that a window was shown, closed, focused, minimized or restored, and
|
||||
tiles the workspace in front again. A window the user drags with the pointer
|
||||
onto the tile of another swaps places with it, and dragging the edge of a tile
|
||||
resizes it, as `resize-edge` does, with the tiles next to the edge following it
|
||||
while it is dragged. A window open at startup goes to the workspace whose desktop
|
||||
it is on.
|
||||
|
||||
A container with more than one window is a stack: the layout gives it one tile,
|
||||
and the window in front is in sight. The others are hidden, which on KWin means
|
||||
moved to one more virtual desktop, `komorebi-park`, that nobody looks at and that
|
||||
is not a workspace. The daemon makes it when it first needs it, removes it when
|
||||
it stops, and removes one that a run that did not stop left behind. A monocle
|
||||
hides the windows of the other containers there too.
|
||||
|
||||
Everything else reaches the daemon as a message on its socket: one JSON
|
||||
`SocketMessage` per line, handled one at a time with the window manager
|
||||
locked. A message that asks a question is answered on the same connection. A
|
||||
message that gives an order changes the model the way an event does: `focus`
|
||||
and `cycle-focus` give the focus to the container on one side of the focused
|
||||
one in the layout, or to the next one in the workspace's order, and `move` and
|
||||
`cycle-move` swap the focused container with that one and tile the workspace
|
||||
again. `change-layout`, `cycle-layout` and `flip-layout` tile the workspace in
|
||||
another layout, `layout-ratios` and `scrolling-layout-columns` tune it,
|
||||
`toggle-tiling` stops it moving windows and starts it again,
|
||||
`preselect-direction` reserves a tile for the next window, `resize-edge` and
|
||||
`resize-axis` move the edges of the focused tile, `promote` brings the
|
||||
focused window to the largest tile, `toggle-float` takes it out of the
|
||||
layout, `toggle-monocle` gives its container the whole work area, hiding the
|
||||
others, and puts it back, `toggle-maximize` has KWin maximize the focused window
|
||||
and restore it (a window the user maximizes leaves the layout the same way, and
|
||||
a fullscreen window is left where it is),
|
||||
`toggle-workspace-layer` switches the focus commands between the tiles and the
|
||||
floating windows, and `toggle-lock` keeps its container at its
|
||||
place. The scrolling layout is a strip of columns that runs past the edges of
|
||||
the monitor and scrolls to the window that has the focus. `minimize` and `close`
|
||||
ask KWin to minimize or close the focused window, `unmanage` takes it out of the
|
||||
layout until `manage` takes it back, and `toggle-pause` stops the daemon acting
|
||||
on events and orders until it is resumed. The padding commands set the gaps around the tiles, and
|
||||
the work area offsets keep parts of a monitor free of tiles. Rules decide which
|
||||
windows are managed at all: `ignore-rule` keeps an application out of the
|
||||
layout, `manage-rule` tiles it whatever the ignore rules say, and
|
||||
`session-float-rule` floats the focused window and the windows like it, and a
|
||||
workspace rule (`workspace-rule`, `initial-workspace-rule`, their named forms,
|
||||
or `workspace_rules` in `komorebi.json`) sends the windows of an application to a
|
||||
workspace, once or whenever the window manager looks, which it does at every event.
|
||||
`focus-workspace` shows another workspace, and `move-to-workspace` and
|
||||
`send-to-workspace` put the focused window on another workspace, with and
|
||||
without showing it; their `cycle-` and `-last-workspace` forms go to the next,
|
||||
the previous or the last workspace, `workspace-name` names a workspace for
|
||||
`focus-named-workspace` and the other named commands, and `new-workspace` and
|
||||
`close-workspace` add and remove one.
|
||||
At the edge of a monitor, `focus` and `move` cross to the monitor on that side;
|
||||
`focus-monitor`, `move-to-monitor`, `send-to-monitor` and their kind work on the
|
||||
monitors, and `eager-focus` finds the window of an application wherever it is.
|
||||
`stack` puts the focused window and the one next to it in one stack, `unstack`
|
||||
takes it out again, and `stack-all` and `unstack-all` do it for a whole
|
||||
workspace; `cycle-stack` and `focus-stack-window` bring another window of a
|
||||
stack to the front, and `cycle-stack-index` moves the front one along it.
|
||||
`toggle-window-container-behaviour` makes a window that opens join
|
||||
the focused stack, and `toggle-float-override` makes it float.
|
||||
|
||||
The daemon is configured by `komorebi.json`: the file `--config` names, or the
|
||||
one in `~/.config/komorebi`. It reads the file when it starts, once it has the
|
||||
monitors, and gives each monitor the workspaces the file lists for it, with their
|
||||
names, layouts, paddings and rules. It watches the file, and when it changes
|
||||
applies it again to the windows it has. It also sets what a window that opens
|
||||
gets (`window_container_behaviour`, `float_override`, `floating_layer_behaviour`,
|
||||
for a workspace or for all of them) and what focusing does in monocle
|
||||
(`monocle_focus_behaviour`). Where a new window goes in the layout is the
|
||||
workspace's `initial_window_placement_rules`: after the focused container unless
|
||||
they say another place, which can depend on the window's program, app id or
|
||||
title. A key that komorebi for KDE does not read
|
||||
is ignored, so one file serves every platform. Rules for particular applications
|
||||
can be in files of their own, which `app_specific_configuration_path` names.
|
||||
`workspace-layout-rule` makes a
|
||||
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 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.
|
||||
`check` reads the file the way the daemon does and says in words what is wrong with it: JSON that
|
||||
does not parse, with the line, a value komorebi does not read, a key that is not a setting (with
|
||||
the nearest one that is), a workspace that is not tiled, and an applications file that is not
|
||||
there. It looks at the key binding file as well (how many bindings it has, the lines that cannot
|
||||
be read, and whether the shortcut files `hotkeys compile` wrote are the ones it would write now),
|
||||
and at the desktop (a Plasma session on Wayland, KWin 6 on the session bus, the daemon and its
|
||||
script in KWin, and what starts komorebi at login), unless `--configuration-only` leaves that out.
|
||||
It exits with status 1 if something is an error.
|
||||
|
||||
A program such as a status bar can subscribe to the daemon's notifications: it
|
||||
listens on a socket of its own, and after each event, each message and each
|
||||
change of the monitors, the daemon connects to it and writes it with the state
|
||||
of the window manager.
|
||||
|
||||
On NixOS, the module [`nix/nixos-module.nix`](nix/nixos-module.nix) runs the
|
||||
daemon as a systemd user unit that the Plasma session starts, and systemd
|
||||
starts it again if it fails.
|
||||
|
||||
The borders are KWin's: komorebi asks the backend for a look, a border of a
|
||||
width, a radius and two colors, and the KWin backend has the KDE Rounded Corners
|
||||
effect draw it, which the module installs. A border takes room around each
|
||||
window, so the layout leaves the room while the compositor says it draws one, and
|
||||
komorebi gives each window the border color of what it is to the layout: the focused
|
||||
window, the others, a locked container, a floating window. `border`, `border-colour`,
|
||||
`border-width` and `border-offset` set it. Windows going to their places are
|
||||
animated by another effect, Geometry Change, which `animation`,
|
||||
`animation-duration` and `animation-style` turn on and set. `transparency` makes
|
||||
the windows that do not have the focus see-through, by the opacity KWin gives a
|
||||
window, and `focus-follows-mouse` has KWin give the focus to the window under the
|
||||
pointer, by its own focus policy. A theme gives the borders their colors, and
|
||||
the palette of a picture is made and kept in the cache directory. A monitor or a workspace
|
||||
can have a wallpaper, which the Plasma shell is asked to show when the workspace comes into view,
|
||||
and which gives the borders the colors of its palette.
|
||||
|
||||
Key bindings are written in the format of skhd, whkd or sxhkd. `komorebi-hotkeys`
|
||||
reads such a file into one model and sorts its bindings into static shortcuts,
|
||||
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. 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
|
||||
|
||||
The user guide starts at [`docs/index.md`](docs/index.md),
|
||||
[`docs/trying-it.md`](docs/trying-it.md) starts a guest in which komorebi tiles a few windows,
|
||||
[`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.
|
||||
[`CONTRIBUTING.md`](CONTRIBUTING.md) says how to work on the code.
|
||||
[`docs/dev/ARCHITECTURE.md`](docs/dev/ARCHITECTURE.md) describes the model,
|
||||
[`docs/dev/DESIGN.md`](docs/dev/DESIGN.md) says why it is built that way,
|
||||
[`docs/dev/PLATFORM.md`](docs/dev/PLATFORM.md) what it needs from KDE Plasma,
|
||||
[`docs/dev/COMPARE.md`](docs/dev/COMPARE.md) what is the same and what is different in
|
||||
komorebi for Windows and komorebi for Mac,
|
||||
[`docs/dev/vm-tests.md`](docs/dev/vm-tests.md) how the VM tests work, and
|
||||
[`docs/dev/utm.md`](docs/dev/utm.md) how to develop in a Plasma guest, and
|
||||
[`docs/dev/wsl2-probe.md`](docs/dev/wsl2-probe.md) how to find out whether a
|
||||
NixOS-WSL2 machine can run one (`nix run .#wsl2-probe`).
|
||||
|
||||
## License
|
||||
|
||||
komorebi for KDE is under the [Komorebi License](LICENSE.md). Contributions
|
||||
are accepted under the terms in [`CONTRIBUTING.md`](CONTRIBUTING.md).
|
||||
|
||||
The license lets others distribute the source code but not binaries, so there
|
||||
is no public binary cache for what the flake builds: komorebi and the KWin
|
||||
effects are built on each machine that installs them, with their dependencies
|
||||
from nixpkgs. The patches to the effects in [`nix`](nix) are derivative works
|
||||
of the effects, which are under the GNU General Public License version 3, and
|
||||
are under the same license, as the header of each one states.
|
||||
Reference in new issue
Block a user