README.md RawHistoryFolder

1<h1 align="center">NeferWL</h1>
2
3<p align="center">
4  <a href="LICENSE"><img src="https://img.shields.io/badge/license-GPLv3-blue?style=flat-square" alt="License: GPLv3"></a>
5  <a href="https://github.com/bnema/neferwl"><img src="https://img.shields.io/badge/platform-Linux-blue?style=flat-square" alt="Platform: Linux"></a>
6  <a href="https://github.com/bnema/neferwl/commits/main"><img src="https://img.shields.io/github/last-commit/bnema/neferwl/main?style=flat-square&logo=github" alt="Last commit"></a>
7</p>
8
9<p align="center">A Wayland compositor that spends its frames on your apps, not on itself.</p>
10
11https://github.com/user-attachments/assets/54f25914-8335-4e66-b458-dabc5493d355
12
13
14<p align="center"><sub>Stash, overview and animations, recorded on the headless backend at 1080p.</sub></p>
15
16> [!WARNING]
17> **Early alpha, but stable enough for daily use.** Developed and tested mostly on AMD CPUs and GPUs. NVIDIA support is incomplete and untested (contribs welcome). Expect bugs and breaking config changes.
18
19## Why NeferWL
20
21- **Performance:** allocation-free hot paths, no wasted CPU passes and no cgo; about 40–80 MB of RAM with two 4K monitors. On 4K HDR video, GC takes under 9% of a process using 13% of a core; see [Architecture](docs/dev/architecture.md#keeping-the-garbage-collector-out-of-the-way) and [Performance](docs/performance.md).
22- **Games:** direct scanout, VRR, tearing, explicit sync and [HDR](docs/config.md#hdr) give games the whole GPU instead of spending it on composition; see [Performance](docs/performance.md).
23- **Overview:** `cmd+o` or a four-finger swipe up shows live workspace previews. Select a window with the keyboard, touchpad or mouse; see [Overview](docs/config.md#overview).
24- **Stash:** `cmd+s` toggles a floating strip of windows set aside for the current workspace; `cmd+shift+s` moves a window into or out of it. See [Stash](docs/config.md#stash).
25- **Hint mode:** click what is on screen by typing its label, without reaching for the mouse; targets come from the `nefer-hints` detector. Enable experimental `hint.enable` and add a bind; see [Hint mode](docs/config.md#hint-mode).
26- **Animations:** short, cheap and off by default. Opt in with experimental `animations = on`; see [Configuration](docs/config.md#keys).
27
28Written in Go, without cgo. Each piece of state has one owner goroutine, connected to the others by channels; hot paths reuse memory and client buffers stay off the Go heap. See [Architecture](docs/dev/architecture.md) for the concurrency model, the GC strategy and the reusable Go libraries.
29
30Small on purpose, and staying small: no blur, shadows or themes. No built-in bar or wallpaper either: bring your own, any layer-shell client works.
31
32## Install
33
34### Arch Linux
35
36```sh
37paru -S neferwl-bin   # latest release, pre-built for x86_64 and aarch64
38paru -S neferwl-git   # latest main, built from source
39```
40
41Or install from a checkout with Go 1.27:
42
43```sh
44make install   # build a package from HEAD and install it with pacman
45```
46
47`make pkg` builds the package without installing it.
48
49### Ubuntu 24.04 and later
50
51Download the `.deb` for your architecture (`amd64` or `arm64`) and `checksums.txt` from [Releases](https://github.com/bnema/neferwl/releases), then install it with apt, which pulls the runtime dependencies:
52
53```sh
54sha256sum -c --ignore-missing checksums.txt
55sudo apt install ./neferwl_<version>_amd64.deb
56```
57
58```sh
59sudo apt install foot fuzzel xdg-desktop-portal-gtk xdg-desktop-portal-gnome
60```
61
62X11 apps need [xwayland-satellite](https://github.com/Supreeeme/xwayland-satellite) 0.7 or later, which you may have to build. The package is tested on Ubuntu 24.04 and 26.04; Debian with the same library packages should work but is untested.
63
64The packages provide:
65
66- `neferwl` with CAP_SYS_NICE for real-time scheduling.
67- A **NeferWL** session for display managers such as Ly, GDM and SDDM.
68- `neferwl-session`, which starts `neferwl.service` and manages `graphical-session.target` so desktop services start and stop with the session.
69
70Running `neferwl --session` directly also exports the display environment to D-Bus and systemd user services. See [Desktop integration](docs/desktop.md) for session setup.
71
72Copy `/usr/share/doc/neferwl/config.example` to `~/.config/neferwl/config` to start from the example config.
73
74### Other distributions
75
76Download a `linux_amd64` or `linux_arm64` archive from [Releases](https://github.com/bnema/neferwl/releases) and verify it against `checksums.txt`. To build locally, run `make bin`; the binary is `bin/neferwl`.
77
78## Configuration
79
80The default file is `$XDG_CONFIG_HOME/neferwl/config`, or `~/.config/neferwl/config`.
81
82```text
83keyboard.layout = fr
84terminal.auto-open = first
85startup = waybar
86
87output.DP-1 = 3840x2160@144
88output.DP-1.scale = 1.5
89
90layout.max-columns = 3
91
92# Start and place an editor and terminal when this workspace is opened.
93workspace.dev.monitor = DP-1
94workspace.dev.column.1 = 67%, code --new-window
95workspace.dev.column.2 = 33%, foot
96bind.cmd+d = workspace dev
97```
98
99- Use one `key = value` per line; `#` starts a comment.
100- Missing keys use defaults. Invalid lines warn and keep that key's default; other lines still apply.
101- Save to reload. The log lists changed keys.
102- Use `neferwl --config <path>` to select a file, or `neferwl validate-config [path]` to check it without starting the compositor.
103
104### Common settings
105
106| Key | Default | Meaning |
107| --- | --- | --- |
108| `keyboard.layout` | system | xkb layout, e.g. `fr` |
109| `keyboard.cmd` | `super` | Modifier used as `cmd` |
110| `terminal` | `$TERMINAL`, then `foot` | Terminal command |
111| `terminal.auto-open` | `first` | Open on initial numbered workspace; also `all` or `off` |
112| `startup` | none | Session-start commands, separated by `;` |
113| `layout.max-columns` | `2` | Columns sharing the screen |
114| `layout.overflow` | `cascade` | Overflow layout: `cascade`, `scroll`, `fixed` |
115| `layout.gaps` | `0` | Space between windows |
116| `output.<name>` | `preferred` | Mode: `WxH@Hz`, `preferred` or `off` |
117| `output.<name>.scale` | `1` | Fractional scale, 1 to 4 |
118| `output.<name>.hdr` | `off` | HDR on capable displays |
119| `touchpad.natural-scroll` | `off` | Content follows fingers |
120| `stash.width` | `80` | Selected stash window width, percent |
121| `hint.enable` | `off` | Experimental keyboard clicking; restart required |
122| `animations` | `off` | Experimental layout and swipe animations |
123
124### Default key bindings
125
126`cmd` means Super by default. Hint mode has no default binding.
127
128| Keys | Action |
129| --- | --- |
130| `cmd+return` | Open terminal |
131| `ctrl+cmd+space` | Launch fuzzel |
132| `cmd+q` | Close window |
133| `cmd+arrows` / `cmd+h/j/k/l` | Focus columns and windows |
134| `cmd+shift+arrows` | Move columns and windows |
135| `cmd+o` | Toggle overview |
136| `cmd+s` | Show/hide stash |
137| `cmd+shift+s` | Move window into/out of stash |
138| `cmd+shift+f` | Toggle fullscreen |
139| `cmd+shift+space` | Toggle floating |
140| `cmd+1`…`9` (physical digit keys) | Focus numbered workspace |
141| `cmd+pageup/pagedown` | Previous/next workspace |
142
143See [Configuration](docs/config.md) for all keys, actions, bindings and automatic-terminal behavior, or [examples/config](examples/config) for commented defaults.
144
145## Features
146
147### Display and games
148
149- Eligible fullscreen buffers use direct scanout; VRR and tearing are on by default for supported fullscreen use (`render.vrr`, `render.tearing`). Tearing requires direct scanout and a client request.
150- Explicit sync carries client fences to the GPU and KMS, enabled by default with no flag. HDR10 on capable displays includes configurable SDR brightness.
151- Separate workspaces and fractional scale per output; workspaces move when a monitor is unplugged and return when it reconnects.
152- Hidden apps get frame callbacks once per second and the suspended state, whether on another workspace, in a hidden stash, off screen or under fullscreen. Captured windows keep their output's refresh rate.
153- Steam and other X11 clients run through xwayland-satellite; Wine can run natively on Wayland.
154
155### Windows and workspaces
156
157- [Cascade tiling](docs/config.md#cascade) is the default; horizontal scrolling (as in PaperWM and niri) and fixed spiral layouts are available per output or workspace.
158- Numbered workspaces appear as needed; named workspaces can start commands and place windows in predefined columns.
159- Overview and stash keep workspaces and set-aside windows close at hand, with keyboard, pointer and touchpad navigation.
160
161### Desktop integration
162
163Bring your own layer-shell UI, such as Noctalia or Waybar. For capture and idle management, see [nefercap](https://github.com/bnema/nefercap) and [neferafk](https://github.com/bnema/neferafk).
164
165Configuration is a flat `key = value` file that reloads on save. A JSON state file exposes outputs, workspaces and windows to scripts; see [Desktop integration](docs/desktop.md).
166
167## Hardware support
168
169NeferWL requires Linux, atomic KMS and a Vulkan 1.3 device that can export images as dmabufs. It reports an error at startup if these requirements are not met.
170
171| GPU | Status |
172| --- | --- |
173| AMD | Developed and tested on radv |
174| NVIDIA | Untested; explicit sync is implemented, but support is incomplete |
175| Intel | Untested |
176
177Reports from NVIDIA and Intel users are welcome.
178
179## Documentation
180
181- [Configuration](docs/config.md): keys, actions, bindings, layouts, overview, stash, hint mode and HDR.
182- [Desktop integration](docs/desktop.md): sessions, clipboard, input methods, X11 apps, session locking and scripting.
183- [Screen capture](docs/capture.md): protocols, indicator, executable allowlist and portals.
184- [Performance](docs/performance.md): VRR and real-time priority.
185- [Developer documentation](docs/dev/index.md): architecture, headless testing, profiling and frame stats.
186
187## Contributing
188
189Issues are welcome, including NVIDIA and Intel reports. Please open an issue before a large pull request; small fixes are fine directly.
190
191Before submitting, run `make check`, `make race`, `make mocks-check` and `staticcheck ./...`. See [AGENTS.md](AGENTS.md) for repository rules.
192
193## License
194
195[GNU General Public License v3.0](LICENSE).