Samuel Onoja
eb84104940
Publish the guides from this repository to the GitHub Wiki. Organize them into Usage, Configuration and Development, with 15 separate configuration topics and redirects for the former website guide URLs. Add a tabbed-windows guide covering grouping, switching tabs and taking windows out. Document the scrolling indicator's defaults and limits, and link the guide from the README, shortcuts and IPC pages. Update from main, including the latest tabbed-layout changes. Separate Activities setup, configuration and publishing documentation. Review the guide prose with the unslop skill, keeping existing examples and heading links. The wiki workflow uses GitHub's built-in token to publish documentation changes on main. Validation: - 20 documentation tests pass, including README links and Activities/tab-indicator field coverage. - The publisher builds 46 wiki pages; the site build and Python syntax checks pass. - All 115 code examples from main are preserved. - The Python suite passes: 90 tests passed and 31 opt-in integration tests skipped, with the system GI module available.
90 lines
4.5 KiB
Markdown
90 lines
4.5 KiB
Markdown
# X11 support (xwayland-satellite)
|
|
|
|
Ferese can run legacy X11-only applications through
|
|
[xwayland-satellite](https://github.com/Supreeeme/xwayland-satellite).
|
|
```kdl
|
|
xwayland {
|
|
enabled #true
|
|
startup on-demand
|
|
path "xwayland-satellite"
|
|
}
|
|
```
|
|
|
|
| Key | Values | Default | Meaning |
|
|
| --- | --- | --- | --- |
|
|
| `enabled` | `true` / `false` | `true` | Run the bridge at all. `false` is a complete opt-out. |
|
|
| `startup` | `on-demand` / `eager` | `on-demand` | `on-demand` starts Satellite the first time an application connects to the X11 socket. `eager` starts it during session startup. |
|
|
| `path` | path to an executable | `xwayland-satellite` | Which binary to run. |
|
|
|
|
These keys require a new session. Reloading configuration does not restart or
|
|
reallocate the X11 service; `feresectl xwayland status` reports
|
|
`restart_required` when the running configuration no longer matches the file.
|
|
|
|
## Requirements and failure behavior
|
|
|
|
`xwayland-satellite` and an `Xwayland` binary it can find must be installed.
|
|
Satellite must be built with its `systemd` feature enabled
|
|
(`cargo build --release --features systemd`); that feature sends the `READY=1`
|
|
notification Ferese waits for. Upstream's default feature set is empty, so a
|
|
default build never sends it and every start ends in a startup failure after
|
|
Ferese's fixed 10-second budget, even though the process is running. Being
|
|
spawned is not readiness. If any of these are missing, the session still starts
|
|
as a normal Wayland desktop and `feresectl xwayland status` explains why X11 is
|
|
unavailable. Ferese never publishes a `DISPLAY` value that does not work, so
|
|
applications fail cleanly instead of hanging against an endpoint that accepts
|
|
nothing.
|
|
|
|
In a nested session, Ferese's own environment is preserved for backend
|
|
initialization, but applications it launches receive the new Ferese endpoints.
|
|
The host's `DISPLAY` is never exported to the activation environment of a nested
|
|
session, so it cannot leak into services started by your login session.
|
|
|
|
## Diagnostics and recovery
|
|
|
|
```text
|
|
feresectl xwayland status
|
|
feresectl xwayland retry
|
|
```
|
|
|
|
`status` reports whether the service is idle, starting, running, backing off, or
|
|
failed, plus the display, the Satellite PID, and whether readiness was verified.
|
|
A failed service is not restarted automatically: Ferese retries a small bounded
|
|
number of times, then stops and waits, so a broken binary cannot produce a
|
|
restart loop. Run `feresectl xwayland retry` once the cause is fixed. The
|
|
snapshot never contains the X11 cookie, so it is safe to paste into a bug
|
|
report.
|
|
|
|
`retry` can also refuse to run. If the previous service group cannot be proven
|
|
gone — for example it survived the stop sequence — Ferese keeps its cleanup
|
|
record instead of starting a second generation that would compete with
|
|
survivors for the same display, and the retry fails with a message naming what
|
|
still holds the X11 display. The endpoint is not republished in the meantime.
|
|
Run the retry again once that group has finished exiting.
|
|
|
|
Each start uses a fresh, private notification socket and only a `READY=1`
|
|
message from the Satellite process that was actually spawned is accepted, so a
|
|
stale or unrelated notification cannot be mistaken for readiness.
|
|
|
|
## Limitations
|
|
|
|
- X11 applications are ordinary Wayland windows as far as layout, focus, and
|
|
window rules are concerned. Rules match the application identity Satellite
|
|
reports, so they are configured the same way as for native clients.
|
|
- Native Wayland preferences are kept as they are. Ferese does not force GTK,
|
|
Qt, Firefox, or Electron onto X11 to demonstrate support.
|
|
- Portal dialogs requested with an `x11:` parent are shown **unparented**. The
|
|
chooser or consent prompt still opens and authorization is unchanged; Ferese
|
|
does not yet translate an X11 window ID into a Wayland export, and inventing a
|
|
parent would be a security problem.
|
|
- Per-monitor fractional scaling of X11 applications depends on the selected
|
|
Satellite build and its Xsettings policy. Text sharpness, pointer coordinates,
|
|
and popup placement should be checked on each output profile rather than
|
|
assumed.
|
|
- Drag and drop between native and X11 applications depends on the Satellite
|
|
build and is not part of the initial support claim.
|
|
- Sandboxed applications may need explicit permission to reach the display. A
|
|
flatpak with only `fallback-x11` gets no X11 socket inside a Wayland session and
|
|
cannot read the private `XAUTHORITY` file under `$XDG_RUNTIME_DIR`, so it exits
|
|
without a window while the service itself reports healthy. See
|
|
[Sandboxed applications](../installation.md#sandboxed-applications).
|