Skip to content

Bundle the Rust fastled CLI binary into the wheel; never cargo-build it in install/CI #67

Closed

Description

@zackees

Context

PR #65 fixed the helper that locates the Rust fastled binary, but the binary still has to be materialised somewhere the helper can find it. Currently it isn't:

  • cargo binstall fastled-cli fails (no published release yet).
  • cargo test --workspace produces a test binary at target/<arch>/debug/deps/fastled-<hash> but not always the regular target/<arch>/debug/fastled[.exe].
  • The deploy (Build Webpage) workflow never runs cargo test.

PR #66 is the current band-aid — it tacks cargo build --release --bin fastled onto ./install, so the binary materialises during install. That works, but it bakes a multi-minute Rust compile into every install, every CI job, and every dev ./install. We should never compile fastled from source as part of installing the Python package.

The right fix

Use Python's first-class mechanism for shipping a native binary in a wheel: the <pkg>-<ver>.data/scripts/<name> slot, which pip extracts to the venv's Scripts/ (or bin/) at install time. maturin builds this directly when a project has both a [lib] (cdylib) target and one or more [[bin]] targets.

After the change:

  1. pip install fastled (or the wheel built from this repo) drops the Rust fastled[.exe] straight into .venv/Scripts/. No Python shim with the same name. No cargo build during install.
  2. _find_rust_fastled_cli becomes a one-liner: Path(shutil.which(\"fastled\")) returns the Rust binary directly.
  3. ./install drops the cargo build --release --bin fastled step (PR fix(ci): build the Rust fastled CLI from source when binstall fails #66's band-aid).
  4. CI's unit-test + deploy jobs work without any extra Rust step.

Concrete plan

  1. Refactor crates/fastled-cli to expose a library entry point (pub fn run() -> std::process::ExitCode) by moving the body of main.rs into lib.rs. crates/fastled-cli/src/main.rs shrinks to fn main() -> ExitCode { fastled_cli::run() }.

  2. Add a [[bin]] to crates/fastled-py/Cargo.toml:

    [[bin]]
    name = "fastled"
    path = "src/bin/fastled.rs"
    
    [dependencies]
    pyo3 = { workspace = true }
    fastled-cli = { path = "../fastled-cli" }

    crates/fastled-py/src/bin/fastled.rs:

    fn main() -> std::process::ExitCode { fastled_cli::run() }
  3. Drop fastled = \"fastled.cli:main\" from [project.scripts] in pyproject.toml (keep fled and fastled-wasm if we still want Python entry-points for those names — but actually those collide too, so probably drop them as well and add them as additional [[bin]] targets).

  4. Delete the install-side cargo build --release --bin fastled fallback added in PR fix(ci): build the Rust fastled CLI from source when binstall fails #66 once this lands.

  5. Sanity: pip install -e . is editable mode, which doesn't run maturin's wheel-build path. Editable installs still need ./install to materialise the binary somehow — leave the cargo-build fallback active only when MATURIN_PEP517_ARGS indicates editable mode, or just keep a cargo-build call as a dev-only path.

Verification

  • bash lint clean.
  • bash test — 119 unit tests pass without any cargo-build step.
  • Build a wheel (uv run maturin build --release), pip install it into a fresh venv, run which fastled, confirm it's the Rust binary and fastled --version matches.
  • CI unit-test + deploy jobs green without the install-script fallback.

Out of scope

  • fastled-viewer (Tauri) bundling — also a Rust bin; same approach if/when desired, but separate PR.
  • Publishing pre-built wheels — orthogonal.

Activity

  1. added a commit that references this issue on May 13, 2026
    838c8da
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions