Repository navigation
Add Linux preview with native monitoring and MangoHud FPS support #68
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
d245360
de2596e
5c467a4
246ea8d
d8b757b
230490c
abf6e59
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| 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 | ||
| 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 | ||
| 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. |
| 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 | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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:
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 -120Repository: 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 -120Repository: 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 -120Repository: 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:
💡 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 |
||
| # 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" | ||
There was a problem hiding this comment.
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:
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@stableare mutable references. A retargeted or compromised tag can execute arbitrary code in the runner with workspace access and the read-onlyGITHUB_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