feat(cli): #242 fbuild ci — PlatformIO-compatible alias for compile-many

[zackees]

Summary

Adds fbuild ci as a drop-in replacement for pio ci that delegates to the two-stage compile-many primitive shipped in PR #241. Existing CI workflows can swap s/pio ci/fbuild ci/ without other changes.

Closes #242.

Flag mapping

fbuild ci flag	pio ci equivalent	Behavior
--board <b> / -b <b>	--board / -b	Required. Picks the platform orchestrator.
--lib <path> / -l <path> (repeatable)	--lib / -l	Mapped to PLATFORMIO_LIB_EXTRA_DIRS; ';' separated on Windows, ':' elsewhere.
--project-conf <path> / -c <path>	--project-conf / -c	Mapped to PLATFORMIO_PROJECT_CONFIG. Canonicalized when possible.
--keep-build-dir	--keep-build-dir	Accepted for compatibility; no-op.
--build-dir <path>	--build-dir	Accepted for compatibility; emits a warning, not yet honored.
--framework-jobs / --sketch-jobs / --quick / --release / --verbose (-v)	n/a	fbuild-native; see compile-many.
positional sketches	positional	Each entry may be a project dir or a .ino file (its parent dir is used).

Implementation notes

• CompileManyRequest grows a pio_env: HashMap<String, String> that threads through SketchBuildInputs into each per-sketch BuildParams.pio_env, so the lib/project-conf overrides reach the orchestrator unchanged.
• The CLI handler keeps the path-rewrite and env-build logic in small pure functions (normalize_ci_sketch_entry, normalize_ci_sketches, build_ci_pio_env) so they can be unit-tested without spawning a process.
• A new crates/fbuild-cli/build.rs reserves an 8 MiB stack for fbuild.exe on *-pc-windows-msvc (default is 1 MiB). The clap-generated arg parser now exceeds the default stack in Windows debug builds when rendering --help; release builds and other targets are unaffected.

Test plan

• uv run soldr cargo check --workspace --all-targets
• uv run soldr cargo clippy --workspace --all-targets -- -D warnings
• uv run soldr cargo fmt --all -- --check
• uv run soldr cargo test -p fbuild-cli (21 unit tests pass, 2 new integration tests pass, 3 pre-existing lib_select tests still pass)
• uv run soldr cargo test -p fbuild-build --test compile_many_two_stage (5 tests pass, request struct change is wired through)
• RUSTDOCFLAGS=-D warnings uv run soldr cargo doc -p fbuild-cli -p fbuild-build --no-deps
• fbuild ci --help shows the PIO-compatible flag surface with PIO terminology
• fbuild ci --board uno examples/Blink/Blink.ino is accepted (.ino -> parent dir)
• fbuild ci without --board/sketches exits non-zero with a clap usage error
• Existing fbuild compile-many ... invocation still works (handler signature extended with default-empty pio_env)

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features

  • Added fbuild ci command as a drop-in replacement for pio ci with PlatformIO-compatible flags
  • Support for library directory overlays and custom project configuration during builds

• Documentation

  • Updated CLI documentation with compile-many and ci subcommand usage and examples

• Chores

  • Improved Windows binary stack allocation for enhanced stability

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 33da0161-ecbe-4b8c-9f25-93d9f9661e09

📥 Commits

Reviewing files that changed from the base of the PR and between cdb986a and 3fc1978.

📒 Files selected for processing (7)

• crates/fbuild-build/src/compile_many.rs
• crates/fbuild-build/tests/compile_many_two_stage.rs
• crates/fbuild-cli/README.md
• crates/fbuild-cli/build.rs
• crates/fbuild-cli/src/main.rs
• crates/fbuild-cli/tests/README.md
• crates/fbuild-cli/tests/ci_command.rs

---

📝 Walkthrough

Walkthrough

This PR implements fbuild ci, a PlatformIO-compatible CLI command for CI builds. It threads a pio_env environment overlay through the existing two-stage compile_many pipeline, adds the ci subcommand with PlatformIO flags (--board, --lib, --project-conf), normalizes sketch paths, and validates the surface with integration tests and documentation.

Changes

fbuild ci — PlatformIO-compatible CI command

Layer / File(s)	Summary
pio_env field and threading through compile_many crates/fbuild-build/src/compile_many.rs, crates/fbuild-build/tests/compile_many_two_stage.rs	CompileManyRequest and SketchBuildInputs gain a pio_env: HashMap<String, String> field. The field is threaded through stage 1 and stage 2 build pipelines, passed to build_one_sketch, and applied to BuildParams.pio_env by the orchestrator. Test request construction updated to include the empty map.
fbuild ci subcommand and dispatch crates/fbuild-cli/src/main.rs	New Commands::Ci variant accepts --board, --lib (repeatable), --project-conf, parallelism flags, profile flags, and one-or-more sketch positional arguments. Argument rewriting recognizes ci for positional swapping. Main dispatcher normalizes sketches (.ino → parent dir, case-insensitive), builds a pio_env overlay from --lib and --project-conf with platform-specific separator and canonicalization, and forwards both into run_compile_many. Unit tests cover sketch normalization, env overlay construction, separator behavior, and clap validation.
Documentation, integration tests, and build setup crates/fbuild-cli/build.rs, crates/fbuild-cli/README.md, crates/fbuild-cli/tests/README.md, crates/fbuild-cli/tests/ci_command.rs	Windows MSVC linker stack reservation (8 MiB) added to build.rs. README updated to clarify CLI delegates "most work" to daemon, document fbuild ci as PlatformIO drop-in with flag mapping table and example invocation. Tests README documents new integration tests. ci_command.rs verifies clap validation: --board required, sketches required.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• FastLED/FastLED#2470: This PR implements the fbuild ci interface and pio_env threading that enables downstream libraries to switch from pio ci to fbuild ci.

Possibly related PRs

• FastLED/fbuild#241: The main PR extends the two-stage compile_many primitive introduced in #241 by adding environment overlay plumbing and the CLI surface to make it PlatformIO-compatible.

Poem

A CLI command takes the stage, fbuild ci is all the rage,
Threading env through build and sketch, PlatformIO's perfect match.
Normalize those .ino files, thread the stages with such style,
Drop-in switching, zero friction—that's the rabbit's new conviction! 🐰

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/issue-242-fbuild-ci

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch feat/issue-242-fbuild-ci

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[zackees]

Superseded by #248 which landed an equivalent change closing #242. Both PRs add the same failed to parse platformio.ini: config error: failed to read ci\platformio.ini: The system cannot find the file specified. (os error 2) PlatformIO-compatible alias and thread through . The two diverge only on the Windows-debug clap-help stack-overflow fix: this PR's link-arg approach is arguably cleaner than #248's runtime trampoline, so happy to fold that in as a follow-up if useful.