aria/feresaria
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add desktop widgets and streamline documentation

Browse Source
This commit is contained in:
Samuel Onoja committed 2026-09-26 22:53:51 +01:00
1 parent c63af64d87
commit 8dc895448d
25 files changed
+2724 -3686
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/installation.md
+29 -54
View File
@@ -1,73 +1,48 @@
# Fedora / SDDM installation
# Installation
From the checkout, run the installer as your normal user:
## Build and install
On Fedora with SDDM, install a Rust toolchain (1.93 or newer), native build
dependencies, `desktop-file-utils`, D-Bus and `foot`. Wallpaper browsing also
needs `zenity`; locking needs swaylock or swaylock-effects.
From the checkout, run as your normal user:
```sh
./scripts/install.sh
```
It builds all four release binaries with the locked dependencies, then uses
`sudo` (or `pkexec`) for installation. Install the Rust toolchain, native build
dependencies, `desktop-file-utils`, and D-Bus first. Cargo reports missing native
libraries during the build. The shell requires Rust 1.93 or newer.
Useful options:
The script builds locked release binaries, then requests elevation to install.
It preserves your configuration and other desktop sessions. Log out and select
**Ferese** at the login screen. Upgrades require logging out and back in too.
```sh
./scripts/install.sh --dry-run
./scripts/install.sh --offline --release-id my-demo
./scripts/install.sh --skip-build --release-id existing-build
./scripts/install.sh --offline --release-id my-build
./scripts/install.sh --skip-build
```
The script works from any directory and preserves your user configuration.
Use `--help` for all options. To test and install manually:
Use `--help` for all options. New configs can be copied from
`/usr/local/lib/ferese/current/config.example.toml` to
`~/.config/ferese/config.toml`. See [Configuration](configuration.md).
```sh
cargo test -p ferese -p feresectl -p ferese-animation -p ferese-core -p ferese-layout -p ferese-shell -p ferese-settings --locked
cargo build --release --locked -p ferese -p ferese-shell -p ferese-settings -p feresectl
sudo bash scripts/install-session.sh YOUR_RELEASE_ID
```
## Preview and logs
The installer adds **Ferese** to SDDM without changing Plasma or
the default session. It installs immutable, versioned directories in
`/usr/local/lib/ferese/releases/` and launchers in `/usr/local/bin/`.
`current` selects the installed build; `previous` records the prior selection
on upgrades. Installation refuses to replace unmanaged launchers/session files.
Run `ferese-session --nested` inside an existing Wayland desktop. For a hardware
session, use the login screen or a spare TTY; never run Ferese as root or start
its DRM backend inside an active graphical session.
Keep your existing `~/.config/ferese/config.toml`. For a new configuration, copy
`/usr/local/lib/ferese/current/config.example.toml` there. The existing compositor
defaults handle connected monitors automatically; add output profiles only after
checking `feresectl get-outputs` on the actual DRM session.
Use `ferese-session --nested` for an installed-build preview. Log out of Plasma
and select Ferese in SDDM for real hardware use. `ferese-session` can also run
from a spare logged-in TTY. It must run as your normal user, never as root.
Foot and `dbus-run-session` must be installed.
Session logs are written under `${XDG_STATE_HOME:-~/.local/state}/ferese/`.
The launcher sets Wayland desktop variables, starts D-Bus if none is available,
and grants shell capabilities only to the compositor-launched shell process.
It does not enable public screencopy, privileged input methods, or shortcut
inhibition by default.
Logs are stored in `${XDG_STATE_HOME:-~/.local/state}/ferese/`. Keep an existing
desktop available while testing scaling, monitor hotplug, suspend and locking.
## Logout and recovery
Save your work, then press **Super+Shift+E** or run `feresectl exit` to log out.
Ferese stops its event loop and terminates its shell child during shutdown.
This is immediate logout, without a save-confirmation dialog.
Save your work before **Super+Shift+E** or `feresectl exit`: logout is immediate.
If frozen, switch to another TTY with Ctrl+Alt+F1–F12, terminate the specific
Ferese process, and select your other desktop on the next login. Restarting SDDM
also ends other sessions, so avoid it with unsaved work.
If the compositor becomes unresponsive, switch to another TTY using
Ctrl+Alt+F1–F12 and terminate that specific Ferese process. Select Plasma on the
next login. Do not restart SDDM while a desktop contains unsaved work.
For a binary rollback, inspect `/usr/local/lib/ferese/previous` and select that
release with the `current` symlink while Ferese is stopped. Existing releases
are retained. To hide the login option, move
Installed binaries live in `/usr/local/lib/ferese/releases/`. While Ferese is
stopped, select a retained release with the `current` symlink; `previous` points
to the prior installation. To hide the session option, move
`/usr/share/wayland-sessions/ferese.desktop` out of that directory.
## First hardware session
Verify terminal/editor/browser, clipboard, fullscreen, fractional scaling,
monitor disconnect/reconnect, VT switching away/back, and logout. Suspend/resume
and session locking are not certified by the nested smoke test. Keep Plasma
available until real development sessions and these checks pass.