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-AGPLv3-blue?style=flat-square" alt="License: AGPLv3"></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/1ff42ce5-47b3-4cf8-a3a7-5fc5abde4af1
12
13<p align="center"><sub>Stash, overview and animations, recorded on the headless backend at 1080p.</sub></p>
14
15> [!WARNING]
16> **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.
17
18## Why NeferWL
19
20- **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).
21- **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).
22- **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).
23- **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).
24- **Hint mode:** click links and buttons by typing their labels, without reaching for the mouse. Enable experimental `hint.enable` and add a bind; see [Hint mode](docs/config.md#hint-mode).
25- **Animations:** short, cheap and off by default. Opt in with experimental `animations = on`; see [Configuration](docs/config.md#keys).
26
27Written 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.
28
29Small 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.
30
31## Install
32
33### Arch Linux
34
35```sh
36paru -S neferwl-bin   # latest release, pre-built for x86_64 and aarch64
37paru -S neferwl-git   # latest main, built from source
38```
39
40Or install from a checkout with Go 1.27:
41
42```sh
43make install   # build a package from HEAD and install it with pacman
44```
45
46`make pkg` builds the package without installing it.
47
48### Ubuntu 24.04 and later
49
50Download the `.deb` for your architecture (`amd64` or `arm64`) and `checksums.txt` from [Releases](https://git.bnema.dev/neferwl/releases), then install it with apt, which pulls the runtime dependencies:
51
52```sh
53sha256sum -c --ignore-missing checksums.txt
54sudo apt install ./neferwl_<version>_amd64.deb
55```
56
57```sh
58sudo apt install foot fuzzel xdg-desktop-portal-gtk xdg-desktop-portal-gnome
59```
60
61X11 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.
62
63The packages provide:
64
65- `neferwl` with CAP_SYS_NICE for real-time scheduling.
66- A **NeferWL** session for display managers such as Ly, GDM and SDDM.
67- `neferwl-session`, which starts `neferwl.service` and manages `graphical-session.target` so desktop services start and stop with the session.
68
69Running `neferwl --session` directly also exports the display environment to D-Bus and systemd user services. See [Desktop integration](docs/desktop.md) for session setup.
70
71Copy `/usr/share/doc/neferwl/config.example` to `~/.config/neferwl/config` to start from the example config.
72
73### Other distributions
74
75Download a `linux_amd64` or `linux_arm64` archive from [Releases](https://git.bnema.dev/neferwl/releases) and verify it against `checksums.txt`. To build locally, run `make bin`; the binary is `bin/neferwl`.
76
77## Configuration
78
79The default file is `$XDG_CONFIG_HOME/neferwl/config`, or `~/.config/neferwl/config`.
80
81```text
82keyboard.layout = fr
83terminal.auto-open = first
84startup = waybar
85
86output.DP-1 = 3840x2160@144
87output.DP-1.scale = 1.5
88
89layout.max-columns = 3
90
91# Start and place an editor and terminal when this workspace is opened.
92workspace.dev.monitor = DP-1
93workspace.dev.column.1 = 67%, code --new-window
94workspace.dev.column.2 = 33%, foot
95bind.cmd+d = workspace dev
96```
97
98- Use one `key = value` per line; `#` starts a comment.
99- Missing keys use defaults. Invalid lines warn and keep that key's default; other lines still apply.
100- Save to reload. The log lists changed keys.
101- Use `neferwl --config <path>` to select a file, or `neferwl validate-config [path]` to check it without starting the compositor.
102
103### Common settings
104
105| Key | Default | Meaning |
106| --- | --- | --- |
107| `keyboard.layout` | system | xkb layout, e.g. `fr` |
108| `keyboard.cmd` | `super` | Modifier used as `cmd` |
109| `terminal` | `$TERMINAL`, then `foot` | Terminal command |
110| `terminal.auto-open` | `first` | Open on initial numbered workspace; also `all` or `off` |
111| `startup` | none | Session-start commands, separated by `;` |
112| `layout.max-columns` | `2` | Columns sharing the screen |
113| `layout.overflow` | `cascade` | Overflow layout: `cascade`, `scroll`, `fixed` |
114| `layout.gaps` | `0` | Space between windows |
115| `output.<name>` | `preferred` | Mode: `WxH@Hz`, `preferred` or `off` |
116| `output.<name>.scale` | `1` | Fractional scale, 1 to 4 |
117| `output.<name>.hdr` | `off` | HDR on capable displays |
118| `touchpad.natural-scroll` | `off` | Content follows fingers |
119| `stash.width` | `80` | Selected stash window width, percent |
120| `hint.enable` | `off` | Experimental keyboard clicking; restart required |
121| `animations` | `off` | Experimental layout and swipe animations |
122
123### Default key bindings
124
125`cmd` means Super by default. Hint mode has no default binding.
126
127| Keys | Action |
128| --- | --- |
129| `cmd+return` | Open terminal |
130| `ctrl+cmd+space` | Launch fuzzel |
131| `cmd+q` | Close window |
132| `cmd+arrows` / `cmd+h/j/k/l` | Focus columns and windows |
133| `cmd+shift+arrows` | Move columns and windows |
134| `cmd+o` | Toggle overview |
135| `cmd+s` | Show/hide stash |
136| `cmd+shift+s` | Move window into/out of stash |
137| `cmd+shift+f` | Toggle fullscreen |
138| `cmd+shift+space` | Toggle floating |
139| `cmd+1`…`9` (physical digit keys) | Focus numbered workspace |
140| `cmd+pageup/pagedown` | Previous/next workspace |
141
142See [Configuration](docs/config.md) for all keys, actions, bindings and automatic-terminal behavior, or [examples/config](examples/config) for commented defaults.
143
144## Features
145
146### Display and games
147
148- 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.
149- Explicit sync carries client fences to the GPU and KMS, enabled by default with no flag. HDR10 on capable displays includes configurable SDR brightness.
150- Separate workspaces and fractional scale per output; workspaces move when a monitor is unplugged and return when it reconnects.
151- 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.
152- Steam and other X11 clients run through xwayland-satellite, or through the experimental built-in window manager (`xwayland = builtin`; menus, popups and tooltips, fullscreen games with keyboard grab; text clipboard and primary selection in both directions, XSETTINGS and a themed root cursor). Wine can run natively on Wayland.
153
154### Windows and workspaces
155
156- [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.
157- Numbered workspaces appear as needed; named workspaces can start commands and place windows in predefined columns.
158- Overview and stash keep workspaces and set-aside windows close at hand, with keyboard, pointer and touchpad navigation.
159
160### Desktop integration
161
162Bring 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).
163
164Configuration 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).
165
166## Hardware support
167
168NeferWL 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.
169
170| GPU | Status |
171| --- | --- |
172| AMD | Developed and tested on radv |
173| NVIDIA | Untested; explicit sync is implemented, but support is incomplete |
174| Intel | Untested |
175
176Reports from NVIDIA and Intel users are welcome.
177
178## Documentation
179
180- [Configuration](docs/config.md): keys, actions, bindings, layouts, overview, stash, hint mode and HDR.
181- [Desktop integration](docs/desktop.md): sessions, clipboard, input methods, X11 apps, session locking and scripting.
182- [Screen capture](docs/capture.md): protocols, indicator, executable allowlist and portals.
183- [Performance](docs/performance.md): VRR and real-time priority.
184- [Developer documentation](docs/dev/index.md): architecture, headless testing, profiling and frame stats.
185
186## Contributing
187
188Issues are welcome, including NVIDIA and Intel reports. Please open an issue before a large pull request; small fixes are fine directly.
189
190Before submitting, run `make check`, `make race`, `make mocks-check` and `staticcheck ./...`. See [AGENTS.md](AGENTS.md) for repository rules.
191
192## License
193
194[GNU Affero General Public License v3.0](LICENSE).