Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .claude/settings.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@
"hooks": [
{
"type": "command",
"command": "uv run python ci/hooks/tool_guard.py",
"timeout": 5
"command": "ci/hooks/tool_guard",
"timeout": 10
}
]
}
Expand Down
24 changes: 22 additions & 2 deletions .codex/hooks.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,28 @@
"hooks": [
{
"type": "command",
"command": "uv run python ci/hooks/tool_guard.py",
"timeout": 5
"command": "ci/hooks/tool_guard",
"timeout": 10
}
]
},
{
"matcher": "shell_command",
"hooks": [
{
"type": "command",
"command": "ci/hooks/tool_guard",
"timeout": 10
}
]
},
{
"matcher": "functions.shell_command",
"hooks": [
{
"type": "command",
"command": "ci/hooks/tool_guard",
"timeout": 10
}
]
}
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/_integration-test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,8 @@ jobs:
- name: Install
run: ./install

- name: Integration Tests
run: uv run pytest -x -v -s tests/integration
- name: Native Test Suite
run: ./test

- name: Upload failure logs
if: failure()
Expand Down
34 changes: 0 additions & 34 deletions .github/workflows/build_webpage.yml

This file was deleted.

11 changes: 10 additions & 1 deletion .github/workflows/publish_release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,16 @@ jobs:
shell: bash

- name: Build executable
run: uv run build_exe.py
shell: bash
run: |
soldr cargo build --release --bin fastled-rs
mkdir -p dist
if [[ "$RUNNER_OS" == "Windows" ]]; then
cp target/release/fastled-rs.exe dist/fastled.exe
else
cp target/release/fastled-rs dist/fastled
chmod +x dist/fastled
fi

# Add signing step for Windows
- name: Decode and Sign Executable (Windows Only)
Expand Down
70 changes: 29 additions & 41 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,69 +1,57 @@
# Agent Instructions

This file is read by Claude Code, Codex, and other coding agents that work on this repo. Codex agents should also see `CODEX.md` — that file is a single-line pointer back here so both agents read the same playbook.
This file is read by Claude Code, Codex, and other coding agents that work on this repo. Codex agents should also see `CODEX.md`, which points back here.

## Layout

- Python package: `src/fastled/`
- Python package shim: `src/fastled/`
- Rust workspace: `crates/fastled-cli`, `crates/fastled-py`, `crates/fastled-tauri`
- Tests: `tests/unit/` (Python), `cargo test --workspace` (Rust)
- Tests: `tests/unit/` (thin Python API smoke tests), `cargo test --workspace` (Rust)
- CI workflows: `.github/workflows/_*.yml`
- Dev scripts: `./install`, `./lint`, `./test`, `./build-wheel`, `./clean`

## Build cache — use soldr + zccache
## Build Cache

This project uses **soldr** (build orchestrator) + **zccache** (compile cache). They are NOT optional for local Rust builds: a clean `cargo build -p fastled-py` recompiles PyO3 + reqwest + tokio + axum + clap from scratch and takes 8–10 minutes. With soldr/zccache the same build hits the cache and finishes in seconds.
Use `soldr cargo ...`, `soldr rustfmt ...`, and related soldr-wrapped commands for Rust work. Plain `cargo`, `rustc`, and `rustfmt` bypass zccache and are blocked by `ci/hooks/tool_guard.py`.

- Binaries live at `/c/tools/python13/Scripts/{soldr,zccache}` on Windows, or wherever `uv pip install soldr` placed them.
- `soldr` wraps `cargo` and automatically uses `zccache` as `RUSTC_WRAPPER`.
- CI installs soldr via `zackees/setup-soldr@v0` (see workflows). Local dev should match.
If `soldr` is not on PATH, install it with `uv tool install soldr`.

**When you invoke any Rust tool from an agent, use `soldr cargo …`, `soldr rustfmt …`, etc.** Plain `cargo` / `rustc` / `rustfmt` are blocked by the PreToolUse hook (`ci/hooks/tool_guard.py`) — they bypass zccache and turn a 30-second incremental build into a 10-minute cold build. The legacy `./_cargo`, `./_rustc`, `./_rustfmt` trampolines were retired in #76; the hook explicitly rejects them too.
## Tests

