Skip to content
Closed
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
134 changes: 134 additions & 0 deletions .github/workflows/linux.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
name: Linux preview

on:
push:
branches: [feat/linux-support]
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
Comment on lines +21 to +22

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -eu
printf '%s\n' '--- workflow ---'
cat -n .github/workflows/linux.yml
printf '%s\n' '--- action-pinning policy references ---'
rg -n -i 'pin|sha|action' .github .yamllint.yml .pre-commit-config.yaml 2>/dev/null || true

Repository: SupaStellar/Cleanmeter

Length of output: 8770


Security Misconfiguration (CWE-829): Inclusion of Functionality from Untrusted Control Sphere

Reachability: External · Exploitability: Moderate

Pin each GitHub Action to a commit SHA.

@v4, @v2, and @stable are mutable references. A retargeted or compromised tag can execute arbitrary code in the runner with workspace access and the read-only GITHUB_TOKEN. Pin every action to a full commit SHA and retain the release version in a comment.

🧰 Tools
🪛 zizmor (1.29.0)

[warning] 21-21: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false

(artipacked)


[error] 21-21: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)


[error] 22-22: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

Source: Linters/SAST tools

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 libayatana-appindicator3-dev librsvg2-dev patchelf rpm xvfb dbus-x11 weston
- 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: 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
10 changes: 9 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,15 @@ 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-support` branch with native hardware
monitoring and sampled 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.
Percentile lows and benchmark recording are not yet supported on Linux.

## 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
139 changes: 139 additions & 0 deletions docs/linux.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
# Cleanmeter for Linux (preview)

The Linux build uses a native Rust monitoring backend. It does not require .NET,
PresentMon, PawnIO, a Windows service, or administrator privileges to run.
Packages target x86-64 desktops: Debian/Ubuntu `.deb`, Fedora-family `.rpm`, and
an AppImage. ARM and Steam Deck Gaming Mode are not validated.

## Install and start

Download the `cleanmeter-linux-x86_64` artifact from a successful **Linux preview**
GitHub Actions run on `feat/linux-support`. These are development packages, not a
published stable release. Extract the artifact, then use the appropriate command
with the actual filename:

```sh
sudo apt install ./Cleanmeter_2.2.17_amd64.deb
# or, on Fedora:
sudo dnf install ./Cleanmeter-2.2.17-1.x86_64.rpm
# or:
chmod +x ./Cleanmeter_2.2.17_amd64.AppImage
./Cleanmeter_2.2.17_amd64.AppImage
```

Package filenames can vary; use the name in your downloaded artifact. AppImages
still need a working desktop and graphics driver. If FUSE is unavailable, use
`--appimage-extract-and-run`. Hardware monitoring starts when Cleanmeter starts.

The app prefers X11/XWayland when available. On native Wayland it uses a normal
monitor window, without absolute overlay positioning or global shortcuts.
Exclusive fullscreen, native Wayland games under an XWayland session, and
Gamescope can obscure external overlay windows. Borderless/windowed mode is the
recommended starting point. This preview does not inject Cleanmeter's UI into games.

Closing Settings minimizes it to the taskbar. Stats has a visibility switch and
a Quit button, so a desktop without tray icons still has controls. Start at login
writes an XDG autostart entry for the current executable; if you move an AppImage,
turn Start at login off and back on to update its path.

## Game FPS and frametime

Install **MangoHud 0.7.0 or newer** through your distribution or the
[upstream project](https://github.com/flightlessmango/MangoHud#installation).
Check with `mangohud --version`. Older distro packages, including Ubuntu 22.04/24.04 packages based on 0.6.x, cannot
provide the live CSV output used here. Hardware monitoring works without MangoHud.

For a native game:

```sh
cleanmeter-run /path/to/game [arguments]
```

For Steam installed on the host, set the game's launch options to:

```text
cleanmeter-run %command%
```

With an AppImage, use its absolute path instead:

```text
"/home/you/Applications/Cleanmeter.AppImage" --run %command%
```

`--run` launches the game without starting a second monitor instance; keep the
Cleanmeter app open separately. The DEB/RPM also accept `cleanmeter --run ...`.
Some OpenGL games need `cleanmeter-run --dlsym game`. Proton games need the
appropriate MangoHud libraries inside their Steam runtime. Flatpak Steam, Snap
Steam, anti-cheat games, and Gamescope require separate validation; this preview
does not configure their sandbox permissions or promise compatibility.

The launcher creates private temporary logs under
`$XDG_CACHE_HOME/cleanmeter/fps` (or `~/.cache/cleanmeter/fps`), removes its session
on normal exit, and disables log uploads. It preserves game arguments and exit
codes. An interrupted machine or SIGKILL can leave session files; they can be
removed after the game exits. Keep cache paths free of commas (MangoHud uses them
as configuration separators).

FPS and frametime are sampled every 100 ms by MangoHud, then read at Cleanmeter's
polling rate. Auto chooses the most recently updated game; selecting a game pins
the source. Readings expire after three seconds without a log update. Unsupported
or absent readings show a dash. **1%/0.1% lows and benchmark recording are disabled**
because these logs are sampled telemetry, not reliable per-frame capture.

## Hardware coverage

| Reading | Source and limits |
| --- | --- |
| CPU utilization | `/proc/stat` deltas; first poll establishes a baseline |
| CPU temperature | Recognized `hwmon` CPU drivers; prefers package/Tctl/Tdie |
| CPU power | Not collected in this preview |
| RAM | `/proc/meminfo`, using `MemAvailable` to account for reclaimable cache |
| Network | `/proc/net/dev` byte deltas; excludes loopback; counter resets are discarded |
| AMD GPU | DRM/sysfs busy percentage, VRAM, temperature and power when exposed |
| NVIDIA GPU | Driver's `nvidia-smi`, with a bounded timeout; N/A readings are omitted |
| Intel GPU | Enumerated through DRM; only exposed sysfs sensors are read. Utilization, VRAM, and power are often unavailable |

Optional unreadable sensors stay absent; the app does not change device permissions.
GPU selection remains scoped to one GPU. Linux identifiers differ from Windows,
so manually imported Windows sensor selections may need to be selected again.

## Diagnose and build

Print current hardware and active game samples without opening a GUI:

```sh
cleanmeter --diagnose
# or ./Cleanmeter.AppImage --diagnose
```

This includes hardware names and local interface identifiers; review it before
sharing. It does not send diagnostics anywhere.

On Ubuntu 22.04+ with Rust and Node 22 installed:

```sh
sudo apt install build-essential libwebkit2gtk-4.1-dev libgtk-3-dev \
libayatana-appindicator3-dev librsvg2-dev libssl-dev patchelf rpm
cd tauri-app
npm ci
npm run lint
npm test
npm run build
python3 src-tauri/linux/test_launcher.py
cargo test --locked --manifest-path src-tauri/Cargo.toml --lib
npm run tauri -- build --bundles deb,rpm,appimage
```

The platform-specific Tauri configurations keep Windows sidecar resources out of
Linux bundles. `.github/workflows/linux.yml` builds all three package formats,
smoke-tests X11 and native Wayland startup, and checks live MangoHud 0.7.2 FPS with a software-rendered
Vulkan cube on Ubuntu 24.04. Physical GPU drivers, actual games, Fedora installs,
and native Wayland compositor behavior still need device testing before release.
Linux updates are installed manually through a downloaded package; the Windows
in-app updater is disabled for this preview.

The standalone TypeScript check (`npx tsc --noEmit -p tsconfig.app.json`) currently
reports five pre-existing diagnostics also present on the base Windows branch.
The Linux changes do not introduce additional diagnostics; lint, frontend unit
tests, and the production Vite build are checked separately.
2 changes: 1 addition & 1 deletion tauri-app/src-tauri/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,9 @@ log = "0.4"
env_logger = "0.11"
dirs = "6"

winreg = "0.55"

[target.'cfg(windows)'.dependencies]
winreg = "0.55"
windows = { version = "0.58", features = [
"Win32_Foundation",
"Win32_Storage_FileSystem",
Expand Down
50 changes: 50 additions & 0 deletions tauri-app/src-tauri/linux/cleanmeter-run
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
#!/bin/sh
# Launch a native or Proton game with sampled FPS telemetry for Cleanmeter.
set -eu
if [ "$#" -eq 0 ]; then
echo 'Usage: cleanmeter-run <game> [args...]' >&2
echo 'Steam launch options: cleanmeter-run %command%' >&2
exit 2
fi
if ! command -v mangohud >/dev/null 2>&1; then
echo 'Install MangoHud first (Ubuntu/Debian: sudo apt install mangohud).' >&2
exit 1
fi
# 0.6.x only saves CSV files when logging stops; live reads need 0.7+.
version=$(mangohud --version 2>/dev/null || true)
if ! printf '%s\n' "$version" | awk -F. '/^v?[0-9]+\.[0-9]+/ { major=$1; sub(/^v/, "", major); if (major+0 > 0 || $2+0 >= 7) ok=1 } END { exit !ok }'; then
echo "Cleanmeter FPS requires MangoHud 0.7.0 or newer (found: $version)." >&2
exit 1
fi
case "${XDG_CACHE_HOME:-}" in
/*) cache=$XDG_CACHE_HOME ;;
*) cache=$HOME/.cache ;;
esac
umask 077
mkdir -p "$cache/cleanmeter/fps"
session=$(mktemp -d "$cache/cleanmeter/fps/session.XXXXXX")
case "$session" in
*,*) echo 'MangoHud requires a cache path without commas.' >&2; rmdir "$session"; exit 1 ;;
esac
child=
cleanup() { rm -rf -- "$session"; }
trap cleanup EXIT
trap 'if [ -n "$child" ]; then kill -TERM "$child" 2>/dev/null || true; fi' INT TERM

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

🔎 Supported by static analysis

🏁 Script executed:

#!/bin/sh
# Verify that a trapped signal interrupts wait before a TERM-ignoring child exits.
set -eu
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT

cat > "$tmp/probe.sh" <<'SH'
#!/bin/sh
child=
cleanup() { printf 'cleanup\n'; }
trap cleanup EXIT
trap 'if [ -n "$child" ]; then kill -TERM "$child" 2>/dev/null || true; fi' INT TERM
sh -c 'trap "" TERM; sleep 2' &
child=$!
status=0
wait "$child" || status=$?
printf 'wait-status=%s\n' "$status"
SH
chmod +x "$tmp/probe.sh"

"$tmp/probe.sh" >"$tmp/output" &
wrapper=$!
sleep 1
kill -INT "$wrapper"
wait "$wrapper" || true
cat "$tmp/output"

Repository: SupaStellar/Cleanmeter

Length of output: 182


🤖 get_repo_knowledge executed:

get_repo_knowledge SupaStellar/Cleanmeter /tmp/coderabbit-repo-knowledge/supastellar-cleanmeter-bf513fbf

Length of output: 1195


🏁 Script executed:

#!/bin/sh
set -eu
printf '%s\n' '--- target file ---'
cat -n tauri-app/src-tauri/linux/cleanmeter-run
printf '%s\n' '--- related references ---'
rg -n --glob '!node_modules' 'cleanmeter-run|forward_and_wait|mangohud|session=' tauri-app/src-tauri tauri-app 2>/dev/null | head -120

Repository: SupaStellar/Cleanmeter

Length of output: 6731


🏁 Script executed:

#!/bin/sh
set -eu
cat -n tauri-app/src-tauri/linux/cleanmeter-run
printf '%s\n' '--- related references ---'
rg -n --glob '!node_modules' 'cleanmeter-run|mangohud|session=' tauri-app/src-tauri tauri-app 2>/dev/null | head -120

Repository: SupaStellar/Cleanmeter

Length of output: 6711


🏁 Script executed:

#!/bin/sh
set -eu
printf '%s\n' '--- target file ---'
sed -n '1,140p' tauri-app/src-tauri/linux/cleanmeter-run
printf '%s\n' '--- references ---'
rg -n --glob '!node_modules' 'cleanmeter-run|mangohud|session' tauri-app/src-tauri tauri-app 2>/dev/null | head -120

Repository: SupaStellar/Cleanmeter

Length of output: 10186


🏁 Script executed:

#!/bin/sh
set -eu
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT
cat >"$tmp/probe.sh" <<'SH'
#!/bin/sh
set -u
start=$(date +%s)
child=
cleanup() { printf 'cleanup-at=%s\n' "$(( $(date +%s) - start ))"; }
trap cleanup EXIT
trap 'if [ -n "$child" ]; then printf "handler-at=%s\n" "$(( $(date +%s) - start )); kill -TERM "$child" 2>/dev/null || true; fi' INT TERM
sh -c 'trap "" TERM; sleep 4' &
child=$!
status=0
wait "$child" || status=$?
printf 'wait-status=%s elapsed=%s\n' "$status" "$(( $(date +%s) - start ))"
SH
chmod +x "$tmp/probe.sh"
"$tmp/probe.sh" >"$tmp/output" &
wrapper=$!
sleep 1
kill -INT "$wrapper"
wait "$wrapper" || true
cat "$tmp/output"

Repository: SupaStellar/Cleanmeter

Length of output: 197


🌐 Web query:

POSIX sh trapped signal wait command interrupted wait semantics dash trap wait

💡 Result:

According to the POSIX standard (IEEE Std 1003.1), when a shell is executing the wait utility and receives a signal for which a trap has been set, the wait utility must return immediately with an exit status greater than 128, after which the trap action associated with that signal is executed [1]. This requirement ensures that the shell can respond to asynchronous events even while blocked waiting for child processes. In practice, implementation behavior can vary significantly: 1. POSIX Requirement: The shell's wait command is required to be interrupted by a trapped signal [1]. This interruption triggers the execution of the trap action, allowing scripts to handle signals promptly [1]. 2. Dash Behavior: It has been documented that the dash shell historically does not interrupt the wait command when a trapped signal is received [2]. This deviates from the expected POSIX behavior, meaning the shell will continue to wait for the child process even if a signal handler is triggered or pending [2]. 3. Other Shells: Many other shells, such as bash, zsh, and mksh, generally adhere to the POSIX requirement, interrupting the wait command upon receipt of a trapped signal [2]. If you are developing portable shell scripts, you cannot rely on wait being interrupted by signals across all POSIX-compliant shells due to these implementation differences in shells like dash [2]. Using wait within a loop or employing other mechanisms to monitor process state and signals may be necessary if immediate responsiveness is required [2].

Citations:


Forward the received signal and reap the child before cleanup.

The trap converts SIGINT to SIGTERM. On shells that interrupt wait for trapped signals, line 49 can also return before the child exits, which removes $session while the child still runs. Use separate handlers that forward the signal and wait for the child.

# A private config file avoids altering the user's MangoHud configuration.
# Uploads are not enabled. Files are removed when the launched process exits.
# MangoHud 0.7.x no_display prevents autostart_log from running. Transparent
# rendering keeps that update path active without showing a second HUD.
cat > "$session/MangoHud.conf" <<CONF
alpha=0
background_alpha=0
autostart_log=1
log_interval=100
log_duration=0
permit_upload=0
output_folder=$session
CONF
MANGOHUD_CONFIGFILE="$session/MangoHud.conf" MANGOHUD_CONFIG="alpha=0,background_alpha=0,autostart_log=1,log_interval=100,log_duration=0,permit_upload=0,output_folder=$session" mangohud "$@" &
child=$!
code=0
wait "$child" || code=$?
exit "$code"
Loading
Loading