Skip to content

fix(packaging): pip install . bundles a stale pre-fix fastled.exe — setup.py reuses old binaries and pip wheel cache serves stale 2.0.10 wheels #165

Closed

Description

@zackees

Context

Even on a checkout that contains the viewer fix 0332caf (#157), pip install . still installs a binary with the old broken viewer, so the Tauri window shows "Not Found" forever (#151 symptom). Reproduced and root-caused on Windows, 2026-06-11, main@c69997e.

Forensic evidence (the pre-fix viewer contains the literal string fastled://localhost; current source has zero fastled:// references):

  1. Fresh pip install . from main@c69997e → installed site-packages\fastled\bin\fastled.exe contains fastled://localhost → stale pre-fix binary.
  2. Even pip install . --no-cache-dir --force-reinstall → still contains the marker.
  3. After deleting the stale tree artifacts and purging the pip cache, pip install . → marker gone (binary size changed 15043584 → 15137280). Viewer code is current.

Three stacked staleness layers, any one of which ships a broken binary:

  1. setup.py:74-76 — ensure_bundled_fastled_binary() early-returns if src/fastled/bin/fastled.exe already exists, with zero freshness/version check. A stale exe dated 2026-06-07 (pre-fix) was sitting in the working tree (it's a known untracked build artifact per CLAUDE.md) and got bundled into every wheel build. A stale copy also persists in build/lib.win-amd64-*/fastled/bin/.
  2. setup.py:43-70 — _copy_first_available_binary() harvests any pre-existing exe from target/*/release/ or ~/.cargo/bin/ instead of rebuilding, again with no check that it matches the current source.
  3. pip wheel cache — pip cache list fastled showed two cached fastled-2.0.10-py3-none-win_amd64.whl built from pre-fix source. Because Cargo.toml workspace.package.version is still 2.0.10 (unchanged since the broken v2.0.10 release), pip's name+version-keyed cache happily reuses the broken wheel on plain pip install ..

Net effect: the fix for #156/#151 is on main but effectively unshippable via pip install . on any machine that ever built/installed the pre-fix version.

Proposal

  1. Make setup.py never trust pre-existing binaries. When Cargo.toml is present (source build), always run soldr cargo build --release --bin fastled and copy the fresh artifact; delete/ignore any pre-existing src/fastled/bin/fastled[.exe] and stale build/lib*/fastled/bin/ copies first. Keep the harvest path only for environments that genuinely cannot build (and fail loud per repo conventions, don't silently grab ~/.cargo/bin). Alternatively/additionally: embed the git commit hash into the binary (build script + --version output) and have setup.py reject a candidate binary whose hash doesn't match git rev-parse HEAD.
  2. Bump workspace.package.version to 2.0.11 so pip's wheel cache key changes (this also unblocks the release tracked in release: cut v2.0.11 with viewer fix #157 + add viewer-wiring regression gate #160). Going forward, any user-visible fix must bump the version, otherwise layer 3 re-bites.
  3. Add a viewer console log hook so future viewer bugs are diagnosable: a FASTLED_VIEWER_LOGS=1 env var (or --viewer-logs <file>) that injects a Tauri initialization_script in crates/fastled-cli/src/tauri_viewer.rs forwarding console.*, window.onerror, and failed fetches to stderr/a log file. Today the viewer has no console/devtools capture at all.

Step-by-step reproduction (pre-fix state)

On a machine that previously built/installed fastled before 0332caf:

cd ~/dev/fastled-wasm
pip install .
python -c "from fastled._rust_cli import find_rust_fastled_cli as f; print(f())"
# scan the printed exe for the pre-fix marker:
# [System.Text.Encoding]::ASCII.GetString([IO.File]::ReadAllBytes($exe)).Contains('fastled://localhost')  -> True = stale
cd ~/dev/fastled
Remove-Item -Recurse -Force examples\wasm\fastled_js   # clear browser artifacts
fastled examples\wasm
# Tauri window shows bare "Not Found" forever, even though the compile succeeds
# and http://127.0.0.1:<port> serves the sketch fine in a regular browser.

Thorough test plan (acceptance verification)

  1. Staleness layer 1: plant a dummy/old src/fastled/bin/fastled.exe, run pip install ., assert the installed exe is freshly built (no fastled://localhost marker; or matching embedded git hash).
  2. Staleness layer 2: with src/fastled/bin empty but a stale exe in target/release/ and ~/.cargo/bin/, run pip install ., assert fresh build wins.
  3. Staleness layer 3: pip cache list fastled after version bump must not resolve to a 2.0.10 wheel; plain pip install . (no flags) on a machine with the old cached wheel must install the fixed binary.
  4. End-to-end (the original complaint): pip install . → cd ~/dev/fastled → delete examples/wasm/fastled_js → fastled examples/wasm → Tauri viewer must show the loading/build page and then the running sketch, never a bare "Not Found". Use the new viewer log hook to capture console output and attach it if anything fails.
  5. bash test and soldr cargo test --workspace pass; add a unit test asserting ensure_bundled_fastled_binary() does not reuse a stale binary (e.g. hash-mismatch path).

Acceptance criteria

  • pip install . from a fixed checkout on a machine with stale artifacts (tree exe, build/lib exe, target exe, cargo-bin exe, pip-cached wheel) installs a binary built from the current source.
  • Version bumped to 2.0.11 in Cargo.toml (coordinates with release: cut v2.0.11 with viewer fix #157 + add viewer-wiring regression gate #160).
  • Viewer console/error log hook exists and is documented (env var or flag).
  • E2E repro above shows loading page → sketch in the Tauri viewer.
  • Regression tests cover the setup.py staleness paths.

Decisions

  • Priority: P1 — same blast radius as release: cut v2.0.11 with viewer fix #157 + add viewer-wiring regression gate #160: every pip install . on a previously-used dev machine silently ships the broken viewer; users cannot self-fix without knowing about three hidden caches.
  • Scope: packaging (setup.py) + version bump + viewer log hook. The viewer code fix itself is already merged (fix: Tauri viewer loads the HTTP server URL instead of serving files from disk #157) and verified correct when freshly built.
  • Fix location guess: setup.py (ensure_bundled_fastled_binary, _copy_first_available_binary), Cargo.toml version, crates/fastled-cli/src/tauri_viewer.rs for the log hook.
  • Workaround documented for users hitting this today: delete src/fastled/bin/fastled.exe + build/, run pip cache remove fastled, then pip install . --force-reinstall --no-deps. Verified working.
  • Implementing agent: fable-5 with xhigh reasoning effort (per maintainer request).

Related issues

Activity

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