If `soldr` is not on PATH, install it with `uv tool install soldr` (or see `zackees/soldr` on GitHub).
`bash test` runs the Python API smoke tests plus the Rust workspace tests. End-to-end WASM compiles should be run only when the change touches the native build backend.

## Tests are slow — pick a narrow set

`bash test` runs the full pytest + cargo test suite. Some unit tests (`tests/unit/test_cli.py`, `tests/unit/test_build_service.py`) perform real WASM compiles via emscripten and can take 10+ minutes each.

For iterative work, run targeted tests:

```bash
uv run pytest tests/unit/test_string_diff.py tests/unit/test_select_sketch_directory.py -v
```

Skip `test_cli.py` unless you actually need to validate end-to-end WASM output:
For iterative work:

```bash
uv run pytest tests/unit --ignore=tests/unit/test_cli.py -v
uv run pytest tests/unit/test_python_api.py -v
soldr cargo test --workspace
```

**Do not pipe pytest through `| tail -N`** if you want streaming output — it buffers until pytest exits, and a multi-minute pytest looks indistinguishable from a hang. Redirect to a file or use `-v`.
Do not pipe pytest through `| tail -N` if you want streaming output; it buffers until pytest exits.

## Architecture notes
## Architecture Notes

- The user-facing CLI is the Rust binary `fastled` (built from `crates/fastled-cli`, bundled into the wheel via `[tool.maturin] data`). Python `cli.py` / `app.py` are 15-line shims that call `fastled._rust_cli.invoke_rust_fastled_cli`.
- `fastled._native` is the PyO3 extension compiled from `crates/fastled-py/src/lib.rs`. It exposes Rust functions to Python (sketch discovery, build service, project init, string diff, frontend bundling, …).
- The compile path is Rust-owned: `crates/fastled-cli/src/build.rs` re-exports the native WASM backend in `crates/fastled-cli/src/wasm_build.rs`. Python `BuildService` / `EmscriptenToolchain` are compatibility facades over `fastled._native.NativeBuildService`.
- For PyO3 changes, after `cargo build -p fastled-py` the new `.dll` lands in `target/maturin/_native.dll`. `maturin develop` copies that to `src/fastled/_native.pyd`. If `_native.pyd` is locked by other Python processes (common on Windows), use the move-aside trick: `mv src/fastled/_native.pyd src/fastled/_native.pyd.old && cp target/maturin/_native.dll src/fastled/_native.pyd`. Remember to delete the `.pyd.old` before committing.
- The user-facing CLI is the Rust binary `fastled`/`fastled-rs` built from `crates/fastled-cli`.
- Python `cli.py` and `app.py` are tiny shims that call `fastled._rust_cli.invoke_rust_fastled_cli`.
- `fastled._native` is the PyO3 extension compiled from `crates/fastled-py/src/lib.rs`. It exposes the public Python API classes and functions directly from Rust.
- The compile path is Rust-owned through `crates/fastled-cli/src/build.rs` and `crates/fastled-cli/src/wasm_build.rs`.
- Python no longer owns build, toolchain, sketch selection, project init, install, server, debug-symbol, or frontend-bundling orchestration.

## Conventions

- Lint command: `bash lint` — runs cargo fmt + clippy, then ruff/black/isort/pyright. Must be green before commit.
- Test command: `bash test` (or targeted subset; see above).
- Cross-platform pyright warnings about `sys.platform` are expected — don't chase them.
- Always fix all diagnostics found, even pre-existing ones not caused by current changes, before declaring a change complete.
- Prefer native (Rust) implementations and fail-loud over silent Python fallbacks. The migration tracked in #14/#71/#72/#73 is moving everything in this direction.
- Don't add backwards-compat hacks for code paths that no longer exist (e.g. unused `_var` renames, "removed" comments).
- Lint command: `bash lint`.
- Test command: `bash test` or targeted subsets above.
- Prefer native Rust implementations and fail-loud behavior over silent Python fallbacks.
- Do not add backwards-compat hacks for code paths that no longer exist.

