docs(xwayland): describe the built-in backend and drop the launcher handoff note
- commit
- a97cce03430f86cbce11ac4b5d5844a2767683af
- author
- brice · · 2026-10-22 06:23 UTC
- committer
- brice · · 2026-10-22 17:54 UTC
- parent
- e82a03e
- signature
- GPG Verified
CD88F9E564E0102646FB6077A1A07C7C7C3E349D· arch-gpg Verified for the committer email
3 files · +2 -54
M docs/config.md +1 -1
| @@ -103,7 +103,7 @@ destination output, even if that output has no windows. Same-screen workspace | |||
| 103 | 103 | switches and mouse focus do not trigger a flash. | |
| 104 | 104 | It runs when `animations = on`. | |
| 105 | 105 | ||
| 106 | - | `xwayland = satellite` uses `xwayland-satellite` from `PATH`; a custom path also selects satellite. `off` disables X11. `builtin`: neferwl starts `Xwayland` itself (experimental). Built-in X11 windows are not managed. | |
| 106 | + | `xwayland = satellite` uses `xwayland-satellite` from `PATH`; a custom path also selects satellite. `off` disables X11. `builtin` (experimental): neferwl starts `Xwayland` itself and manages X11 windows with its own window manager. | |
| 107 | 107 | ||
| 108 | 108 | ## Automatic terminal | |
| 109 | 109 | ||
| @@ -103,7 +103,7 @@ destination output, even if that output has no windows. Same-screen workspace | |||||
| 103 | switches and mouse focus do not trigger a flash. | 103 | switches and mouse focus do not trigger a flash. | ||
| 104 | It runs when `animations = on`. | 104 | It runs when `animations = on`. | ||
| 105 | 105 | ||||
| 106 | - | `xwayland = satellite` uses `xwayland-satellite` from `PATH`; a custom path also selects satellite. `off` disables X11. `builtin`: neferwl starts `Xwayland` itself (experimental). Built-in X11 windows are not managed. | 106 | + | `xwayland = satellite` uses `xwayland-satellite` from `PATH`; a custom path also selects satellite. `off` disables X11. `builtin` (experimental): neferwl starts `Xwayland` itself and manages X11 windows with its own window manager. |
| 107 | 107 | ||||
| 108 | ## Automatic terminal | 108 | ## Automatic terminal | ||
| 109 | 109 | ||||
M docs/desktop.md +1 -1
| @@ -58,7 +58,7 @@ By default, X11 apps such as Steam run through [xwayland-satellite](https://gith | |||
| 58 | 58 | xwayland = off # no X11 support | |
| 59 | 59 | ``` | |
| 60 | 60 | ||
| 61 | - | With `xwayland = builtin`, neferwl starts `Xwayland` itself (experimental). Built-in X11 windows are not managed. | |
| 61 | + | With `xwayland = builtin` (experimental), neferwl starts `Xwayland` itself and manages X11 windows with its own window manager. | |
| 62 | 62 | ||
| 63 | 63 | ## Session locking | |
| 64 | 64 | ||
| @@ -58,7 +58,7 @@ By default, X11 apps such as Steam run through [xwayland-satellite](https://gith | |||||
| 58 | xwayland = off # no X11 support | 58 | xwayland = off # no X11 support | ||
| 59 | ``` | 59 | ``` | ||
| 60 | 60 | ||||
| 61 | - | With `xwayland = builtin`, neferwl starts `Xwayland` itself (experimental). Built-in X11 windows are not managed. | 61 | + | With `xwayland = builtin` (experimental), neferwl starts `Xwayland` itself and manages X11 windows with its own window manager. |
| 62 | 62 | ||||
| 63 | ## Session locking | 63 | ## Session locking | ||
| 64 | 64 | ||||
D docs/dev/xwayland-builtin-phase5.md +0 -52
| @@ -1,52 +0,0 @@ | |||
| 1 | - | # Built-in launcher verification (Phase 5) | |
| 2 | - | ||
| 3 | - | Verified on 2026-10-22 with Go 1.27.3 and Xwayland 24.1.14-1. | |
| 4 | - | The launcher uses only the decided `:N -rootless -listenfd ... -wm ... | |
| 5 | - | -displayfd ...` arguments (no `-terminate`). `/usr/sbin/Xwayland -help` | |
| 6 | - | confirms each flag. No XWM or global filter is implemented. | |
| 7 | - | ||
| 8 | - | ## Headless evidence | |
| 9 | - | ||
| 10 | - | Built using `CGO_ENABLED=0 go build -o /tmp/xwb/neferwl ./cmd/neferwl`. | |
| 11 | - | Both runs used `env -u NEFERWL_STATE -u NEFERWL_SLOT`, throwaway configs, | |
| 12 | - | separate `XDG_STATE_HOME` directories, `--backend=headless --no-terminal | |
| 13 | - | --size 640x360`, and bounded `--timeout` shutdowns. Neither used | |
| 14 | - | `--no-xwayland`. | |
| 15 | - | ||
| 16 | - | Built-in (`xwayland = builtin`): | |
| 17 | - | ||
| 18 | - | - Reserved `DISPLAY=:1`, Wayland socket `wayland-2` at 08:16:55. | |
| 19 | - | - No Xwayland process started before the X client connected at 08:16:57. | |
| 20 | - | - Logged `Xwayland started` (pid 160850), `Xwayland attached`, and | |
| 21 | - | `Xwayland ready` at 08:16:57. | |
| 22 | - | - **Unmet gate:** `DISPLAY=:1 timeout 5s xprop -root` timed out (124), | |
| 23 | - | without output. A second run with debug logging and strace reproduced | |
| 24 | - | the timeout despite readiness. No fatal Xwayland error was logged. | |
| 25 | - | Root cause is not established; the WM socket is intentionally held open | |
| 26 | - | without an X11 handshake or requests in this phase. Do not treat the | |
| 27 | - | readiness signal as proof that external X11 clients work without an XWM. | |
| 28 | - | - Compositor exited 0 on timeout. Before and after `pgrep -a Xwayland` | |
| 29 | - | contained only the user's existing pid 4467 on `:0`. | |
| 30 | - | ||
| 31 | - | Default satellite (config with no xwayland key): | |
| 32 | - | ||
| 33 | - | - Reserved `:1`, started satellite pid 175585 only after the client connected. | |
| 34 | - | - `DISPLAY=:1 timeout 4s xprop -root` exited 0, printing `_NET_SUPPORTED`, | |
| 35 | - | `_NET_ACTIVE_WINDOW`, `_NET_SUPPORTING_WM_CHECK`, `_XKB_RULES_NAMES`. | |
| 36 | - | - Compositor exited 0; only pre-existing Xwayland pid 4467 remained. | |
| 37 | - | ||
| 38 | - | Raw local artifacts: `/tmp/xwb/{builtin-state,satellite-state}/neferwl/runs/headless/`, | |
| 39 | - | `builtin-xprop.txt`, `satellite-xprop.txt`, `before.txt`, `after.txt`, `trace`. | |
| 40 | - | ||
| 41 | - | ## Phase 6 handoff | |
| 42 | - | ||
| 43 | - | `Server.xwayland` is display-owner state. It records the adopted Wayland | |
| 44 | - | client and holds the WM socket until replacement, client destruction or | |
| 45 | - | server shutdown. Phase 6 takes this fd for the XWM. `AttachXwayland` owns | |
| 46 | - | both fds on call, including failure and stopped-display paths. The launcher | |
| 47 | - | duplicates parent socket descriptors before handing them off, so `os.File` | |
| 48 | - | cleanup/finalizers cannot close descriptors owned by libwayland/the server. | |
| 49 | - | ||
| 50 | - | The external-client timeout needs resolution before declaring the full | |
| 51 | - | Phase 5 acceptance gate satisfied; no extra flags or partial XWM were added | |
| 52 | - | to bypass the decided boundary. | |
| @@ -1,52 +0,0 @@ | |||||
| 1 | - | # Built-in launcher verification (Phase 5) | |||
| 2 | - | ||||
| 3 | - | Verified on 2026-10-22 with Go 1.27.3 and Xwayland 24.1.14-1. | |||
| 4 | - | The launcher uses only the decided `:N -rootless -listenfd ... -wm ... | |||
| 5 | - | -displayfd ...` arguments (no `-terminate`). `/usr/sbin/Xwayland -help` | |||
| 6 | - | confirms each flag. No XWM or global filter is implemented. | |||
| 7 | - | ||||
| 8 | - | ## Headless evidence | |||
| 9 | - | ||||
| 10 | - | Built using `CGO_ENABLED=0 go build -o /tmp/xwb/neferwl ./cmd/neferwl`. | |||
| 11 | - | Both runs used `env -u NEFERWL_STATE -u NEFERWL_SLOT`, throwaway configs, | |||
| 12 | - | separate `XDG_STATE_HOME` directories, `--backend=headless --no-terminal | |||
| 13 | - | --size 640x360`, and bounded `--timeout` shutdowns. Neither used | |||
| 14 | - | `--no-xwayland`. | |||
| 15 | - | ||||
| 16 | - | Built-in (`xwayland = builtin`): | |||
| 17 | - | ||||
| 18 | - | - Reserved `DISPLAY=:1`, Wayland socket `wayland-2` at 08:16:55. | |||
| 19 | - | - No Xwayland process started before the X client connected at 08:16:57. | |||
| 20 | - | - Logged `Xwayland started` (pid 160850), `Xwayland attached`, and | |||
| 21 | - | `Xwayland ready` at 08:16:57. | |||
| 22 | - | - **Unmet gate:** `DISPLAY=:1 timeout 5s xprop -root` timed out (124), | |||
| 23 | - | without output. A second run with debug logging and strace reproduced | |||
| 24 | - | the timeout despite readiness. No fatal Xwayland error was logged. | |||
| 25 | - | Root cause is not established; the WM socket is intentionally held open | |||
| 26 | - | without an X11 handshake or requests in this phase. Do not treat the | |||
| 27 | - | readiness signal as proof that external X11 clients work without an XWM. | |||
| 28 | - | - Compositor exited 0 on timeout. Before and after `pgrep -a Xwayland` | |||
| 29 | - | contained only the user's existing pid 4467 on `:0`. | |||
| 30 | - | ||||
| 31 | - | Default satellite (config with no xwayland key): | |||
| 32 | - | ||||
| 33 | - | - Reserved `:1`, started satellite pid 175585 only after the client connected. | |||
| 34 | - | - `DISPLAY=:1 timeout 4s xprop -root` exited 0, printing `_NET_SUPPORTED`, | |||
| 35 | - | `_NET_ACTIVE_WINDOW`, `_NET_SUPPORTING_WM_CHECK`, `_XKB_RULES_NAMES`. | |||
| 36 | - | - Compositor exited 0; only pre-existing Xwayland pid 4467 remained. | |||
| 37 | - | ||||
| 38 | - | Raw local artifacts: `/tmp/xwb/{builtin-state,satellite-state}/neferwl/runs/headless/`, | |||
| 39 | - | `builtin-xprop.txt`, `satellite-xprop.txt`, `before.txt`, `after.txt`, `trace`. | |||
| 40 | - | ||||
| 41 | - | ## Phase 6 handoff | |||
| 42 | - | ||||
| 43 | - | `Server.xwayland` is display-owner state. It records the adopted Wayland | |||
| 44 | - | client and holds the WM socket until replacement, client destruction or | |||
| 45 | - | server shutdown. Phase 6 takes this fd for the XWM. `AttachXwayland` owns | |||
| 46 | - | both fds on call, including failure and stopped-display paths. The launcher | |||
| 47 | - | duplicates parent socket descriptors before handing them off, so `os.File` | |||
| 48 | - | cleanup/finalizers cannot close descriptors owned by libwayland/the server. | |||
| 49 | - | ||||
| 50 | - | The external-client timeout needs resolution before declaring the full | |||
| 51 | - | Phase 5 acceptance gate satisfied; no extra flags or partial XWM were added | |||
| 52 | - | to bypass the decided boundary. | |||