Skip to content

Building from Source

Jump to bottom
Daniel Struis edited this page Aug 21, 2026 · 5 revisions

Building from source

ClutterCutter is written in Rust. (The original C# implementation was removed in v0.9.2 — Rust is now the one and only build.) It has a shared scan engine and two GUI frontends: the native Win32 GUI on Windows (cluttercutter.exe) and a portable eframe/egui GUI (cluttercutter-gui) that runs on Linux and macOS. Contributors should read AGENTS.md for the full dev workflow, architecture, and conventions.

Building

Needs the Rust stable toolchain.

cd rust
cargo build --release

This produces, in rust/target/release/:

  • cluttercutter.exe — the native Win32 GUI. On the releases page and via winget this ships as ClutterCutter.exe, a single self-contained executable. Windows only; keeps the NTFS-MFT fast path.
  • cluttercutter-gui — the portable eframe/egui GUI. Runs on Linux and macOS (and Windows); scans with the portable std::fs walker.
  • cluttercutter-cli — a console harness for testing the scanners without a GUI.

On Linux / macOS, run the portable GUI directly:

cd rust
cargo run --bin cluttercutter-gui

There's also a console harness for testing the scanners without the GUI:

cargo run --bin cluttercutter-cli -- --top-n 20 C:\Users

Keep the tree cargo fmt-clean and cargo clippy --release-clean.

Tests & coverage

cd rust
cargo test                       # unit tests for the logic modules

The Win32 GUI is a large body of unsafe Win32 code (window procedures, GDI, list-view messages) that can't be meaningfully unit-tested without a live desktop, so the tests target the pure logic instead: byte/size/count formatting, the top-/oldest-files heap queries, temp-location discovery, the directory walker, and the MFT record/data-run parsers. Coverage on those modules runs high (formatting and types at 100%, analysis ~95%, the walker ~87%, temp ~83%). To measure it yourself:

cargo install cargo-llvm-cov      # one-time
cargo llvm-cov --lib --summary-only

Platforms

The Windows build is the native Win32 GUI and keeps the NTFS-MFT fast path. The Linux and macOS builds use the portable egui GUI, which shares the same Rust scan engine but scans with a portable std::fs walker. Prebuilt binaries are published for Windows (ClutterCutter.exe) and Linux (ClutterCutter-linux-x86_64.tar.gz); macOS has no prebuilt binary — build it from source with cargo run --bin cluttercutter-gui.

CI & releases

GitHub Actions reproduces the builds on every push (.github/workflows/build.yml), producing the Windows ClutterCutter.exe, the Windows ClutterCutter.msi installer, and the Linux ClutterCutter-linux-x86_64.tar.gz. Releases are managed by release-please under Semantic Versioning: conventional-commit messages on main keep an open release PR up to date; merging it tags the version and creates the GitHub Release. The winget manifest for each version is generated automatically and the winget folder is submitted to the community repository; winget installs the Windows portable build (the exe) only, not the MSI. See the README for the full procedure.

ClutterCutter

Source on GitHub

Clone this wiki locally