Document full installation and update links for ferese-wm
This commit is contained in:
Samuel Onoja committed
1 parent
f8b8704f8b
commit
0295b5be3e
6 files changed
+291
-50
No files matched your search
@@ -45,22 +45,26 @@ rules, displays, widgets and login items are configurable too. Start with the
|
||||
|
||||
## Install
|
||||
|
||||
The current installation guide covers Fedora with SDDM. After installing the
|
||||
[prerequisites](docs/installation.md), run:
|
||||
Install Ferese on Linux with any Wayland-capable login manager, a command-based
|
||||
greeter, or a local TTY. Start with the [installation guide](docs/installation.md)
|
||||
for system dependencies and Rust 1.95 or newer, then build as your normal user:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/ferese-wm/ferese.git
|
||||
cd ferese
|
||||
./scripts/install.sh
|
||||
```
|
||||
|
||||
Log out, select **Ferese** at the login screen, and sign in. The installer keeps
|
||||
your configuration and the previous release for rollback. See
|
||||
[installation and recovery](docs/installation.md) for the full setup and safety
|
||||
notes.
|
||||
Log out and select **Ferese** at your login screen. For greeters that take a
|
||||
session command, use `/usr/local/bin/ferese-session`. The installer preserves
|
||||
your configuration and other sessions, and retains the previous release for
|
||||
rollback. The guide covers [all startup methods](docs/installation.md#start-a-session),
|
||||
optional tools, updates, and recovery.
|
||||
|
||||
To preview Ferese inside your current Wayland desktop instead:
|
||||
|
||||
```sh
|
||||
cargo build --release --locked -p ferese -p ferese-shell -p ferese-settings -p feresectl
|
||||
cargo build --release --locked -p ferese -p ferese-shell -p ferese-settings -p feresectl -p ferese-lock
|
||||
target/release/ferese --backend nested --grant-effects --grant-shell-control -- \
|
||||
target/release/ferese-shell
|
||||
```
|
||||
@@ -87,6 +91,7 @@ Settings → Shortcuts** to change them or assign gestures to other actions.
|
||||
- [Configuration reference](docs/configuration.md)
|
||||
- [Desktop widgets](docs/desktop-widgets.md)
|
||||
- [Notifications](docs/notifications.md)
|
||||
- [Native locker](docs/locking.md)
|
||||
|
||||
## Development
|
||||
|
||||
|
||||
+267
-34
@@ -1,35 +1,201 @@
|
||||
# Installation
|
||||
|
||||
Ferese runs on Linux and installs as a standalone Wayland session. Use any login
|
||||
manager that can launch Wayland sessions, a command-based greeter, or a local
|
||||
TTY. You do not need to replace your existing login manager or desktop.
|
||||
|
||||
## Requirements
|
||||
|
||||
You need a working graphics driver with DRM/KMS and EGL support, an authenticated
|
||||
local login session with seat access through logind or seatd, D-Bus, and
|
||||
Linux-PAM for the native locker. A nested preview needs an existing Wayland
|
||||
desktop instead of direct access to the graphics device.
|
||||
|
||||
Build with **Rust 1.95 or newer**, a C/C++ toolchain, CMake, pkg-config, and the
|
||||
native development libraries below. The installer builds Ferese, its shell,
|
||||
Settings, command-line tools, and locker together. It does not install system
|
||||
packages or enable services for you.
|
||||
|
||||
### Fedora
|
||||
|
||||
```sh
|
||||
sudo dnf install git curl gcc gcc-c++ make cmake pkgconf-pkg-config \
|
||||
wayland-devel libxkbcommon-devel libinput-devel systemd-devel libseat-devel \
|
||||
mesa-libgbm-devel mesa-libEGL-devel libdrm-devel fontconfig-devel \
|
||||
freetype-devel expat-devel dbus-daemon dbus-tools desktop-file-utils foot pam
|
||||
```
|
||||
|
||||
### Arch Linux
|
||||
|
||||
```sh
|
||||
sudo pacman -S --needed base-devel git curl cmake pkgconf wayland libxkbcommon \
|
||||
libinput systemd seatd mesa libdrm fontconfig freetype2 expat dbus \
|
||||
desktop-file-utils foot pam
|
||||
```
|
||||
|
||||
### Debian and Ubuntu
|
||||
|
||||
```sh
|
||||
sudo apt update
|
||||
sudo apt install build-essential git curl cmake pkg-config libwayland-dev \
|
||||
libxkbcommon-dev libinput-dev libudev-dev libseat-dev libgbm-dev libegl-dev \
|
||||
libdrm-dev libfontconfig1-dev libfreetype-dev libexpat1-dev dbus-bin \
|
||||
dbus-user-session desktop-file-utils foot libpam0g
|
||||
```
|
||||
|
||||
These are package recipes, not a claim that every distribution release has been
|
||||
tested. Fedora is the currently exercised installation path. Older releases
|
||||
may need newer packages or additional repositories. For other distributions,
|
||||
install the equivalent libraries; see the upstream
|
||||
[Smithay dependencies](https://github.com/Smithay/smithay#system-dependencies).
|
||||
|
||||
### Rust toolchain
|
||||
|
||||
Check your toolchain:
|
||||
|
||||
```sh
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
If Rust is missing, install it using the instructions at
|
||||
[rustup.rs](https://rustup.rs/), then reopen your terminal. With rustup installed,
|
||||
you can select the required version for this checkout after cloning:
|
||||
|
||||
```sh
|
||||
rustup toolchain install 1.95.0
|
||||
rustup override set 1.95.0
|
||||
```
|
||||
|
||||
## Build and install
|
||||
|
||||
On Fedora with SDDM, install a Rust toolchain (1.95 or newer), native build
|
||||
dependencies, `desktop-file-utils`, D-Bus and `foot`. Wallpaper browsing also
|
||||
needs `zenity`; locking needs swaylock or swaylock-effects.
|
||||
Screenshots need `grim`, `slurp`, `satty`, `wl-clipboard`, and Python 3.
|
||||
Print Screen captures the active monitor; Super+Shift+S selects an area.
|
||||
Use `ferese-screenshot --all` to capture all monitors in one image.
|
||||
|
||||
Clone the repository, then run the installer as your normal user:
|
||||
Run these commands as your normal user:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/borngraced/ferese.git
|
||||
git clone https://github.com/ferese-wm/ferese.git
|
||||
cd ferese
|
||||
./scripts/install.sh
|
||||
```
|
||||
|
||||
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.
|
||||
The script builds locked release binaries, then requests administrator access
|
||||
through `sudo` or `pkexec` for installation. Do not run the whole build as root.
|
||||
The first build needs network access to fetch Rust dependencies.
|
||||
|
||||
The installer adds:
|
||||
|
||||
- Versioned releases under `/usr/local/lib/ferese/releases/`, with `current` and
|
||||
`previous` links for upgrades and rollback.
|
||||
- Commands under `/usr/local/bin/`, including `ferese-session`, `ferese-settings`,
|
||||
`feresectl`, `ferese-lock`, and `ferese-screenshot`.
|
||||
- A Wayland session entry at `/usr/share/wayland-sessions/ferese.desktop`.
|
||||
- A Settings application entry, icons, the default wallpaper, and an example config.
|
||||
- `/etc/pam.d/ferese-lock`, using your distribution's authentication stack.
|
||||
An existing administrator-supplied policy is preserved.
|
||||
|
||||
Your existing configuration and other desktop sessions are preserved. The
|
||||
installer does not change your default session or login manager.
|
||||
|
||||
### Initial configuration
|
||||
|
||||
Ferese has built-in defaults. To start from the example without replacing an
|
||||
existing config:
|
||||
|
||||
```sh
|
||||
./scripts/install.sh --dry-run
|
||||
./scripts/install.sh --offline --release-id my-build
|
||||
./scripts/install.sh --skip-build
|
||||
mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/ferese"
|
||||
if [ ! -e "${XDG_CONFIG_HOME:-$HOME/.config}/ferese/config.kdl" ]; then
|
||||
cp /usr/local/lib/ferese/current/config.example.kdl \
|
||||
"${XDG_CONFIG_HOME:-$HOME/.config}/ferese/config.kdl"
|
||||
fi
|
||||
```
|
||||
|
||||
Use `--help` for all options. New configs can be copied from
|
||||
`/usr/local/lib/ferese/current/config.example.kdl` to
|
||||
`~/.config/ferese/config.kdl`. See [Configuration](configuration.md).
|
||||
Open **Control Center → Settings** after login, or run `ferese-settings`.
|
||||
See [Configuration](configuration.md) for themes, displays, shortcuts, and startup
|
||||
applications. The default terminal shortcut uses `foot`; change the terminal
|
||||
command in Settings if you prefer another terminal.
|
||||
|
||||
## Start a session
|
||||
|
||||
### Graphical login managers
|
||||
|
||||
Save your work and log out. Open your login screen's session selector, choose
|
||||
**Ferese**, and sign in. Any manager that supports Wayland sessions and reads
|
||||
`/usr/share/wayland-sessions/` can discover the installed entry. The selector's
|
||||
location and whether it appears before or after choosing your account depend
|
||||
on the login manager.
|
||||
|
||||
If Ferese is missing, confirm that the session entry exists and its launcher is
|
||||
executable:
|
||||
|
||||
```sh
|
||||
ls -l /usr/share/wayland-sessions/ferese.desktop
|
||||
test -x /usr/local/bin/ferese-session && echo "Session launcher is ready"
|
||||
desktop-file-validate /usr/share/wayland-sessions/ferese.desktop
|
||||
```
|
||||
|
||||
Check your manager's documentation for enabling Wayland session discovery. A
|
||||
manager that only launches X11 sessions cannot start Ferese through that path;
|
||||
use a Wayland-capable greeter or the TTY method below.
|
||||
|
||||
### Command-based greeters
|
||||
|
||||
If your greeter asks for a session command instead of reading desktop files, use:
|
||||
|
||||
```sh
|
||||
/usr/local/bin/ferese-session
|
||||
```
|
||||
|
||||
For a setup such as greetd, configure that as the command launched **after user
|
||||
authentication**, using your greeter's session-command option. Preserve the
|
||||
existing authentication and greeter configuration. Do not set Ferese itself as
|
||||
the privileged greeter process. See the
|
||||
[greetd documentation](https://sr.ht/~kennylevinsen/greetd/) for your chosen frontend.
|
||||
|
||||
The launcher starts the compositor and shell together, sets the desktop
|
||||
environment variables, and starts a D-Bus session when one is not already
|
||||
available. Launch it instead of the bare compositor for a complete desktop.
|
||||
|
||||
### From a TTY
|
||||
|
||||
Log out of the graphical session, switch to a local console with
|
||||
**Ctrl+Alt+F2** (or another available function key), and sign in as your normal
|
||||
user. Then run:
|
||||
|
||||
```sh
|
||||
/usr/local/bin/ferese-session
|
||||
```
|
||||
|
||||
Your login must provide `XDG_RUNTIME_DIR` and access to the active seat through
|
||||
logind or seatd. If either is missing, fix the distribution's login/session setup;
|
||||
do not work around it by running Ferese as root or making device nodes writable.
|
||||
For non-systemd systems, follow your distribution's seatd and user-session setup.
|
||||
Do not start the DRM backend inside an existing graphical session; use a nested
|
||||
preview there.
|
||||
|
||||
## Optional desktop tools
|
||||
|
||||
Install these through your distribution when you want the corresponding features:
|
||||
|
||||
| Feature | Tools or services |
|
||||
| --- | --- |
|
||||
| Wallpaper file picker | `zenity` |
|
||||
| Screenshots and editing | `grim`, `slurp`, `satty`, `wl-clipboard`, Python 3 |
|
||||
| Idle locking | `swayidle` with the included `ferese-lock` |
|
||||
| Network controls | NetworkManager and its running service |
|
||||
| Audio controls | PipeWire, WirePlumber, and `wpctl` |
|
||||
| Bluetooth controls | BlueZ, `bluetoothctl`, and its running service |
|
||||
|
||||
Package names and availability vary by distribution. In particular, install
|
||||
Satty using its [upstream instructions](https://github.com/Satty-org/Satty#install)
|
||||
if your repositories do not provide it. Ferese does not enable these services
|
||||
or replace your existing service configuration during installation.
|
||||
|
||||
Print Screen captures the active monitor; **Super+Shift+S** selects an area.
|
||||
Use `ferese-screenshot --all` to capture all monitors in one image.
|
||||
|
||||
The native locker follows your shell theme. Open **Settings → Lock Screen** to
|
||||
customize it, or run `ferese-lock --preview` to see an ordinary preview window.
|
||||
Test real unlocking before enabling automatic locking; see
|
||||
[Native locker](locking.md) for authentication, idle locking, and limitations.
|
||||
|
||||
## Preview and logs
|
||||
|
||||
@@ -37,32 +203,99 @@ To preview a source build before installing, run these commands from the checkou
|
||||
inside an existing Wayland desktop:
|
||||
|
||||
```sh
|
||||
cargo build --release --locked -p ferese -p ferese-shell -p ferese-settings -p feresectl
|
||||
cargo build --release --locked -p ferese -p ferese-shell -p ferese-settings -p feresectl -p ferese-lock
|
||||
target/release/ferese --backend nested --grant-effects --grant-shell-control -- \
|
||||
target/release/ferese-shell
|
||||
```
|
||||
|
||||
After installation, the equivalent launcher is:
|
||||
|
||||
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.
|
||||
```sh
|
||||
ferese-session --nested
|
||||
```
|
||||
|
||||
Logs are stored in `${XDG_STATE_HOME:-~/.local/state}/ferese/`. Keep an existing
|
||||
desktop available while testing scaling, monitor hotplug, suspend and locking.
|
||||
The session launcher stores logs in `${XDG_STATE_HOME:-$HOME/.local/state}/ferese/`.
|
||||
A directly launched source build writes to its terminal. Keep another desktop
|
||||
available while testing scaling, monitor hotplug, suspend, and locking.
|
||||
|
||||
The session launcher enables the screencopy protocol for screenshot tools.
|
||||
Set `FERESE_ENABLE_SCREENCOPY=0` in the session environment to disable it.
|
||||
When enabled, Wayland clients can capture the unlocked desktop. Capture remains
|
||||
The launcher enables the screencopy protocol for screenshot tools. Set
|
||||
`FERESE_ENABLE_SCREENCOPY=0` in the session environment to disable it. When
|
||||
enabled, Wayland clients can capture the unlocked desktop. Capture remains
|
||||
blocked while the session is locked. Launcher changes take effect at next login.
|
||||
|
||||
## Updating
|
||||
|
||||
From your existing checkout, with any local edits saved:
|
||||
|
||||
```sh
|
||||
git pull --ff-only
|
||||
./scripts/install.sh
|
||||
```
|
||||
|
||||
Log out and back in to use the new release. Running sessions keep their existing
|
||||
processes and release paths until restarted.
|
||||
|
||||
Installer options:
|
||||
|
||||
```sh
|
||||
./scripts/install.sh --dry-run
|
||||
./scripts/install.sh --offline --release-id my-build
|
||||
./scripts/install.sh --skip-build
|
||||
```
|
||||
|
||||
`--dry-run` prints the planned commands. `--offline` requires dependencies to be
|
||||
cached already. `--skip-build` installs the binaries already in `target/release/`;
|
||||
use it only after building all five components from the intended revision.
|
||||
Run `./scripts/install.sh --help` for all options.
|
||||
|
||||
## Logout and recovery
|
||||
|
||||
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 Ferese freezes, switch to another TTY with **Ctrl+Alt+F1–F12**, sign in, and
|
||||
identify the affected compositor process:
|
||||
|
||||
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.
|
||||
```sh
|
||||
pgrep -a -u "$USER" -x ferese
|
||||
```
|
||||
|
||||
Terminate only that session's process with `kill PID`, replacing `PID` with the
|
||||
correct process ID. This ends its applications and can lose unsaved work. You
|
||||
can then select your other desktop at the next login.
|
||||
|
||||
### Roll back a release
|
||||
|
||||
While Ferese is stopped, inspect the retained releases:
|
||||
|
||||
```sh
|
||||
readlink /usr/local/lib/ferese/current
|
||||
readlink /usr/local/lib/ferese/previous
|
||||
ls /usr/local/lib/ferese/releases/
|
||||
```
|
||||
|
||||
If `previous` exists and points to the release you want, switch back:
|
||||
|
||||
```sh
|
||||
sudo sh -eu -c '
|
||||
cd /usr/local/lib/ferese
|
||||
previous_release=$(readlink previous)
|
||||
test -x "$previous_release/ferese-session"
|
||||
ln -sfn -- "$previous_release" current-rollback
|
||||
mv -Tf -- current-rollback current
|
||||
'
|
||||
```
|
||||
|
||||
Then log in again. This changes the selected binaries; it does not restore your
|
||||
config or replace the PAM policy. Settings keeps a backup when saving config
|
||||
changes; see [Saving and validation](configuration.md#saving-and-validation).
|
||||
|
||||
### Remove the login option
|
||||
|
||||
To hide Ferese from login managers while keeping its releases and your config:
|
||||
|
||||
```sh
|
||||
sudo mv /usr/share/wayland-sessions/ferese.desktop \
|
||||
/usr/local/lib/ferese/ferese.desktop.disabled
|
||||
```
|
||||
|
||||
For a command-based greeter, remove Ferese from its session choices using that
|
||||
greeter's configuration. Reinstalling restores the desktop session entry.
|
||||
@@ -10,13 +10,14 @@ from markdown_it import MarkdownIt
|
||||
|
||||
ROOT = Path(__file__).resolve().parent.parent
|
||||
OUTPUT = ROOT / 'build' / 'site'
|
||||
REPO = 'https://github.com/borngraced/ferese'
|
||||
REPO = 'https://github.com/ferese-wm/ferese'
|
||||
PAGES = [
|
||||
('index', 'Introduction', ROOT / 'site/content/index.md'),
|
||||
('installation', 'Installation', ROOT / 'docs/installation.md'),
|
||||
('configuration', 'Configuration', ROOT / 'docs/configuration.md'),
|
||||
('desktop-widgets', 'Desktop widgets', ROOT / 'docs/desktop-widgets.md'),
|
||||
('notifications', 'Notifications', ROOT / 'docs/notifications.md'),
|
||||
('locking', 'Native locker', ROOT / 'docs/locking.md'),
|
||||
]
|
||||
md = MarkdownIt('commonmark', {'html': False}).enable('table')
|
||||
OUTPUT.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
+1
-1
@@ -28,7 +28,7 @@ site sources or Markdown guides, then refresh the browser.
|
||||
|
||||
Select **Settings → Pages → Source → GitHub Actions**. The Pages workflow
|
||||
publishes site and documentation changes pushed to `main`, or can run manually.
|
||||
Expected URL: https://borngraced.github.io/ferese/.
|
||||
Expected URL: https://ferese-wm.github.io/ferese/.
|
||||
|
||||
Local links are relative, including documentation search, so publishing under
|
||||
the `/ferese/` project path works. Screenshots are copied from `docs/images`
|
||||
|
||||
@@ -6,7 +6,7 @@ This handbook covers installing Ferese, finding your way around, and making the
|
||||
|
||||
## Start with your first session
|
||||
|
||||
1. Read [Installation](installation.md) for the supported setup, building, and recovery.
|
||||
1. Read [Installation](installation.md) for dependencies, building, login-manager or TTY startup, and recovery.
|
||||
2. Open **Control Center → Settings** to choose a theme and configure your desktop.
|
||||
3. Explore the [configuration reference](configuration.md) for layouts, shortcuts, window rules, and displays.
|
||||
|
||||
@@ -31,6 +31,8 @@ Three-finger swipes move between workspaces and windows. Open **Control Center
|
||||
|
||||
Use **Settings** for everyday customization. Choose an appearance preset, change the wallpaper, adjust shell and window corners, or add a clock and sticky notes through [Desktop widgets](desktop-widgets.md).
|
||||
|
||||
[Native locker](locking.md) covers lock-screen appearance, authentication, and idle locking.
|
||||
|
||||
[Notifications](notifications.md) explains popup cards, history, Do Not Disturb, and app actions.
|
||||
|
||||
If you prefer a text editor, your configuration lives at:
|
||||
@@ -56,4 +58,4 @@ cargo test --workspace --locked
|
||||
cargo fmt --all --check
|
||||
```
|
||||
|
||||
The [source repository](https://github.com/borngraced/ferese) is the place to explore implementation details and report issues. When reporting a problem, include how to reproduce it, whether you used the nested or DRM backend, and relevant logs.
|
||||
The [source repository](https://github.com/ferese-wm/ferese) is the place to explore implementation details and report issues. When reporting a problem, include how to reproduce it, whether you used the nested or DRM backend, and relevant logs.
|
||||
+5
-5
@@ -19,7 +19,7 @@
|
||||
<meta property="og:type" content="website" />
|
||||
<meta
|
||||
property="og:image"
|
||||
content="https://borngraced.github.io/ferese/assets/ferese-desktop.png"
|
||||
content="https://ferese-wm.github.io/ferese/assets/ferese-desktop.png"
|
||||
/>
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<title>Ferese — A desktop that feels like yours</title>
|
||||
@@ -38,7 +38,7 @@
|
||||
<nav aria-label="Main navigation">
|
||||
<a href="./" aria-current="page">Overview</a
|
||||
><a href="docs/">Documentation</a
|
||||
><a href="https://github.com/borngraced/ferese"
|
||||
><a href="https://github.com/ferese-wm/ferese"
|
||||
>GitHub <svg class="link-arrow" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M7 17 17 7M7 7h10v10"/></svg></a
|
||||
>
|
||||
</nav>
|
||||
@@ -56,7 +56,7 @@
|
||||
<div class="product-links">
|
||||
<a class="button" href="docs/installation.html">Install Ferese</a>
|
||||
<a class="button secondary" href="docs/">Documentation</a>
|
||||
<a class="source-link" href="https://github.com/borngraced/ferese"
|
||||
<a class="source-link" href="https://github.com/ferese-wm/ferese"
|
||||
>Source code <svg class="link-arrow" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M7 17 17 7M7 7h10v10"/></svg></a
|
||||
>
|
||||
</div>
|
||||
@@ -108,13 +108,13 @@
|
||||
<h2>Getting started</h2>
|
||||
<p>
|
||||
The <a href="docs/installation.html">installation guide</a> covers
|
||||
Fedora with SDDM. You can also
|
||||
dependencies, setup with any Wayland-capable login manager, and TTY startup. You can also
|
||||
<a href="docs/installation.html#preview-and-logs">preview Ferese</a>
|
||||
inside an existing Wayland session before installing.
|
||||
</p>
|
||||
<p>
|
||||
Built in Rust on Smithay. Development happens
|
||||
<a href="https://github.com/borngraced/ferese">on GitHub</a>.
|
||||
<a href="https://github.com/ferese-wm/ferese">on GitHub</a>.
|
||||
</p>
|
||||
</section>
|
||||
</main>
|
||||
|
||||
Reference in new issue
Block a user