## Common gotchas
## Common Gotchas

- The installed `fastled` CLI on PATH (e.g. `/c/tools/python13/Scripts/fastled.exe`) may be a Python compatibility shim or stale script; the Rust CLI binary is named `fastled-rs[.exe]` during the migration. If a CLI test fails, check `uv run python -c "from fastled._rust_cli import find_rust_fastled_cli; print(find_rust_fastled_cli())"`.
- Error messages from the Rust CLI go to **stderr**. Tests asserting `result.stdout` for error text should use `result.stdout + result.stderr` (the parse_args.py removal in #72 exposed this).
- `tasklist` on Windows may report tens of thousands of `python.exe` zombies — most are stale tasklist artifacts, not real processes. `ps -ef | grep python` is more reliable for live ones.
- The installed `fastled` CLI on PATH may be a Python compatibility shim or stale script; during migration the Rust CLI binary is named `fastled-rs[.exe]`.
- Error messages from the Rust CLI go to stderr.
- On Windows, if `_native.pyd` is locked after a PyO3 build, move it aside before copying the newly built extension into `src/fastled/`.

## Filing issues / PRs
## Filing Issues / PRs

- `gh issue create --repo zackees/fastled-wasm …`
- `gh pr create …`
- `gh issue create --repo zackees/fastled-wasm ...`
- `gh pr create ...`
- Reference the originating issue (`Refs #72`) in commits/PRs when applicable.
34 changes: 0 additions & 34 deletions DEBUGGER.md

This file was deleted.

1 change: 0 additions & 1 deletion MANIFEST.in
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
include pyproject.toml
include requirements.testing.txt
include template_python_cmd/assets/example.txt
include src/fastled/assets/localhost.pem
include src/fastled/assets/localhost-key.pem
recursive-include src/fastled/frontend *.ts *.js *.css *.html *.json *.d.ts *.h *.ttf *.map
12 changes: 2 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@
| **macOS x86** | [![macOS x86 Build](https://github.com/zackees/fastled-wasm/actions/workflows/macos-x86-build.yml/badge.svg)](https://github.com/zackees/fastled-wasm/actions/workflows/macos-x86-build.yml) | [![macOS x86 Lint](https://github.com/zackees/fastled-wasm/actions/workflows/macos-x86-lint.yml/badge.svg)](https://github.com/zackees/fastled-wasm/actions/workflows/macos-x86-lint.yml) | [![macOS x86 Unit Test](https://github.com/zackees/fastled-wasm/actions/workflows/macos-x86-unit-test.yml/badge.svg)](https://github.com/zackees/fastled-wasm/actions/workflows/macos-x86-unit-test.yml) | [![macOS x86 Integration Test](https://github.com/zackees/fastled-wasm/actions/workflows/macos-x86-integration-test.yml/badge.svg)](https://github.com/zackees/fastled-wasm/actions/workflows/macos-x86-integration-test.yml) |
| **macOS ARM** | [![macOS ARM Build](https://github.com/zackees/fastled-wasm/actions/workflows/macos-arm-build.yml/badge.svg)](https://github.com/zackees/fastled-wasm/actions/workflows/macos-arm-build.yml) | [![macOS ARM Lint](https://github.com/zackees/fastled-wasm/actions/workflows/macos-arm-lint.yml/badge.svg)](https://github.com/zackees/fastled-wasm/actions/workflows/macos-arm-lint.yml) | [![macOS ARM Unit Test](https://github.com/zackees/fastled-wasm/actions/workflows/macos-arm-unit-test.yml/badge.svg)](https://github.com/zackees/fastled-wasm/actions/workflows/macos-arm-unit-test.yml) | [![macOS ARM Integration Test](https://github.com/zackees/fastled-wasm/actions/workflows/macos-arm-integration-test.yml/badge.svg)](https://github.com/zackees/fastled-wasm/actions/workflows/macos-arm-integration-test.yml) |

[![Build Webpage](https://github.com/zackees/fastled-wasm/actions/workflows/build_webpage.yml/badge.svg)](https://github.com/zackees/fastled-wasm/actions/workflows/build_webpage.yml)
[![Publish Release](https://github.com/zackees/fastled-wasm/actions/workflows/publish_release.yml/badge.svg)](https://github.com/zackees/fastled-wasm/actions/workflows/publish_release.yml)

## Compile your FastLED sketch and run it on the browser!
Expand Down Expand Up @@ -71,10 +70,9 @@ Useful flags:
| Flag | Description |
|------|-------------|
| `--just-compile` | Compile and exit without opening a browser or watching files |
| `--debug` | Build with debug artifacts for browser DWARF debugging |
| `--debug` | Build with debug-friendly compiler settings |
| `--quick` | Default build mode |
| `--release` | Optimized build (~1/3 smaller binary) |
| `--app` | Launch local preview in the Tauri-based native viewer |
| `--fastled-path <path>` | Point the build at a local FastLED checkout |
| `--purge` | Clear cached FastLED downloads and stale WASM build artifacts |
| `--serve-dir <dir>` | Serve an existing directory without compiling |
Expand All @@ -97,18 +95,12 @@ For an example see `examples/SdCard` in the FastLED repo.

### Compile Speed

Three compile modes are available: `--quick` (default), `--release` (optimized for size, ~1/3 smaller binary), and `--debug` (includes DWARF symbols for browser step-through debugging). Aggressive object caching means incremental rebuilds are near-instant.
Three compile modes are available: `--quick` (default), `--release` (optimized for size, ~1/3 smaller binary), and `--debug` (debug-friendly compiler settings). Aggressive object caching means incremental rebuilds are near-instant.

### Arduino Compatibility

Most simple Arduino sketches compile out of the box. Common functions like `digitalWrite()`, `Serial.println()`, and others are stubbed. `digitalRead()` returns 0 and `analogRead()` returns random numbers.

## Debugging

`fastled --debug --app` serves the local preview and exposes `/dwarfsource` resolution so browser devtools can map DWARF paths back to sketch, FastLED, and EMSDK source files.

For setup details see [DEBUGGER.md](DEBUGGER.md).

## HTTPS

The local preview server supports HTTPS using the bundled localhost certificate pair. HTTPS is required for browser features such as microphone access. See [HTTPS_SSL.md](HTTPS_SSL.md).
Expand Down
55 changes: 0 additions & 55 deletions build_exe.py

This file was deleted.

20 changes: 0 additions & 20 deletions build_site.py

This file was deleted.

6 changes: 4 additions & 2 deletions ci/hooks/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,10 @@ Python scripts invoked by Claude Code and Codex hooks. Claude Code loads the
hook config from `.claude/settings.json`; Codex loads the migrated config from
`.codex/hooks.json`.

All hooks run via `uv run python ci/hooks/<name>.py` so they share the project
Python environment.
Hooks run through `ci/hooks/tool_guard`, not `uv run python`. The wrapper uses
`python` on Windows, including Git Bash/MSYS/Cygwin, and `python3` on
macOS/Linux. They are intentionally stdlib-only so PreToolUse checks do not
trigger a uv sync or a native-extension rebuild before every tool call.

## Hooks

Expand Down
9 changes: 9 additions & 0 deletions ci/hooks/tool_guard
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
#!/bin/sh
case "$(uname -s 2>/dev/null || echo unknown)" in
MINGW*|MSYS*|CYGWIN*)
exec python ci/hooks/tool_guard.py
;;
*)
exec python3 ci/hooks/tool_guard.py
;;
esac
2 changes: 2 additions & 0 deletions ci/hooks/tool_guard.cmd
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
@echo off
python ci\hooks\tool_guard.py
Loading
Loading