Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -186,3 +186,53 @@ jobs:
releaseDraft: true
prerelease: false
args: --bundles ${{ matrix.bundles }}

linux-release:
# Serialize with Windows so both platforms are retained in latest.json.
needs: build
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
cache-dependency-path: tauri-app/package-lock.json
- uses: dtolnay/rust-toolchain@stable
- name: Install Linux dependencies
run: |
sudo apt-get update
sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libgtk-layer-shell-dev libayatana-appindicator3-dev librsvg2-dev patchelf rpm
- run: npm ci
working-directory: tauri-app
- name: Validate Linux release
working-directory: tauri-app
run: |
npm test
npm run lint
cargo test --locked --manifest-path src-tauri/Cargo.toml --lib
python3 src-tauri/linux/test_launcher.py
- name: Require signing and feedback configuration
env:
TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
FEEDBACK_PORTAL_URL: ${{ secrets.FEEDBACK_PORTAL_URL }}
FEEDBACK_WRITE_KEY: ${{ secrets.FEEDBACK_WRITE_KEY }}
run: |
test -n "$TAURI_SIGNING_PRIVATE_KEY" || { echo 'Linux releases require an updater signing key'; exit 1; }
test -n "$FEEDBACK_PORTAL_URL" && test -n "$FEEDBACK_WRITE_KEY" || { echo 'Feedback configuration is missing'; exit 1; }
- name: Add signed Linux packages to the draft release
uses: tauri-apps/tauri-action@v0
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
FEEDBACK_PORTAL_URL: ${{ secrets.FEEDBACK_PORTAL_URL }}
FEEDBACK_WRITE_KEY: ${{ secrets.FEEDBACK_WRITE_KEY }}
APPIMAGE_EXTRACT_AND_RUN: '1'
with:
projectPath: tauri-app
tagName: v__VERSION__
releaseName: 'Cleanmeter v__VERSION__'
releaseDraft: true
prerelease: false
args: --bundles deb,rpm,appimage --config src-tauri/tauri.linux-release.conf.json
139 changes: 139 additions & 0 deletions .github/workflows/linux.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
name: Linux preview

on:
push:
branches: [feat/linux-support, feat/linux-current]
pull_request:
branches: [main]
workflow_dispatch:

permissions:
contents: read

