Repository navigation
Description
Migrate CLI to Rust with Tauri UI and PyO3 bridge
Orchestration process
Each phase is a sub-issue. The workflow for every phase:
- Branch from
main(e.g.rust/phase-1a-scaffold) - Implement the phase tasks
- Push and open a PR referencing the sub-issue
- CI must be green -- if red, fix on the branch until green
- Merge to main once CI passes
- Close the sub-issue
- Start the next phase from the updated
main
Dependencies between phases are strict -- do not start a phase until its prerequisites are merged to main. Phases 2b, 2c, 2d are independent of each other and can run in parallel after 2a merges.
Phase 1a -> Phase 1b -> Phase 1c
|
Phase 2a
/ | \
2b 2c 2d
\ | /
Phase 2e
|
Phase 3a
|
Phase 3b
|
Phase 4
Sub-issues
Phase 1: Scaffold
- Phase 1a: Scaffold Cargo workspace and rust-toolchain #15 -- Phase 1a: Scaffold Cargo workspace and rust-toolchain
- Phase 1b: Add maturin build backend and PyO3 bridge stub #16 -- Phase 1b: Add maturin build backend and PyO3 bridge stub
- Phase 1c: Add sccache CI workflows for all 6 platforms #17 -- Phase 1c: Add sccache CI workflows for all 6 platforms
Phase 2: Port core logic
- Phase 2a: Port argument parsing and CLI entry point to Rust #18 -- Phase 2a: Port argument parsing and CLI entry point to Rust
- Phase 2b: Port file watching to Rust #19 -- Phase 2b: Port file watching to Rust (parallel with 2c, 2d)
- Phase 2c: Port archive download and toolchain installers to Rust #20 -- Phase 2c: Port archive download and toolchain installers to Rust (parallel with 2b, 2d)
- Phase 2d: Port project init and sketch detection to Rust #21 -- Phase 2d: Port project init and sketch detection to Rust (parallel with 2b, 2c)
- Phase 2e: Port keyboard input and build orchestration to Rust #22 -- Phase 2e: Port keyboard input and build orchestration to Rust
Phase 3: Tauri UI
- Phase 3a: Create Tauri viewer sidecar binary #23 -- Phase 3a: Create Tauri viewer sidecar binary
- Phase 3b: Integrate Tauri viewer into CLI and remove Flask #24 -- Phase 3b: Integrate Tauri viewer into CLI and remove Flask
Phase 4: Ship
- Phase 4: Polish, remove dead Python, benchmarks, and final cut over #25 -- Phase 4: Polish, remove dead Python, benchmarks, and final cut over
Motivation
The CLI is currently pure Python. Migrating to Rust gives us:
- Startup time: ~5ms vs ~300-500ms Python interpreter startup
- Single binary distribution: No Python runtime required for end users
- Tauri UI: Replace Flask HTTP server + system browser with a native webview window (~3 MB vs ~200 MB Playwright Chromium)
- Consistency with other tools:
running-processalready uses this pattern
Reference implementation: zackees/running-process
The running-process repo provides the blueprint:
Project structure
Cargo.toml # Workspace root
rust-toolchain.toml # Pinned Rust version
pyproject.toml # maturin build backend
crates/
running-process-core/ # Pure Rust library (no Python)
running-process-py/ # PyO3 cdylib bridge -> running_process._native
src/
running_process/ # Python package (imports from _native)
ci/ # Python-based CI orchestration
Key patterns to replicate
- Cargo workspace with pure-Rust core crate + PyO3 bridge crate
- maturin as Python build backend with
abi3-py310(one wheel for Python 3.10+) - sccache in CI via
mozilla-actions/sccache-action@v0.0.9+SCCACHE_GHA_ENABLED=true+RUSTC_WRAPPER=sccache, combined withSwatinem/rust-cache@v2(registry only,cache-targets: false) - Reusable workflow templates (
_build.yml,_lint.yml, etc.) called by thin per-platform workflows - Fingerprint-based dev builds to skip unnecessary recompilation
CI matrix (6 platforms)
| Platform | Runner |
|---|---|
| Linux x86 | ubuntu-24.04 |
| Linux ARM | ubuntu-24.04-arm |
| Windows x86 | windows-2025 |
| Windows ARM | windows-11-arm |
| macOS x86 | macos-15-intel |
| macOS ARM | macos-15 |
Proposed architecture
fastled-wasm/
Cargo.toml # Workspace root
rust-toolchain.toml # Pinned Rust toolchain
pyproject.toml # maturin build backend
crates/
fastled-cli/ # Pure Rust binary (the CLI)
src/
main.rs # Entry point, clap args
watcher.rs # File watching (notify crate)
build.rs # Compilation orchestration
archive.rs # Toolchain download/extract
project.rs # Project init, sketch detection
keyboard.rs # Terminal input (termios/Win32)
fastled-tauri/ # Tauri UI viewer (separate binary)
src/
main.rs # Tauri app, window management
ipc.rs # JS <-> Rust commands
tauri.conf.json
fastled-py/ # PyO3 bridge crate (cdylib)
src/
lib.rs # #[pymodule] exposing Rust to Python
src/
fastled/ # Python package (imports from _native)
toolchain/
internal_wasm_build.py # Stays Python (Meson/Ninja orchestration)
playwright/ # Stays Python (browser automation)
Runtime flow
fastled --just-compile examples/Wasm
-> Rust CLI parses args (clap)
-> Detects sketch directory (Rust)
-> Calls Python subprocess for WASM build
| -> internal_wasm_build.py (Meson/Ninja)
-> Reports results
fastled --app examples/Wasm
-> Rust CLI parses args
-> Spawns Tauri viewer (sidecar binary)
| -> Native webview window, no localhost server
| -> Loads frontend assets directly (no HTTP, no CORS)
| -> IPC for debug symbol resolution
-> Watches files (notify crate)
-> On change: calls Python subprocess for rebuild
-> Notifies Tauri viewer to reload
What moves to Rust vs stays Python
MIGRATE TO RUST (~90% of codebase)
| Module | LOC | Rust replacement |
|---|---|---|
parse_args.py + args.py |
395 | clap |
filewatcher.py |
307 | notify crate |
server_flask.py |
226 | Eliminated by Tauri |
open_browser.py |
211 | Eliminated by Tauri |
emscripten_archive.py |
250 | reqwest + tar/zstd |
frontend_esbuild.py |
227 | reqwest + zip |
project_init.py |
419 | reqwest + zip |
keyboard.py |
120 | termios/Win32 API |
debug_symbols.py |
212 | Rust path resolution |
debug_routes.py |
47 | Tauri IPC command |
build_service.py + build_types.py |
279 | Rust structs |
compile_native.py |
189 | Rust orchestration loop |
| Utilities (emoji, spinner, types, etc.) | ~300 | Standard Rust |
KEEP AS PYTHON (called via subprocess)
| Module | LOC | Reason |
|---|---|---|
toolchain/internal_wasm_build.py |
1,696 | Orchestrates Meson/Ninja C++ build system |
toolchain/emscripten.py |
879 | Emscripten env setup, delegates to internal_wasm_build |
playwright/* |
1,153 | Playwright Python library dependency |
select_sketch_directory.py |
160 | Interactive prompts (low priority to port) |
BRIDGE VIA PyO3 (for pip install fastled compatibility)
The PyO3 bridge crate exposes the Rust CLI functionality as a Python module (fastled._native) so that pip install fastled continues to work. Python callers get:
fastled._native.build(sketch_dir, mode)-> calls Rust build orchestrationfastled._native.watch(sketch_dir)-> starts file watcherfastled._native.init(example_name)-> project scaffolding
Tauri replaces Flask + browser
What gets eliminated
| Current component | Status |
|---|---|
Flask HTTP server |
Eliminated -- Tauri loads assets directly |
flask-cors |
Eliminated -- no cross-origin (same process) |
| HTTPS + self-signed certs | Eliminated -- Tauri custom protocol is a secure context |
| COEP/COOP headers | Simplified -- configurable in tauri.conf.json |
| Port finding / conflicts | Eliminated -- no TCP server |
| Playwright browser (~200 MB) | Eliminated -- uses OS webview (0 bytes) |
| Process cleanup / orphans | Eliminated -- single process lifecycle |
Tauri integration approach: Sidecar binary
The Tauri viewer is built as a separate binary (fastled-tauri) rather than embedding Tauri into the main CLI. This keeps the CLI lightweight for headless/CI use:
// In fastled-cli, when --app is requested:
let tauri_path = find_tauri_sidecar(); // downloaded on first use, like esbuild
Command::new(tauri_path)
.arg("--frontend-dir").arg(output_dir)
.spawn()?;Cross-platform webview
| Platform | Engine | Bundled? |
|---|---|---|
| Windows | WebView2 (Chromium) | Pre-installed on Win 11; installer handles Win 10 |
| macOS | WKWebView (WebKit) | Always available |
| Linux | WebKitGTK | Must be installed (apt install libwebkit2gtk-4.1-dev) |
Risk: Linux WebKitGTK fragmentation
Older Linux distros ship older webkit2gtk versions that may lack SharedArrayBuffer support. Mitigations:
- Require minimum webkit2gtk version in package dependencies
- Keep Flask+browser as a
--legacy-browserfallback for unsupported systems - Document the requirement
Existing frontend works as-is
The esbuild-built frontend (index.html, app.js, index.css) loads directly into Tauri webview. The tauri.conf.json points to the built frontend directory:
{
"build": {
"frontendDist": "../src/fastled/frontend/dist"
}
}Rust crate dependencies
| Need | Crate |
|---|---|
| CLI args | clap |
| File watching | notify |
| HTTP client | reqwest |
| Archive extraction | tar, zip, zstd |
| JSON | serde, serde_json |
| Async runtime | tokio |
| Error handling | thiserror, anyhow |
| Path manipulation | std::path + dunce (Windows UNC) |
| String matching | strsim |
| Progress bars | indicatif |
| Terminal input | crossterm |
| Python bridge | pyo3 (abi3-py310) |
| UI framework | tauri v2 |
| Hashing | sha2, blake3 |
| Process management | running-process-core |
CI setup (matching running-process)
sccache configuration
env:
CARGO_HOME: ${{ github.workspace }}/.cargo
RUSTUP_HOME: ${{ github.workspace }}/.rustup
SCCACHE_GHA_ENABLED: "true"
RUSTC_WRAPPER: sccache
steps:
- uses: mozilla-actions/sccache-action@v0.0.9
- uses: Swatinem/rust-cache@v2
with:
shared-key: fastled-${{ inputs.runs-on }}
cache-targets: falseReusable workflow templates
_build.yml-- build wheels + Tauri binaries_lint.yml--cargo fmt+cargo clippy+ruff_unit-test.yml--cargo test+pytest_integration-test.yml-- end-to-end compilation tests
Acceptance criteria
-
fastled --just-compile examples/Wasmworks via Rust CLI calling Python build subprocess -
fastled --app examples/Wasmopens a Tauri webview window (not system browser) -
pip install fastledstill works via PyO3 bridge - No Flask, no Playwright dependency for default usage
- CI builds on all 6 platform/arch combinations with sccache
- Startup time < 50ms (vs ~300-500ms Python)
- Single binary size < 15 MB (Tauri viewer) + < 5 MB (CLI)
Activity
feat: use Tauri viewer as default for --app mode