Rewrite documentation and complete shortcut and feature lists
This commit is contained in:
Samuel Onoja committed
1 parent
bbb1eac189
commit
17243464f6
18 files changed
+257
-222
No files matched your search
@@ -2,7 +2,7 @@
|
||||
<img src="docs/images/ferese-lockup.svg" width="300" alt="Ferese">
|
||||
</p>
|
||||
|
||||
<p align="center"><strong>A complete Wayland desktop built around personalization</strong></p>
|
||||
<p align="center"><strong>A configurable Wayland desktop</strong></p>
|
||||
|
||||
<p align="center">
|
||||
<a href="docs/installation.md">Install</a> ·
|
||||
@@ -11,7 +11,7 @@
|
||||
<a href="docs/README.md">Documentation</a>
|
||||
</p>
|
||||
|
||||
Ferese is a window manager and desktop shell built together and configured in one place, for people who want their desktop to be their own.
|
||||
Ferese combines a window manager and desktop shell with one configuration.
|
||||
|
||||
|
||||
|
||||
@@ -19,14 +19,16 @@ Ferese is a window manager and desktop shell built together and configured in on
|
||||
|
||||
## Features
|
||||
|
||||
- Scrolling columns, tree tiling and floating windows, with an overview of all your workspaces
|
||||
- Keyboard shortcuts and touchpad gestures you can remap
|
||||
- Multiple monitors with fractional scaling
|
||||
- Themes, wallpapers, blur and corners that update live, with Light/Dark/Auto modes and custom KDL themes
|
||||
- Scrolling columns with window grouping, tree tiling and floating windows that remember their size and placement
|
||||
- Workspace overview and recent-window switching
|
||||
- Remappable keyboard shortcuts and touchpad gestures
|
||||
- Multiple monitors with fractional scaling and automatic refresh-rate switching on low battery
|
||||
- Themes, wallpapers and blur that update live, with Light/Dark/Auto modes and custom KDL themes
|
||||
- Squircle window corners with matching borders and shadows
|
||||
- Desktop widgets, including a clock and sticky notes
|
||||
- Screenshots with annotation, plus screen sharing and built-in recording
|
||||
- A built-in lock screen
|
||||
- Integrated Settings and Control Center for configuring your desktop
|
||||
- Screenshots with annotation, screen sharing and built-in recording
|
||||
- A built-in lock screen and authentication dialogs
|
||||
- Settings and Control Center with Wi-Fi, Bluetooth and audio controls
|
||||
|
||||
## Install
|
||||
|
||||
@@ -45,9 +47,8 @@ guide](docs/installation.md) also walks you through previews, updates and recove
|
||||
|
||||
## Configure
|
||||
|
||||
Make it yours through **Control Center → Settings** or `~/.config/ferese/config.kdl`,
|
||||
with changes applying as you make them and the last working configuration staying in
|
||||
place if an edit is invalid.
|
||||
Configure Ferese through **Control Center → Settings** or `~/.config/ferese/config.kdl`.
|
||||
Changes apply live. Invalid edits leave the last working configuration in place.
|
||||
|
||||
The [configuration reference](docs/configuration.md) and [example
|
||||
config](packaging/config.kdl) cover everything from appearance and window layouts to
|
||||
@@ -78,16 +79,14 @@ Shortcuts** whenever you want to change a shortcut or gesture.
|
||||
| Three-finger swipe up / down | Next / previous workspace |
|
||||
| Three-finger swipe left / right | Focus the window to the right / left |
|
||||
|
||||
Explore [all shortcuts and mouse actions](docs/shortcuts.md) for more ways to arrange
|
||||
your windows and move between workspaces.
|
||||
See [all shortcuts and mouse actions](docs/shortcuts.md) for window and workspace controls.
|
||||
|
||||
## Documentation
|
||||
|
||||
The [documentation index](docs/README.md) brings the desktop guides together, while
|
||||
[development instructions](docs/development.md) cover building, testing and
|
||||
contributing.
|
||||
The [documentation index](docs/README.md) lists the desktop guides.
|
||||
[Development instructions](docs/development.md) cover building, testing and contributing.
|
||||
|
||||
Ferese is written in Rust using Smithay, with development happening [on
|
||||
Ferese is written in Rust using Smithay. Development happens [on
|
||||
GitHub](https://github.com/ferese-wm/ferese). If something goes wrong, [open an
|
||||
issue](https://github.com/ferese-wm/ferese/issues) with the steps to reproduce it and
|
||||
any relevant logs.
|
||||
@@ -1,7 +1,7 @@
|
||||
# Ferese theme
|
||||
|
||||
The shared native UI theme for the shell, settings, lock screen, authentication
|
||||
prompt and screen-sharing/recording chooser.
|
||||
This crate supplies the shared native UI theme used by the shell, settings, lock
|
||||
screen, authentication prompt and screen-sharing/recording chooser.
|
||||
|
||||
- `Palette` resolves KDL colors and corners and builds the native toolkit theme.
|
||||
- `PRESETS` defines twelve variants in six families.
|
||||
@@ -17,8 +17,8 @@ prompt and screen-sharing/recording chooser.
|
||||
Keep the attachment alive with its window and make the client background
|
||||
transparent after attachment succeeds. Other compositors retain the client fill.
|
||||
|
||||
Applications supply layout, data, actions, and animation progress. Extend shared
|
||||
components when a style is needed across apps.
|
||||
Each application supplies its layout, data, actions and animation progress.
|
||||
Add styles used by several apps to the shared components.
|
||||
|
||||
```rust
|
||||
let palette = ferese_theme::Palette::from_document(Some(&document));
|
||||
@@ -28,5 +28,5 @@ let font = ferese_theme::font(Some("Inter"));
|
||||
let label = ferese_theme::text("Appearance", font);
|
||||
```
|
||||
|
||||
The compositor owns backdrop blur and material rendering. This crate does not
|
||||
provide a client-side imitation of those effects.
|
||||
Backdrop blur and material rendering happen in the compositor. This crate does
|
||||
not reproduce those effects on the client.
|
||||
+9
-11
@@ -2,23 +2,21 @@
|
||||
|
||||
## Get started
|
||||
|
||||
- [Installation](installation.md): dependencies, login, previews, updates, and recovery.
|
||||
- [Configuration](configuration.md): KDL syntax, layouts, input, shortcuts, and displays.
|
||||
- [Why Ferese](why-ferese.md): layouts and the shared desktop theme.
|
||||
|
||||
- [Screenshots](screenshots.md): desktop themes, overview and shell controls.
|
||||
- [Installation](installation.md): install dependencies, log in, preview changes, update and recover a session.
|
||||
- [Configuration](configuration.md): configure layouts, input, shortcuts and displays in KDL.
|
||||
- [Why Ferese](why-ferese.md): window layouts and a shared theme for the desktop.
|
||||
- [Screenshots](screenshots.md): see the themes, overview and shell controls.
|
||||
|
||||
## Use the desktop
|
||||
|
||||
- [Shortcuts and gestures](shortcuts.md): keyboard navigation, Super-drag, resize, and window grouping.
|
||||
|
||||
- [Lock screen](locking.md): appearance, automatic locking, and display sleep.
|
||||
- [Screen sharing and recording](screen-sharing.md): choosing sources and stopping a session.
|
||||
- [Desktop portals](portals.md): application integration and supported services.
|
||||
- [Shortcuts and gestures](shortcuts.md): keyboard navigation, moving and resizing with Super-drag, and window grouping.
|
||||
- [Lock screen](locking.md): change its appearance, set up automatic locking and configure display sleep.
|
||||
- [Screen sharing and recording](screen-sharing.md): choose a source and stop sharing.
|
||||
- [Desktop portals](portals.md): services available to applications.
|
||||
|
||||
## Develop Ferese
|
||||
|
||||
- [Development](development.md): builds, tests, and portal checks.
|
||||
- [Development](development.md): build Ferese, run tests and check portal contracts.
|
||||
- [Nested resize checks](nested-resize-testing.md).
|
||||
- [Client soak testing](native-soak-testing.md).
|
||||
- [Performance measurements](performance-baseline.md).
|
||||
|
||||
+21
-18
@@ -39,21 +39,22 @@ output-profile "docked" {
|
||||
}
|
||||
```
|
||||
|
||||
Repeated `binding`, `window-rule`, `output-profile`, `output`, `note` and
|
||||
`autostart` nodes describe lists of settings. Bindings accept positional
|
||||
keys/action/argument; profiles, outputs and notes accept a positional name,
|
||||
match or ID. Other fields can be properties or child nodes. Autostart accepts
|
||||
its command as positional arguments. Duplicate fields are rejected.
|
||||
Use repeated `binding`, `window-rule`, `output-profile`, `output`, `note` and
|
||||
`autostart` nodes for lists of settings. Bindings accept keys, an action and its
|
||||
argument positionally. Profiles, outputs and notes accept a positional name,
|
||||
match or ID; other fields can be properties or child nodes. Autostart commands
|
||||
use positional arguments. Duplicate fields are rejected.
|
||||
The dotted paths in the reference tables below describe nested sections.
|
||||
|
||||
Settings preserves comments and custom fields when editing, while normalizing
|
||||
indentation. Configuration uses KDL.
|
||||
indentation.
|
||||
|
||||
## Saving and validation
|
||||
|
||||
Settings saves automatically: text on Enter/focus loss, sliders when released.
|
||||
Undo restores the previous save; Reload picks up external edits without merging
|
||||
unfinished drafts. Wallpaper browsing needs `zenity`; a path can also be entered.
|
||||
Settings saves text when you press Enter or leave the field, and sliders when
|
||||
you release them. Undo restores the previous save. Reload reads external edits
|
||||
without merging unfinished drafts. Wallpaper browsing needs `zenity`, but you
|
||||
can also enter a path directly.
|
||||
Settings keeps `config.kdl.settings-backup` before saving.
|
||||
|
||||
File edits reload automatically, including atomic editor saves. Invalid changes
|
||||
@@ -414,11 +415,12 @@ window rules can override that behavior.
|
||||
| `width`, `height` | numbers > 0 | Application-chosen floating size |
|
||||
| `fullscreen` | boolean | Leave fullscreen state unchanged |
|
||||
|
||||
At least one matcher is required; supplied matchers must all match. Rules apply
|
||||
in order, with later fields overriding earlier ones. Dimensions imply floating
|
||||
when `floating` is omitted. Floating apps without dimensions choose their own
|
||||
size. Placement first centers transients on the visible part of their parent,
|
||||
then tries remembered geometry, then the position with least summed overlap.
|
||||
Every rule needs at least one matcher, and supplied matchers must all match.
|
||||
Rules apply in order; later fields override earlier ones. Dimensions imply
|
||||
floating when `floating` is omitted. Floating apps without dimensions choose
|
||||
their own size. Ferese first tries to center transient windows on the visible
|
||||
part of their parent, then tries saved geometry, then the position with the least
|
||||
summed overlap.
|
||||
Equal-overlap candidates favor the focused window's center. If the size cannot
|
||||
fit, a per-output cascade advances by 32 logical pixels and wraps to the work-area
|
||||
origin. Placement respects layer-shell exclusive zones and client minimum sizes;
|
||||
@@ -426,10 +428,11 @@ an oversized window keeps its size with its top-left corner reachable.
|
||||
|
||||
Successful move/resize completion saves ordinary floating geometry by app ID in
|
||||
`$XDG_STATE_HOME/ferese/floating.json` (normally `~/.local/state/ferese/floating.json`).
|
||||
The output name and work-area fractions preserve placement across resolution
|
||||
changes. Missing outputs and restores with less than 25% visibility are skipped.
|
||||
Saves run on a worker and pending updates coalesce to the latest snapshot;
|
||||
drag completion updates memory immediately without waiting for storage.
|
||||
Geometry is stored with the output name and as fractions of its work area, so
|
||||
placement survives resolution changes. Restores are skipped if the output is
|
||||
missing or less than 25% of the window would be visible. A worker saves the
|
||||
latest snapshot, combining pending updates. Completing a drag updates memory
|
||||
immediately without waiting for storage.
|
||||
Transient dialogs and cancelled drags do not update this memory. Floating → tiled
|
||||
→ floating also restores the window's last floating geometry. Nested previews
|
||||
keep drag memory in process and do not write the user's saved placements.
|
||||
|
||||
+16
-16
@@ -27,9 +27,9 @@ cargo test --locked -p xdg-desktop-portal-ferese
|
||||
python3 scripts/tests/test_portal_contracts.py
|
||||
```
|
||||
|
||||
The contract test uses a private bus. It checks signatures, appearance changes,
|
||||
invalid-config retention, and caller authorization. It does not prove complete
|
||||
compatibility with every app or open consent dialogs.
|
||||
The contract test runs on a private bus and checks signatures, appearance changes,
|
||||
caller authorization and retention of the last working config after invalid edits.
|
||||
It does not open consent dialogs or prove complete compatibility with every app.
|
||||
|
||||
With release binaries built, run isolated integration checks:
|
||||
|
||||
@@ -41,9 +41,9 @@ FERESE_TEST_RESTORE=1 python3 scripts/tests/test_restore_isolated.py
|
||||
FERESE_TEST_WINDOW_STREAM=1 python3 scripts/tests/test_window_stream_isolated.py
|
||||
```
|
||||
|
||||
These cover shortcut cleanup, window capture, inhibitors, restored permissions,
|
||||
and live window streams. Check each script's dependencies before running it.
|
||||
They use disposable nested sessions or private buses.
|
||||
These checks use disposable nested sessions or private buses to test shortcut
|
||||
cleanup, window capture, inhibitors, restored permissions and live window streams.
|
||||
Check each script's dependencies before running it.
|
||||
|
||||
For monitor streaming and lock revocation, install Python GI/GStreamer with
|
||||
`pipewiresrc`, `dbus-daemon`, `xdg-desktop-portal`, and `bwrap`, then run:
|
||||
@@ -77,17 +77,17 @@ access tokens, or private window content.
|
||||
|
||||
## Resume recovery
|
||||
|
||||
The direct backend retains known GPU identities while their DRM resources are
|
||||
unavailable. Hotplug, configuration and lid changes reconcile through one path;
|
||||
inactive sessions defer that work. Activation reads the lid asynchronously, then
|
||||
re-enumerates devices and connectors before allowing presentation. A logind
|
||||
system-wake signal follows the same path, including when seat ownership did not
|
||||
change. Newer libinput observations supersede in-flight lid reads. A failed read
|
||||
preserves the last observation; a three-second deadline prevents a stalled bus
|
||||
from blocking recovery indefinitely.
|
||||
The direct backend keeps track of known GPUs when their DRM resources are
|
||||
unavailable. It handles hotplug, configuration and lid changes through the same
|
||||
recovery path, deferring the work while the session is inactive. On activation,
|
||||
it reads the lid state asynchronously and re-enumerates devices and connectors
|
||||
before allowing presentation. A logind system-wake signal triggers the same work,
|
||||
even if seat ownership has not changed. New libinput observations take precedence
|
||||
over pending lid reads. If a read fails, Ferese keeps the last observation. Reads
|
||||
have a three-second deadline so a stalled bus cannot block recovery indefinitely.
|
||||
|
||||
Device failures retire their output globals and retry with exponential backoff
|
||||
capped at 32 seconds. Working devices remain usable. Known hardware can return
|
||||
When a device fails, Ferese removes its output globals and retries with exponential
|
||||
backoff capped at 32 seconds. Working devices remain usable. Known hardware can return
|
||||
under a different `cardN` path. This does not expand support to previously
|
||||
unmanaged secondary GPUs. Connected-output reports mark a mode active only when
|
||||
output creation succeeded. Lock ownership is retained throughout recovery.
|
||||
|
||||
+29
-29
@@ -1,13 +1,13 @@
|
||||
# Installation
|
||||
|
||||
Ferese runs on Linux as its own Wayland session, alongside your existing desktop, and
|
||||
you can launch it from a login manager, a command-based greeter or a local TTY.
|
||||
Ferese runs on Linux as its own Wayland session alongside your existing desktop.
|
||||
Launch it from a login manager, a command-based greeter or a local TTY.
|
||||
|
||||
## Requirements
|
||||
|
||||
For a full session, you’ll need a Wayland-capable graphics driver and a local user
|
||||
session with seat access through logind or seatd, while a nested preview runs inside the
|
||||
Wayland desktop you already use.
|
||||
session with seat access through logind or seatd. A nested preview runs inside your
|
||||
existing Wayland desktop.
|
||||
|
||||
To build Ferese, install **Rust 1.95 or newer**, a C/C++ toolchain, CMake, pkg-config
|
||||
and the libraries below. The installer builds the Ferese components once those system
|
||||
@@ -49,10 +49,10 @@ sudo apt install build-essential git curl cmake pkg-config libwayland-dev \
|
||||
gstreamer1.0-plugins-good
|
||||
```
|
||||
|
||||
Fedora is the tested installation path, and package names or versions may differ on
|
||||
other distributions, where the [Smithay
|
||||
dependencies](https://github.com/Smithay/smithay#system-dependencies) can help you find
|
||||
equivalent libraries.
|
||||
Installation has been tested on Fedora. Package names or versions may differ on
|
||||
other distributions; check the [Smithay
|
||||
dependencies](https://github.com/Smithay/smithay#system-dependencies) for equivalent
|
||||
libraries.
|
||||
|
||||
### Rust toolchain
|
||||
|
||||
@@ -82,17 +82,17 @@ cd ferese
|
||||
./scripts/install.sh
|
||||
```
|
||||
|
||||
The script builds locked release binaries as your normal user and then asks for
|
||||
administrator access through `sudo` or `pkexec` to install them, so leave the build
|
||||
The script builds locked release binaries as your normal user, then asks for
|
||||
administrator access through `sudo` or `pkexec` to install them. Leave the build
|
||||
itself unprivileged. The first build needs network access to fetch Rust dependencies.
|
||||
|
||||
Installation brings together the session launcher, desktop tools, portal backend, login
|
||||
The installer adds the session launcher, desktop tools, portal backend, login
|
||||
entry, icons, default wallpaper and example config. Releases live under
|
||||
`/usr/local/lib/ferese/releases/` and commands under `/usr/local/bin/`, with `current`
|
||||
and `previous` links for switching between releases during updates and rollback.
|
||||
|
||||
Your configuration, other desktop sessions and existing PAM policy stay in place, while
|
||||
Ferese starts its authentication agent and portal services together with the session.
|
||||
The installer preserves your configuration, other desktop sessions and existing PAM
|
||||
policy. Ferese starts its authentication agent and portal services with the session.
|
||||
The authentication agent registers for the login session, so requests from desktop
|
||||
apps use the Ferese dialog. Remove other polkit agents from your Ferese autostart
|
||||
configuration to avoid competing session registrations.
|
||||
@@ -110,8 +110,8 @@ if [ ! -e "${XDG_CONFIG_HOME:-$HOME/.config}/ferese/config.kdl" ]; then
|
||||
fi
|
||||
```
|
||||
|
||||
After login, open **Control Center → Settings** or run `ferese-settings` to shape your
|
||||
desktop, using [Configuration](configuration.md) for themes, displays, shortcuts and
|
||||
After login, open **Control Center → Settings** or run `ferese-settings` to configure
|
||||
your desktop. See [Configuration](configuration.md) for themes, displays, shortcuts and
|
||||
startup apps. The default terminal is `foot`, which you can replace with your preferred
|
||||
terminal command in Settings.
|
||||
|
||||
@@ -144,8 +144,8 @@ If your greeter asks for a session command instead of reading desktop files, use
|
||||
/usr/local/bin/ferese-session
|
||||
```
|
||||
|
||||
For greetd, set this as the session command after authentication using the [greetd
|
||||
documentation](https://sr.ht/~kennylevinsen/greetd/), and the launcher will start the
|
||||
For greetd, set this as the session command after authentication; see the [greetd
|
||||
documentation](https://sr.ht/~kennylevinsen/greetd/). The launcher starts the
|
||||
compositor, shell and session services together.
|
||||
|
||||
### From a TTY
|
||||
@@ -176,7 +176,7 @@ Install these through your distribution when you want the corresponding features
|
||||
| Audio controls | PipeWire, WirePlumber, and `wpctl` |
|
||||
| Bluetooth controls | BlueZ, `bluetoothctl`, and its running service |
|
||||
|
||||
Package names and availability vary by distribution, so use Satty’s [upstream
|
||||
Package names and availability vary by distribution. Use Satty’s [upstream
|
||||
instructions](https://github.com/Satty-org/Satty#install) if it isn’t in your
|
||||
repositories. Ferese leaves service setup to you and preserves your existing service
|
||||
configuration during installation.
|
||||
@@ -184,8 +184,8 @@ configuration during installation.
|
||||
Use **Print Screen** to capture the active monitor, **Super+Shift+S** to select an area,
|
||||
or `ferese-screenshot --all` to capture all monitors in one image.
|
||||
|
||||
The native locker follows your shell theme and can be personalized in **Settings → Lock
|
||||
Screen**, with `ferese-lock --preview` opening an ordinary preview window. Before
|
||||
The native locker follows your shell theme. Customize it in **Settings → Lock
|
||||
Screen**, and run `ferese-lock --preview` to open an ordinary preview window. Before
|
||||
enabling automatic locking, test real unlocking and read [Native locker](locking.md) for
|
||||
authentication, idle locking and limits.
|
||||
|
||||
@@ -230,11 +230,11 @@ git pull --ff-only
|
||||
./scripts/install.sh
|
||||
```
|
||||
|
||||
Log out and back in to start using the new release, as a running session keeps its
|
||||
existing processes and release paths until it restarts.
|
||||
Log out and back in to use the new release. A running session keeps its existing
|
||||
processes and release paths until it restarts.
|
||||
|
||||
Each release records the portal configuration it ships so later upgrades can identify
|
||||
it, and installation stops if it encounters modified or untracked administrator files.
|
||||
it. Installation stops if it encounters modified or untracked administrator files.
|
||||
To replace Ferese portal configuration from an earlier development install, build first
|
||||
and run `./scripts/install.sh --skip-build --replace-portal-config`, which backs up the
|
||||
existing files in the new release’s `portal-config.previous/` directory.
|
||||
@@ -268,8 +268,8 @@ process:
|
||||
pgrep -a -u "$USER" -x ferese
|
||||
```
|
||||
|
||||
Replace `PID` with the affected session’s process ID and use `kill PID` to end it,
|
||||
bearing in mind that its applications will close and unsaved work may be lost. You can
|
||||
Replace `PID` with the affected session’s process ID and use `kill PID` to end it.
|
||||
Its applications will close and unsaved work may be lost. You can
|
||||
then choose another desktop at the next login.
|
||||
|
||||
### Roll back a release
|
||||
@@ -312,8 +312,8 @@ configuration; reinstalling Ferese restores the desktop session entry.
|
||||
|
||||
## Screen sharing and recording
|
||||
|
||||
Ferese’s native ScreenCast portal is included in the installation, which backs up the
|
||||
old user service override pointing to `~/.local/libexec/ferese` so new sessions use the
|
||||
installed release. Custom overrides are preserved and reported before building, and
|
||||
[Screen sharing](screen-sharing.md) covers consent, PipeWire setup, supported sources
|
||||
The installer includes Ferese’s native ScreenCast portal and backs up the old user
|
||||
service override pointing to `~/.local/libexec/ferese`, so new sessions use the
|
||||
installed release. Custom overrides are preserved and reported before building.
|
||||
See [Screen sharing](screen-sharing.md) for consent, PipeWire setup, supported sources
|
||||
and recording limits.
|
||||
+14
-14
@@ -15,9 +15,9 @@ ferese-lock --foreground # stay attached until unlock
|
||||
Do not enter your real password in a preview. The account picture comes from
|
||||
AccountsService or `~/.face`; a silhouette is used when neither is available.
|
||||
|
||||
Escape clears the password. Caps Lock is shown beside authentication status.
|
||||
Failed attempts show an error and delay retries. Authentication uses the system's
|
||||
PAM policy; both password and account validation must succeed.
|
||||
Press Escape to clear the password. The authentication status also shows whether
|
||||
Caps Lock is on. A failed attempt displays an error and delays the next retry.
|
||||
Authentication uses the system's PAM policy; both password and account validation must succeed.
|
||||
|
||||
## Automatic locking
|
||||
|
||||
@@ -46,23 +46,23 @@ lock-screen {
|
||||
}
|
||||
```
|
||||
|
||||
These delays start after locking, independently of the automatic-lock timer.
|
||||
Both delays start when the session locks, separately from the automatic-lock timer.
|
||||
Display sleep does not suspend the computer. A nested preview shows black
|
||||
instead of powering off the host display.
|
||||
|
||||
## Recovery and limits
|
||||
|
||||
The lock covers all displays, including newly connected ones. If the lock UI
|
||||
crashes, the compositor keeps the session protected and permits a replacement
|
||||
locker to take over. A running locker cannot be replaced. Launch `ferese-lock`
|
||||
with the affected session's Wayland environment to recover; ending the session
|
||||
from another TTY remains an option (see [Recovery](installation.md#logout-and-recovery)).
|
||||
The lock covers all displays, including displays connected after locking. If the
|
||||
lock UI crashes, the compositor keeps the session protected and allows a replacement
|
||||
locker to take over. A running locker cannot be replaced. To recover, launch
|
||||
`ferese-lock` with the affected session's Wayland environment. You can also end the
|
||||
session from another TTY; see [Recovery](installation.md#logout-and-recovery).
|
||||
|
||||
Readiness is reported only after protocol confirmation: every connected output
|
||||
has presented protected content, or there are no outputs. The pinned Iced runtime
|
||||
also emits a synthetic `Locked` event when making the request. The locker retains
|
||||
its two-event guard until upstream distinguishes request initiation from protocol
|
||||
confirmation; dependency upgrades must re-audit this workaround.
|
||||
The locker reports readiness only after protocol confirmation. At that point,
|
||||
every connected output has presented protected content, or there are no outputs.
|
||||
The pinned Iced runtime also emits a synthetic `Locked` event when it sends the
|
||||
request. The locker keeps a two-event guard until upstream separates that event
|
||||
from protocol confirmation. Dependency upgrades must re-audit this workaround.
|
||||
|
||||
Password messages use zeroizing storage. Avatar files are limited to 8 MiB,
|
||||
4096 pixels per dimension, and a 32 MiB decoding budget. The clock updates at
|
||||
|
||||
+11
-12
@@ -1,13 +1,12 @@
|
||||
# Native-client soak testing
|
||||
|
||||
The soak runner repeatedly creates and destroys native Wayland clients while
|
||||
exercising focus, resize, column width, fullscreen, floating, and workspace
|
||||
paths. Every tenth iteration also terminates a client abruptly. If a local
|
||||
malformed-client probe is available, it opens three isolated connections that
|
||||
send malformed Wayland messages. The runner requires
|
||||
Ferese to disconnect each malformed client and then checks that the compositor
|
||||
and authenticated IPC socket remain responsive. It also records compositor RSS
|
||||
growth.
|
||||
The soak runner repeatedly opens and closes native Wayland clients, testing focus,
|
||||
resize, column width, fullscreen, floating windows and workspace changes. Every
|
||||
tenth iteration terminates a client abruptly. When a local malformed-client probe
|
||||
is available, it sends malformed Wayland messages through three isolated connections.
|
||||
The runner requires Ferese to disconnect each malformed client, then checks that
|
||||
the compositor and authenticated IPC socket still respond. It also records
|
||||
compositor RSS growth.
|
||||
|
||||
Build `ferese` and `feresectl` and start a disposable
|
||||
[nested session](installation.md#preview-and-logs). Select its Wayland socket and
|
||||
@@ -29,10 +28,10 @@ FERESE_SOAK_SECONDS=300 \
|
||||
./scripts/soak-native.sh
|
||||
```
|
||||
|
||||
Development probes are local-only, not distributed in the Cargo workspace.
|
||||
Supply an existing executable with `FERESE_MALFORMED_CLIENT` to enable protocol
|
||||
checks. An explicitly configured missing probe is an error; without a probe,
|
||||
the runner reports that protocol checks are skipped.
|
||||
Development probes are local tools and are not distributed in the Cargo workspace.
|
||||
Set `FERESE_MALFORMED_CLIENT` to an existing executable to enable protocol checks.
|
||||
If you explicitly configure a probe that does not exist, the runner reports an
|
||||
error. Without a probe, it reports that protocol checks are skipped.
|
||||
|
||||
The local probe can also be run independently against a disposable Ferese session:
|
||||
|
||||
|
||||
@@ -9,18 +9,18 @@ WAYLAND_DEBUG=1 FERESE_TRACE_PERFORMANCE=1 \
|
||||
target/release/ferese-shell 2>/tmp/ferese-resize.log
|
||||
```
|
||||
|
||||
Use a wallpaper, drag each edge of the host window, and repeatedly maximize and
|
||||
restore it. Check that the wallpaper and bar follow without long stalls, including
|
||||
at fractional scaling.
|
||||
Set a wallpaper, then drag each edge of the host window and repeatedly maximize
|
||||
and restore it. The wallpaper and bar should resize without long stalls. Check
|
||||
this at fractional scaling too.
|
||||
|
||||
## Compare renderers
|
||||
|
||||
Repeat with `ICED_BACKEND=wgpu` and `ICED_BACKEND=tiny-skia`. The shell enables
|
||||
wgpu; software fallback can be slower when resampling wallpaper.
|
||||
|
||||
Trace the whole sequence: host resize, layer configure, client acknowledgement,
|
||||
new buffer commit, then compositor rendering. A quick acknowledgement does not
|
||||
mean the client has finished drawing. `FERESE_TRACE_PERFORMANCE` measures compositor
|
||||
Follow the trace from host resize through layer configure, client acknowledgement,
|
||||
new buffer commit and compositor rendering. A quick acknowledgement does not mean
|
||||
the client has finished drawing. `FERESE_TRACE_PERFORMANCE` measures compositor
|
||||
work, not shell rasterization.
|
||||
|
||||
## Historical check
|
||||
@@ -28,8 +28,8 @@ work, not shell rasterization.
|
||||
A KDE Wayland check at 175% scale used debug binaries and protocol tracing.
|
||||
Median configure acknowledgement was 1.35 ms with tiny-skia and 2.27 ms with
|
||||
wgpu. Wallpaper buffer intervals were 5919 ms with tiny-skia (only two buffers)
|
||||
and 9.85 ms median with wgpu. Capture durations differed, so these are diagnostic
|
||||
observations rather than throughput benchmarks. GPU intervals also had stalls
|
||||
and 9.85 ms median with wgpu. The captures had different durations, so these
|
||||
observations do not establish comparative throughput. GPU intervals also had stalls
|
||||
up to about 200 ms.
|
||||
|
||||
Repeat on the current build. A nested result does not establish direct-session
|
||||
|
||||
@@ -13,13 +13,13 @@ FERESE_TRACE_PERFORMANCE=1 target/release/ferese --backend nested \
|
||||
--grant-effects --grant-shell-control -- target/release/ferese-shell
|
||||
```
|
||||
|
||||
Compare idle, several windows, overview, Settings navigation, translucent
|
||||
popovers, and screen capture separately. Allow startup to settle and repeat each
|
||||
sample. Record process CPU, child-process CPU, RSS, render attempts, and damaged
|
||||
frames. Keep build work and unrelated activity outside the sampling interval.
|
||||
Measure idle, several windows, overview, Settings navigation, translucent popovers
|
||||
and screen capture separately. Wait for startup to settle, then repeat each sample.
|
||||
Record process CPU, child-process CPU, RSS, render attempts and damaged frames.
|
||||
Do not build or run unrelated workloads during the sample.
|
||||
|
||||
CPU percentages below use one core as 100%. Short samples are observations,
|
||||
not guarantees or hardware-session benchmarks.
|
||||
CPU percentages below use one core as 100%. These short samples describe observed
|
||||
behavior; they are not guarantees or hardware-session benchmarks.
|
||||
|
||||
## Direct frame timing
|
||||
|
||||
@@ -33,11 +33,11 @@ For a direct session, enable `FERESE_TRACE_PERFORMANCE=1` and
|
||||
`RUST_LOG=ferese::render=debug` before starting Ferese. The timing records include
|
||||
the planned render start, actual render start, timer lateness, presentation
|
||||
target, DRM presentation timestamp, and request-to-presentation duration.
|
||||
Missed deadlines compare submitted frames with their targets; idle gaps do not
|
||||
count. Request-to-presentation starts at the compositor's redraw request, so it
|
||||
does not include device input latency, client rendering before the request, or
|
||||
the display's pixel response. Render cost measures CPU preparation and queueing;
|
||||
asynchronous GPU work is covered conservatively by feedback-driven margins.
|
||||
Missed deadlines are counted against submitted frames' presentation targets;
|
||||
idle gaps do not count. Request-to-presentation timing starts at the compositor's
|
||||
redraw request. It does not include device input latency, client rendering before
|
||||
the request or the display's pixel response. Render cost measures CPU preparation
|
||||
and queueing. Feedback-driven margins allow conservatively for asynchronous GPU work.
|
||||
|
||||
Check sustained animation, idle wakeup, callback-only clients, and mixed-refresh
|
||||
outputs separately. Nested sessions do not exercise the DRM scheduler.
|
||||
@@ -52,23 +52,22 @@ while a render timer was scheduled or a frame was in flight. Compare these with
|
||||
coalesce and are not themselves rendered frames.
|
||||
|
||||
`animation fallback scheduling` reports watchdog arms, cancellations, wakeups,
|
||||
recovery requests and observations of animations with an intact normal frame
|
||||
chain. Summaries are emitted during redraw activity every five seconds and on
|
||||
normal exit. The fallback counters reset with each summary. An orphaned animation
|
||||
gets a watchdog deadline two refresh intervals after its own output loses its
|
||||
frame chain. Recovery also retains a requested final frame if another output
|
||||
settles that animation while scheduling is unavailable. Idle, powered-off and
|
||||
disconnected outputs do not set that deadline.
|
||||
An already scheduled render or pending page flip suppresses the watchdog; this
|
||||
policy does not replace DRM error recovery or diagnose a permanently lost flip.
|
||||
recovery requests and animations whose normal frame chain is intact. Ferese emits
|
||||
summaries every five seconds during redraw activity and on normal exit, resetting
|
||||
the fallback counters each time. When an animation loses its output's frame chain,
|
||||
the watchdog deadline is two refresh intervals later. Recovery keeps a requested
|
||||
final frame even if another output settles the animation while scheduling is
|
||||
unavailable. Idle, powered-off and disconnected outputs do not set that deadline.
|
||||
The watchdog is suppressed when a render is already scheduled or a page flip is
|
||||
pending. It does not replace DRM error recovery or diagnose a permanently lost flip.
|
||||
|
||||
The regression replays use a 60 Hz animation beside an idle 240 Hz output.
|
||||
The old fallback rule produces 60 unnecessary wakes in one simulated second;
|
||||
the new rule produces zero while the normal chain remains intact. Three cursor
|
||||
moves within one output require three output requests rather than the old six.
|
||||
These are deterministic scheduling counts, not live DRM CPU, latency or battery
|
||||
measurements. Verify those separately with the same hardware workload before
|
||||
making claims about power savings.
|
||||
These counts come from deterministic scheduling replays. They do not measure live
|
||||
DRM CPU use, latency or battery consumption. Measure those separately with the same
|
||||
hardware workload before claiming power savings.
|
||||
|
||||
## Settled overview damage
|
||||
|
||||
@@ -79,8 +78,8 @@ Intel Core Ultra 7 258V and Mesa 26.2.3. Ten-second process samples measured
|
||||
removing forced full damage from unchanged rounded thumbnails.
|
||||
|
||||
A settled five-second interval changed from 300 damaged frames to zero.
|
||||
The nested backend still makes about 300 no-damage render attempts per interval;
|
||||
this change avoids unchanged submissions rather than changing nested scheduling.
|
||||
The nested backend still makes about 300 no-damage render attempts per interval.
|
||||
The change skips unchanged submissions; it does not alter nested scheduling.
|
||||
These short samples exclude host compositor CPU and do not measure battery
|
||||
discharge or direct DRM performance.
|
||||
|
||||
@@ -115,8 +114,8 @@ cached reading; the existing `wpctl` reader preserves volume and device semantic
|
||||
Disconnected subscriptions retain bounded polling, and missing sinks retry.
|
||||
Brightness and other status polling remain unchanged.
|
||||
|
||||
These are short nested observations, exclude the host compositor, and do not
|
||||
measure battery discharge. Raw measurements and profiles were saved locally in
|
||||
These short nested samples exclude the host compositor and do not measure battery
|
||||
discharge. Raw measurements and profiles were saved locally in
|
||||
`/tmp/ferese-shell-profile-20261002`.
|
||||
|
||||
The subscription regression starts its own PipeWire server, changes default
|
||||
|
||||
+12
-11
@@ -1,8 +1,8 @@
|
||||
# Desktop portals
|
||||
|
||||
Desktop portals let applications request screen sharing, screenshots, wallpaper
|
||||
changes, and other desktop services. Ferese provides themed consent dialogs;
|
||||
GTK supplies file, print, and other standard dialogs.
|
||||
Applications use desktop portals to request screen sharing, screenshots, wallpaper
|
||||
changes and other desktop services. Ferese supplies themed consent dialogs, while
|
||||
GTK handles file, print and other standard dialogs.
|
||||
|
||||
Install `xdg-desktop-portal`, `xdg-desktop-portal-gtk`, and Ferese's backend through
|
||||
[Installation](installation.md). The session launcher starts the services with
|
||||
@@ -29,23 +29,24 @@ This does not affect ordinary application clipboard use.
|
||||
|
||||
## Consent and capture
|
||||
|
||||
Screenshot and screen-sharing requests ask for approval. Screen sharing can
|
||||
remember display permissions when the application requests it and the user opts
|
||||
in. Window sharing always asks again. See [Screen sharing](screen-sharing.md).
|
||||
Screenshot and screen-sharing requests need approval. Display-sharing permissions
|
||||
can be remembered when the application requests it and the user opts in. Window
|
||||
sharing always asks again. See [Screen sharing](screen-sharing.md).
|
||||
Window captures contain the selected app and its subsurfaces; separate popups,
|
||||
other apps, shell layers, and compositor decorations are excluded.
|
||||
|
||||
InputCapture starts at an approved display-edge barrier. **Ctrl+Alt+Escape**
|
||||
returns local control. Locking, disconnecting the receiver, or changing displays
|
||||
or the keyboard layout stops capture. Touch and remembered InputCapture grants
|
||||
are not supported. InputCapture forwards local input; it does not inject remote input.
|
||||
InputCapture starts at an approved barrier at the edge of a display. Press
|
||||
**Ctrl+Alt+Escape** to regain local control. Capture stops when you lock the session,
|
||||
disconnect the receiver, change displays or change the keyboard layout. Touch and
|
||||
remembered InputCapture grants are not supported. InputCapture forwards local
|
||||
input; it does not inject remote input.
|
||||
|
||||
Wallpaper approval copies the image into Ferese's data directory and updates the
|
||||
config. Set `theme.background.lock-path` for a separate lock-screen image; otherwise
|
||||
it follows the desktop wallpaper.
|
||||
|
||||
Global shortcuts cannot replace Ferese bindings or reserved escape/console keys.
|
||||
They stop when the app session closes and never activate on the lock screen.
|
||||
They stop when the app session closes. They never activate on the lock screen.
|
||||
Power confirmations show app inhibitors before proceeding. Ferese has no
|
||||
user-switch operation.
|
||||
|
||||
|
||||
+14
-13
@@ -10,9 +10,9 @@ portal and PipeWire dependencies.
|
||||
2. Select a monitor and click **Share**.
|
||||
3. Click the stop square to finish.
|
||||
|
||||
Videos are saved as VP8 WebM files in your XDG Videos folder under `Ferese`.
|
||||
A notification shows the saved path. Audio and region recording are not supported
|
||||
by the built-in recorder; other recording apps can handle audio separately.
|
||||
The recorder saves VP8 WebM files under `Ferese` in your XDG Videos folder, then
|
||||
shows the path in a notification. The built-in recorder does not support audio or
|
||||
region recording; other recording apps can handle audio separately.
|
||||
If recording fails, a notification reports the error and any unfinished
|
||||
`.webm.part` file.
|
||||
|
||||
@@ -23,18 +23,19 @@ choose a display or window and click **Share**. Nothing is selected initially.
|
||||
Apps requesting multiple sources can select up to eight.
|
||||
|
||||
A shared display includes everything visible on it, including notifications.
|
||||
A shared window includes only that app's content and subsurfaces, even when
|
||||
covered or on another workspace. Separate popups and compositor decorations are
|
||||
excluded. Resizing a shared window updates its video size; closing it ends sharing.
|
||||
Window sharing captures only the selected app's content and subsurfaces, even if
|
||||
the window is covered or on another workspace. It excludes separate popups and
|
||||
compositor decorations. The video size follows window resizes; closing the window
|
||||
ends sharing.
|
||||
|
||||
The picker follows your shell colors, font, corners, opacity, and blur.
|
||||
|
||||
## Stop sharing
|
||||
|
||||
Click **Stop sharing** in the sharing window, or close that window. The built-in
|
||||
recorder uses the top-bar stop button instead. Sharing also ends when the app
|
||||
closes or Ferese locks. Disconnecting a shared monitor or changing its capture
|
||||
size ends its stream; start sharing again afterward.
|
||||
Click **Stop sharing** or close the sharing window. For the built-in recorder,
|
||||
use the stop button in the top bar. Sharing also ends when the app closes or
|
||||
Ferese locks. If you disconnect a shared monitor or change its capture size,
|
||||
its stream ends and you need to start sharing again.
|
||||
|
||||
## Remember permissions
|
||||
|
||||
@@ -55,9 +56,9 @@ see the [package lists](installation.md#requirements).
|
||||
The installer supplies Ferese's portal backend and selects it for screen sharing.
|
||||
Log into a new Ferese session after installation.
|
||||
|
||||
Streams run at up to 30 fps and support hidden or embedded cursors. Capture copies
|
||||
frames through CPU-accessible buffers, so large or multiple streams can use
|
||||
substantial CPU and memory bandwidth.
|
||||
Streams run at up to 30 fps with hidden or embedded cursors. Frames are copied
|
||||
through CPU-accessible buffers. Large streams or several simultaneous streams
|
||||
can therefore use substantial CPU and memory bandwidth.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
|
||||
+3
-3
@@ -1,6 +1,6 @@
|
||||
# Screenshots
|
||||
|
||||
Captured on September 30, 2026. Select an image to view it at full size.
|
||||
These screenshots were taken on September 30, 2026. Click an image to open it at full size.
|
||||
|
||||
## Ferese Blue
|
||||
|
||||
@@ -22,7 +22,7 @@ Windows and workspaces over a custom wallpaper.
|
||||
|
||||
## Power controls
|
||||
|
||||
Power profiles and restart, power off and suspend actions.
|
||||
Power controls for selecting a profile, restarting, powering off and suspending.
|
||||
|
||||
[](images/screenshots/power-controls.png)
|
||||
|
||||
@@ -34,7 +34,7 @@ Application previews and workspace selection.
|
||||
|
||||
## Shortcut guide
|
||||
|
||||
The login guide shows the configured keyboard shortcuts.
|
||||
The shortcut guide displayed at login, using the configured keyboard shortcuts.
|
||||
|
||||
[](images/screenshots/shortcut-guide.png)
|
||||
|
||||
|
||||
+44
-2
@@ -3,6 +3,8 @@
|
||||
`Super` is usually the Windows key. These are the built-in defaults. Open
|
||||
**Settings → Shortcuts** to change bindings and gestures or disable the login
|
||||
guide. Your saved bindings can override these defaults.
|
||||
The [example config](../packaging/config.kdl) adds the app, media and arrow-key
|
||||
shortcuts listed below.
|
||||
|
||||
## Move and resize with the mouse
|
||||
|
||||
@@ -25,6 +27,9 @@ to nearby edges; continuing to drag beyond 20 logical pixels releases the snap.
|
||||
| Shortcut | Action |
|
||||
| --- | --- |
|
||||
| Super + H / J / K / L | Focus in that direction |
|
||||
| Super + Backspace | Return to the last focused window, including on another workspace or monitor |
|
||||
| Alt + Tab | Preview recent windows in focus order |
|
||||
| Alt + Shift + Tab | Preview recent windows in reverse focus order |
|
||||
| Super + Shift + H / J / K / L | Move the focused window in that direction |
|
||||
| Super + Ctrl + H / J / K / L | Resize in that direction |
|
||||
| Super + Q | Close the focused window |
|
||||
@@ -34,6 +39,10 @@ to nearby edges; continuing to drag beyond 20 logical pixels releases the snap.
|
||||
Maximize fills the available workspace. Fullscreen also hides the bar and window
|
||||
decorations.
|
||||
|
||||
Keep Alt held to cycle through recent windows. Release Alt to select the previewed
|
||||
window, or press Escape to cancel. Repeating Super + Backspace toggles between the
|
||||
two most recently focused windows.
|
||||
|
||||
## Columns and layouts
|
||||
|
||||
| Shortcut | Action |
|
||||
@@ -61,8 +70,8 @@ overview.
|
||||
| Super + Shift + 1–9 | Move the window to that workspace |
|
||||
| Super + Escape | Toggle between the last two visited workspaces on this monitor |
|
||||
|
||||
Workspaces are created as needed. Selecting one visible on another monitor focuses
|
||||
that monitor.
|
||||
Workspaces are created as needed and numbered separately on each monitor.
|
||||
Workspace shortcuts select a workspace on the focused monitor.
|
||||
|
||||
To make pressing the current workspace's shortcut toggle back too, enable
|
||||
**Settings → Windows → Toggle back with the same workspace shortcut**. It is off
|
||||
@@ -99,6 +108,39 @@ Gestures can use the same actions
|
||||
as keyboard bindings, including overview or moving a window. Four- and five-finger
|
||||
bindings are supported too.
|
||||
|
||||
## Reserved and context controls
|
||||
|
||||
These controls are handled by the compositor rather than configurable bindings.
|
||||
|
||||
| Control | Action |
|
||||
| --- | --- |
|
||||
| Enter in overview | Activate the selected window |
|
||||
| Escape in overview | Close overview |
|
||||
| Escape during Alt + Tab | Cancel the preview without changing focus |
|
||||
| Release Alt during Alt + Tab | Focus the previewed window |
|
||||
| Ctrl + Alt + Escape | Release an active shortcut inhibitor or input-capture session |
|
||||
| Ctrl + Alt + F1–F12 | Switch virtual terminals in a direct session |
|
||||
|
||||
Virtual-terminal switching is unavailable in nested previews.
|
||||
|
||||
## Example-config shortcuts
|
||||
|
||||
The [example config](../packaging/config.kdl) adds these to the built-in defaults.
|
||||
App and hardware controls require their configured programs to be installed.
|
||||
|
||||
| Shortcut | Action |
|
||||
| --- | --- |
|
||||
| Super + B | Open Firefox |
|
||||
| Super + Z | Open Zed |
|
||||
| Super + Alt + L | Lock with `ferese-lock` |
|
||||
| Super + Left / Down / Up / Right | Focus in that direction |
|
||||
| Super + Ctrl + Left / Down / Up / Right | Move the focused window in that direction |
|
||||
| Super + Alt + Left / Down / Up / Right | Resize in that direction |
|
||||
| Brightness up / down | Adjust brightness with `brightnessctl` |
|
||||
| Volume up / down | Adjust volume with `wpctl` |
|
||||
| Audio mute | Toggle output mute with `wpctl` |
|
||||
| Microphone mute | Toggle microphone mute with `wpctl` |
|
||||
|
||||
## Add a shortcut
|
||||
|
||||
For example, bind a lock command and use a swipe to open overview:
|
||||
|
||||
+5
-6
@@ -1,17 +1,16 @@
|
||||
# Why Ferese
|
||||
|
||||
Most Wayland desktops are assembled from separate programs such as a compositor, a bar, a notification daemon, a launcher, a lock screen with each having its own config and its own idea of how things should look. Ferese is built as one desktop. Window management and the shell share a single configuration, so personalizing it means changing one thing, not five.
|
||||
Most Wayland desktops are assembled from separate programs: a compositor, a bar, a notification daemon, a launcher and a lock screen, each with its own config and appearance settings. Ferese's window manager and shell share a single configuration.
|
||||
|
||||
## Choose how windows fit
|
||||
## Window layouts
|
||||
|
||||
Keep windows at useful widths and move through them horizontally with scrolling columns,
|
||||
divide the screen into nested splits with tree tiling, or let individual windows float
|
||||
alongside either layout. When you want to see how everything fits together, overview
|
||||
brings your windows and workspaces into view.
|
||||
alongside either layout. Overview shows your windows and workspaces together.
|
||||
|
||||
|
||||
|
||||
## Change the desktop together
|
||||
## Appearance
|
||||
|
||||
Choose a theme in Settings and build on it with your own wallpaper, colors, font,
|
||||
corners and motion, with changes applying across the desktop as you make them. Window
|
||||
@@ -29,6 +28,6 @@ theme {
|
||||
}
|
||||
```
|
||||
|
||||
Explore [Configuration](configuration.md) for everything you can change, or follow
|
||||
See [Configuration](configuration.md) for available settings, or follow
|
||||
[Installation](installation.md) to try Ferese inside your current desktop with a nested
|
||||
preview.
|
||||
+5
-7
@@ -1,8 +1,7 @@
|
||||
# Ferese website and handbook
|
||||
|
||||
The website introduces Ferese as one desktop you can make your own, with a handbook
|
||||
built from the project’s Markdown guides so the website and repository share the same
|
||||
documentation.
|
||||
The website's handbook is built from the project's Markdown guides, so the website
|
||||
and repository share the same documentation.
|
||||
|
||||
## Local preview
|
||||
|
||||
@@ -14,8 +13,7 @@ python3 -m http.server 8080 --bind 127.0.0.1 --directory build/site
|
||||
```
|
||||
|
||||
Open http://localhost:8080 for the homepage or http://localhost:8080/docs/ for the
|
||||
handbook, then rebuild and refresh the browser whenever you change the site sources or
|
||||
guides.
|
||||
handbook. Rebuild and refresh the browser after changing the site sources or guides.
|
||||
|
||||
- `site/index.html` and `site/styles.css`: homepage and shared visual design.
|
||||
- `site/content/index.md`: handbook introduction.
|
||||
@@ -28,8 +26,8 @@ guides.
|
||||
## GitHub Pages
|
||||
|
||||
Choose **Settings → Pages → Source → GitHub Actions** to publish through the Pages
|
||||
workflow, which runs when site or documentation changes reach `main` and can also be
|
||||
started manually. The expected address is https://ferese-wm.github.io/ferese/.
|
||||
workflow. It runs when site or documentation changes reach `main`; you can also
|
||||
start it manually. The expected address is https://ferese-wm.github.io/ferese/.
|
||||
|
||||
The site uses relative links, including for handbook search, so it also works under the
|
||||
`/ferese/` project path. Each build copies screenshots from `docs/images` into
|
||||
|
||||
@@ -1,11 +1,10 @@
|
||||
# Ferese handbook
|
||||
|
||||
Ferese is a window manager and desktop shell built together and configured in one place,
|
||||
for people who want their desktop to be their own. This handbook helps you get settled,
|
||||
shape the desktop around the way you work and understand what you can change.
|
||||
Ferese combines a window manager and desktop shell with one configuration.
|
||||
This handbook covers installation, settings and desktop controls.
|
||||
|
||||
[Browse screenshots](screenshots.md) to see the themes, layouts and desktop controls in
|
||||
use
|
||||
use.
|
||||
|
||||
## Get started
|
||||
|
||||
@@ -44,9 +43,8 @@ group windows, resize them and move between workspaces.
|
||||
- [Screen sharing and recording](screen-sharing.md): share an app or display, or save a video.
|
||||
- [Desktop portals](portals.md): integration with applications.
|
||||
|
||||
Personalize the desktop in Settings or edit `~/.config/ferese/config.kdl` directly, with
|
||||
changes applying live and the last working configuration staying in place if an edit is
|
||||
invalid.
|
||||
Configure the desktop in Settings or edit `~/.config/ferese/config.kdl` directly.
|
||||
Changes apply live. Invalid edits leave the last working configuration in place.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
@@ -54,6 +52,6 @@ If you need to end a session, `feresectl request-logout` asks for confirmation a
|
||||
`feresectl exit` exits immediately, so save your work first. The [logs and recovery
|
||||
guide](installation.md#logout-and-recovery) helps when something stops responding.
|
||||
|
||||
You can [report a problem](https://github.com/ferese-wm/ferese/issues) with the steps to
|
||||
To [report a problem](https://github.com/ferese-wm/ferese/issues), include the steps to
|
||||
reproduce it, relevant logs and whether you were using a nested preview or a direct
|
||||
session, or start with [Development](development.md) if you’d like to contribute.
|
||||
session. See [Development](development.md) to contribute.
|
||||
+10
-12
@@ -5,9 +5,9 @@
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<meta name="theme-color" content="#10151c" />
|
||||
<meta name="description" content="Ferese is a Wayland desktop built around personalization." />
|
||||
<meta name="description" content="Ferese is a configurable Wayland desktop." />
|
||||
<meta property="og:title" content="Ferese — Wayland desktop" />
|
||||
<meta property="og:description" content="A Wayland desktop built around personalization." />
|
||||
<meta property="og:description" content="A configurable Wayland desktop." />
|
||||
<meta property="og:type" content="website" />
|
||||
<meta property="og:image" content="https://ferese-wm.github.io/ferese/assets/screenshots/ferese-main-hero.png" />
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
@@ -36,12 +36,11 @@
|
||||
<main id="main" class="simple-home">
|
||||
<section class="product-intro page-width">
|
||||
<h1 class="product-tagline">
|
||||
A Wayland desktop built around personalization.
|
||||
A configurable Wayland desktop.
|
||||
</h1>
|
||||
<p class="product-description">
|
||||
Ferese is a window manager and desktop shell
|
||||
built together and configured in one place,
|
||||
for people who want their desktop to be their own.
|
||||
Ferese combines a window manager and desktop shell
|
||||
with one configuration.
|
||||
</p>
|
||||
<div class="product-links">
|
||||
<a class="button" href="docs/installation.html">Install Ferese</a>
|
||||
@@ -64,7 +63,7 @@
|
||||
</figure>
|
||||
<section class="product-features page-width" aria-label="Features">
|
||||
<article>
|
||||
<h2>Flexible layouts</h2>
|
||||
<h2>Window layouts</h2>
|
||||
<p>
|
||||
Scrolling columns, tree tiling, floating windows, and a workspace
|
||||
overview. Use keyboard shortcuts or gestures to move around.
|
||||
@@ -72,15 +71,14 @@
|
||||
<a href="docs/configuration.html#layout">Configure layouts →</a>
|
||||
</article>
|
||||
<article>
|
||||
<h2>A native desktop</h2>
|
||||
<h2>Desktop tools</h2>
|
||||
<p>
|
||||
A menu bar, Control Center, Settings, notifications, and desktop
|
||||
widgets, designed to work together.
|
||||
A menu bar, Control Center, Settings, notifications, and desktop widgets.
|
||||
</p>
|
||||
<a href="docs/why-ferese.html">Explore Ferese →</a>
|
||||
</article>
|
||||
<article>
|
||||
<h2>Make it yours</h2>
|
||||
<h2>Appearance</h2>
|
||||
<p>
|
||||
Choose your theme, wallpaper, colors, and motion. Change settings
|
||||
through the app or a KDL config, with live reload.
|
||||
@@ -118,4 +116,4 @@
|
||||
</footer>
|
||||
</body>
|
||||
|
||||
</html>
|
||||
</html>
|
||||
Reference in new issue
Block a user