jobs:
linux:
runs-on: ubuntu-22.04
timeout-minutes: 45
defaults:
run:
working-directory: tauri-app
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
cache-dependency-path: tauri-app/package-lock.json
- uses: dtolnay/rust-toolchain@stable
- uses: Swatinem/rust-cache@v2
with:
workspaces: tauri-app/src-tauri
- name: Install Linux build and smoke-test dependencies
run: |
sudo apt-get update
sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libgtk-layer-shell-dev libayatana-appindicator3-dev librsvg2-dev patchelf rpm xvfb dbus-x11 weston webkit2gtk-driver openbox xcompmgr xdotool
- run: npm ci
- run: npm run lint && npm test && npm run build
- run: python3 src-tauri/linux/test_launcher.py
- name: Test native backend
run: cargo test --locked --manifest-path src-tauri/Cargo.toml --lib
- name: Build Linux packages
env:
APPIMAGE_EXTRACT_AND_RUN: '1'
run: npm run tauri -- build --bundles deb,rpm,appimage
- name: Native settings and shortcut integration
run: |
cargo install tauri-driver --version 2.1.0 --locked
CLEANMETER_TEST_BINARY="$(realpath src-tauri/target/release/cleanmeter)" \
sh src-tauri/linux/test_native_webdriver.sh
- name: Smoke test GUI and native monitoring
run: |
set +e
RUST_LOG=info WEBKIT_DISABLE_COMPOSITING_MODE=1 timeout 15s xvfb-run -a dbus-run-session -- src-tauri/target/release/cleanmeter > linux-smoke.log 2>&1
result=$?
set -e
cat linux-smoke.log
test "$result" -eq 124
grep -q 'Linux monitoring connected' linux-smoke.log
test -x src-tauri/linux/cleanmeter-run
- name: Smoke test native Wayland fallback
run: |
export XDG_RUNTIME_DIR="$RUNNER_TEMP/cleanmeter-wayland"
mkdir -p "$XDG_RUNTIME_DIR"
chmod 700 "$XDG_RUNTIME_DIR"
weston --backend=headless-backend.so --socket=cleanmeter-test --idle-time=0 > weston.log 2>&1 &
compositor=$!
trap 'kill "$compositor" 2>/dev/null || true' EXIT
for attempt in $(seq 1 20); do
test -S "$XDG_RUNTIME_DIR/cleanmeter-test" && break
sleep 0.5
done
set +e
env -u DISPLAY GDK_BACKEND=wayland WAYLAND_DISPLAY=cleanmeter-test RUST_LOG=info WEBKIT_DISABLE_COMPOSITING_MODE=1 timeout 15s dbus-run-session -- src-tauri/target/release/cleanmeter > wayland-smoke.log 2>&1
result=$?
set -e
cat wayland-smoke.log
test "$result" -eq 124
grep -q 'Linux monitoring connected' wayland-smoke.log
grep -q 'Display backend: wayland' wayland-smoke.log
- uses: actions/upload-artifact@v4
if: always()
with:
name: cleanmeter-linux-x86_64
if-no-files-found: error
path: |
tauri-app/src-tauri/target/release/bundle/deb/*.deb
tauri-app/src-tauri/target/release/bundle/rpm/*.rpm
tauri-app/src-tauri/target/release/bundle/appimage/*.AppImage
tauri-app/linux-smoke.log
tauri-app/wayland-smoke.log
tauri-app/weston.log

live-fps:
needs: linux
runs-on: ubuntu-24.04
timeout-minutes: 10
steps:
- uses: actions/download-artifact@v4
with:
name: cleanmeter-linux-x86_64
path: packages
- name: Install desktop runtime and real MangoHud
run: |
sudo apt-get update
sudo apt-get install -y libwebkit2gtk-4.1-0 libayatana-appindicator3-1 libxnvctrl0 vulkan-tools mesa-vulkan-drivers xvfb
curl -fL https://github.com/flightlessmango/MangoHud/releases/download/v0.7.2/MangoHud-0.7.2.r0.g7b80f73.tar.gz -o mangohud.tar.gz
echo '16b5a5d39b82825bac69ead0f2dd5c5f2bbc32b973a2f7b117a775a0b8731f58 mangohud.tar.gz' | sha256sum -c -
tar -xzf mangohud.tar.gz
cd MangoHud
tar -xf MangoHud-package.tar
sudo bash mangohud-setup.sh install
mangohud --version
- name: Verify real Vulkan FPS through the AppImage launcher
run: |
image=$(find packages -name '*.AppImage' -print -quit)
chmod +x "$image"
"$image" --appimage-extract > /dev/null
chmod +x squashfs-root/usr/bin/cleanmeter
export XDG_CACHE_HOME="$RUNNER_TEMP/cleanmeter-live-test"
xvfb-run -a squashfs-root/AppRun --run vkcube > game.log 2>&1 &
game=$!
trap 'kill "$game" 2>/dev/null || true' EXIT
for attempt in $(seq 1 20); do
squashfs-root/AppRun --diagnose > diagnostics.json
if python3 -c 'import json; d=json.load(open("diagnostics.json")); assert any(g["fps"] > 0 and g["frametime"] > 0 for g in d["games"]); assert any(s["name"] == "CPU Total" for s in d["hardware"]["sensors"])'; then
cat diagnostics.json
exit 0
fi
sleep 1
done
cat game.log
find "$XDG_CACHE_HOME/cleanmeter/fps" -name '*.csv' -exec sh -c 'head -n 4 "$1"; tail -n 3 "$1"' sh {} \;
exit 1
- uses: actions/upload-artifact@v4
if: always()
with:
name: cleanmeter-live-fps-evidence
path: |
diagnostics.json
game.log
11 changes: 10 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,16 @@ A clean, minimal performance overlay for gamers. Monitor your system stats witho
- **Network speed** — download/upload rates with live graph
- **Smart sensor auto-select** — picks the right CPU, GPU, RAM, and network sensors automatically

## Requirements
## Linux preview

Linux support is available on the `feat/linux-current` branch with native hardware
monitoring and per-frame game FPS through MangoHud 0.7+. DEB, RPM, and AppImage
packages are built by the Linux preview workflow. See the [Linux setup guide](docs/linux.md)
for installation, Steam launch options, hardware coverage, and Wayland limitations.
Live percentile lows and recording are supported. Game Mode integration and bounded
long-session capture remain incomplete; this is a Desktop Mode test preview.

## Windows requirements

- Windows 10/11 (x64)
- [.NET 8 Desktop Runtime](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) — required for hardware monitoring
Expand Down
79 changes: 79 additions & 0 deletions docs/linux-delivery.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# Linux delivery gates

Baseline: Windows v2.2.19 (`ed0bb61`), with the Linux implementation from PR #68
(`abf6e59`) applied without replacing current UI changes.

## 1. Current-main preview

- Resolve the Linux port against current settings, diagnostics, Pixel Shift,
GPU power validation, sounds, and clock UI.
- Run frontend tests/lint/build, Linux Rust tests and launcher tests.
- Build AppImage, DEB and RPM on Ubuntu 22.04.
- Exercise X11 and native Wayland with an isolated settings directory.
- Compare standalone TypeScript diagnostics to clean main.

## 2. Overlay implementation and local validation

Complete implementation and local validation before requesting Mars's testing.
Hardware testing is a final acceptance step, not a gate on further development.
Test Desktop Mode and Game Mode separately. A passing desktop smoke test does
not establish Game Mode support. Check transparency, visibility over a native
game and a Proton game, focus, controller input, and coexistence with Steam/QAM
and the performance overlay. Record SteamOS version and LCD/OLED model.

Gamescope's external overlay selection must be investigated before adopting an
external-window integration. Do not replace or terminate Steam's mangoapp to
make a test pass. If a separate renderer is needed, keep the shared settings UI
and telemetry contracts and review the architecture before expanding the port.

## 3. Telemetry parity

Add tested Linux CPU/GPU clock providers and supported power providers. Validate
real AMD APU readings on Deck and keep unavailable readings distinct from zero.
Test device identity, reconnects, permissions, stale data and game selection.

## 4. Product parity

Verify current layouts, themes, graphs, settings persistence, reset, Pixel
Shift, shortcuts, startup, diagnostics, feedback and sound on Linux. Probe
Wayland portal support instead of promising universal global shortcuts.

## 5. Frame statistics

Per-frame MangoHud 0.7.2 capture has been validated against a live Vulkan workload.
The Linux implementation now computes Windows-compatible live and recording lows.
Continue checking game restarts, capture-file rotation, long sessions and overhead.

## 6. Packaging and hardware acceptance

Verify clean install, upgrade, uninstall and a portable home-directory launch.
No changes to SteamOS read-only protection. Measure idle and in-game overhead,
suspend/resume, game exits, and long sessions. AppImage compatibility and real
GPU support require hardware evidence. Keep release artifacts unpublished until
explicit publication approval.

## Test environments

- Windows: shared frontend and Windows backend regression checks.
- Ubuntu 22.04 WSL2: Linux builds/tests and WebKit runtime checks. Virtualized
sensors are not evidence of host Windows or Deck hardware support.
- Xvfb/Weston: headless startup and application integration.
- Do not install additional Linux distributions or a Linux VM. Use the existing, user-approved WSL
environment for local builds and native runtime checks.
- Mars's Deck: physical sensors, games, controls, Game Mode and performance.

## Remaining delivery gates

Native Wayland layer-shell positioning and portal shortcut integration are
implemented and locally exercised. Unsupported desktops retain a monitor window.
Gamescope Game Mode coexistence with Steam's performance HUD is not implemented
and cannot be signed off from these desktop tests.

MangoHud 0.7.2 retains every captured sample until logging stops. Cleanmeter's
bounded reader and histogram do not bound the producer's memory or CSV growth.
A bounded capture transport is required before long-session parity sign-off.

Signed AppImage release configuration and a serialized Linux draft-release job
are implemented. No signed update was published or end-to-end applied.
Physical Deck sensors, Proton, suspend/resume, controller input and driver
performance remain acceptance checks.
71 changes: 71 additions & 0 deletions docs/linux-mars-test.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# Steam Deck preview test

This is a current-main Linux preview, not a parity release. Start in Desktop
Mode. Game Mode overlay compatibility is an explicit experiment and may fail.
No root password, package-manager changes, or read-only filesystem changes
should be needed to launch the portable application.

## Start

1. Extract the test kit into a directory under your home folder.
2. In that directory, run `sha256sum -c SHA256SUMS`.
3. Make the included AppImage executable (`chmod +x ./*.AppImage`).
4. Launch the AppImage. If FUSE is unavailable, use
`./Cleanmeter_2.2.19_amd64.AppImage --appimage-extract-and-run`.
5. If launch fails, capture its terminal output. Do not install system packages
or disable SteamOS read-only protection to work around it.

## Desktop Mode

- Record Deck model (LCD/OLED), SteamOS version and desktop session type.
- Check settings fit the 1280x800 display; scroll all tabs and test touch input.
- Check CPU/RAM/network readings change under load; compare against a trusted
monitor. WSL results do not validate Deck hardware readings.
- Check GPU identification, load, temperature, memory and available power.
Unsupported readings must not appear as credible zero values.
- Toggle the overlay, change its layout/position, and check it does not steal
game input. Check theme, graph toggles, persistence and restart.
- FPS requires a compatible MangoHud installation (0.7+). Record
`mangohud --version`; if unavailable, report it rather than changing SteamOS.
- With compatible MangoHud, keep Cleanmeter open and try this Steam launch
option using the actual absolute path to the AppImage:
`"/home/deck/path/Cleanmeter_2.2.19_amd64.AppImage" --run %command%`.
- Test one native Vulkan game and one Proton game. Check selection, switching,
exit/relaunch and stale values. Remove the launch option after testing.

## Game Mode experiment

Record whether the app launches, whether the overlay is visible above a game,
whether game/controller input remains usable, and whether Steam/QAM and the
built-in performance HUD still work. Do not terminate mangoapp or replace
Steam components. An app opening as a separate full-screen window is a failure
of the in-game overlay requirement, not a successful overlay test.

## Stability and overhead

Use the same game scene/settings with Cleanmeter off and on. Record FPS,
frametime behavior, CPU/memory usage and battery power where available. Test
suspend/resume and a 30-minute session. Note crashes or stale readings.

## Diagnostic snapshot

Run the AppImage with `--diagnose > cleanmeter-diagnostics.json`. This is a
read-only hardware and sampled FPS snapshot. Review it before sharing: it can
include hardware identifiers and game names. Include screenshots and exact
reproduction steps. Do not include Steam credentials or unrelated logs.

## Known gaps

Native Wayland supports layer-shell positioning and desktop portal shortcuts
where available; other desktops use a monitor window. Game Mode is unvalidated.
CPU/GPU clocks, supported CPU power, per-frame percentile lows and recording are
implemented and locally tested; Deck sensor coverage and long-session overhead
remain unverified. Signed AppImage updater configuration is prepared, but no Linux update has
been published or applied end to end. MangoHud per-frame capture memory grows
throughout a session; this remains an implementation gap.

## Remove

Quit Cleanmeter, disable its autostart setting if enabled, remove any Steam
launch option you added, then delete the extracted kit. Retain settings if you
intend to test a later build.
Loading
Loading