Integrate soldr into build workflows

.github/workflows/check-macos.yml

@@ -16,21 +16,34 @@ jobs:
     runs-on: macos-latest
     steps:
       - uses: actions/checkout@v6
+      - uses: actions/checkout@v6
+        with:
+          repository: zackees/soldr
+          ref: v0.7.4
+          path: soldr
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
       - uses: dtolnay/rust-toolchain@stable
         with:
           components: clippy, rustfmt
-      - name: Setup zccache
-        uses: zackees/zccache@main
-        with:
-          shared-key: ${{ runner.os }}-check
+      - name: Install soldr bootstrap
+        shell: bash
+        run: python -m pip install soldr==0.7.4
+      - name: Build soldr from source
+        shell: bash
+        working-directory: soldr
+        run: soldr cargo build --package soldr-cli --release --locked
+      - name: Add soldr to PATH
+        shell: bash
+        run: echo "${{ github.workspace }}/soldr/target/release" >> "$GITHUB_PATH"
 
       - name: Check
-        run: cargo check --workspace --all-targets
+        shell: bash
+        run: soldr cargo check --workspace --all-targets
       - name: Clippy
-        run: cargo clippy --workspace --all-targets -- -D warnings
+        shell: bash
+        run: soldr cargo clippy --workspace --all-targets -- -D warnings
       - name: Test
-        run: cargo test --workspace
-
-      - name: Cleanup zccache
-        if: always()
-        uses: zackees/zccache/action/cleanup@main
+        shell: bash
+        run: soldr cargo test --workspace

.github/workflows/check-ubuntu.yml

@@ -19,18 +19,15 @@ jobs:
       - uses: dtolnay/rust-toolchain@stable
         with:
           components: clippy, rustfmt
-      - name: Setup zccache
-        uses: zackees/zccache@main
-        with:
-          shared-key: ${{ runner.os }}-check
+      - name: Install soldr 0.7.4
+        shell: bash
+        run: |
+          curl -fsSL https://raw.githubusercontent.com/zackees/soldr/v0.7.4/install.sh | bash -s -- --version 0.7.4
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
 
       - name: Check
-        run: cargo check --workspace --all-targets
+        run: soldr cargo check --workspace --all-targets
       - name: Clippy
-        run: cargo clippy --workspace --all-targets -- -D warnings
+        run: soldr cargo clippy --workspace --all-targets -- -D warnings
       - name: Test
-        run: cargo test --workspace
-
-      - name: Cleanup zccache
-        if: always()
-        uses: zackees/zccache/action/cleanup@main
+        run: soldr cargo test --workspace

.github/workflows/check-windows.yml

@@ -16,21 +16,34 @@ jobs:
     runs-on: windows-latest
     steps:
       - uses: actions/checkout@v6
+      - uses: actions/checkout@v6
+        with:
+          repository: zackees/soldr
+          ref: v0.7.4
+          path: soldr
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
       - uses: dtolnay/rust-toolchain@stable
         with:
           components: clippy, rustfmt
-      - name: Setup zccache
-        uses: zackees/zccache@main
-        with:
-          shared-key: ${{ runner.os }}-check
+      - name: Install soldr bootstrap
+        shell: bash
+        run: python -m pip install soldr==0.7.4
+      - name: Build soldr from source
+        shell: bash
+        working-directory: soldr
+        run: soldr cargo build --package soldr-cli --release --locked
+      - name: Add soldr to PATH
+        shell: bash
+        run: echo "${{ github.workspace }}/soldr/target/release" >> "$GITHUB_PATH"
 
       - name: Check
-        run: cargo check --workspace --all-targets
+        shell: bash
+        run: soldr cargo check --workspace --all-targets
       - name: Clippy
-        run: cargo clippy --workspace --all-targets -- -D warnings
+        shell: bash
+        run: soldr cargo clippy --workspace --all-targets -- -D warnings
       - name: Test
-        run: cargo test --workspace
-
-      - name: Cleanup zccache
-        if: always()
-        uses: zackees/zccache/action/cleanup@main
+        shell: bash
+        run: soldr cargo test --workspace

.github/workflows/docs.yml

@@ -15,14 +15,11 @@ jobs:
     steps:
       - uses: actions/checkout@v6
       - uses: dtolnay/rust-toolchain@stable
-      - name: Setup zccache
-        uses: zackees/zccache@main
-        with:
-          shared-key: docs
+      - name: Install soldr 0.7.4
+        shell: bash
+        run: |
+          curl -fsSL https://raw.githubusercontent.com/zackees/soldr/v0.7.4/install.sh | bash -s -- --version 0.7.4
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
 
       - name: Build docs
-        run: cargo doc --workspace --no-deps
-
-      - name: Cleanup zccache
-        if: always()
-        uses: zackees/zccache/action/cleanup@main
+        run: soldr cargo doc --workspace --no-deps

.github/workflows/fmt.yml

@@ -15,5 +15,10 @@ jobs:
       - uses: dtolnay/rust-toolchain@stable
         with:
           components: rustfmt
+      - name: Install soldr 0.7.4
+        shell: bash
+        run: |
+          curl -fsSL https://raw.githubusercontent.com/zackees/soldr/v0.7.4/install.sh | bash -s -- --version 0.7.4
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
       - name: Check formatting
-        run: cargo fmt --all -- --check
+        run: soldr cargo fmt --all -- --check

.github/workflows/msrv.yml

@@ -13,14 +13,11 @@ jobs:
     steps:
       - uses: actions/checkout@v6
       - uses: dtolnay/rust-toolchain@1.75.0
-      - name: Setup zccache
-        uses: zackees/zccache@main
-        with:
-          shared-key: msrv
+      - name: Install soldr 0.7.4
+        shell: bash
+        run: |
+          curl -fsSL https://raw.githubusercontent.com/zackees/soldr/v0.7.4/install.sh | bash -s -- --version 0.7.4
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
 
       - name: Check MSRV
-        run: cargo check --workspace
-
-      - name: Cleanup zccache
-        if: always()
-        uses: zackees/zccache/action/cleanup@main
+        run: soldr cargo check --workspace

.github/workflows/template_build.yml

@@ -32,13 +32,17 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v6
 
-      - name: Install Rust toolchain
+      - name: Install pinned Rust toolchain
         uses: dtolnay/rust-toolchain@stable
-
-      - name: Setup zccache
-        uses: zackees/zccache@main
         with:
-          shared-key: ${{ runner.os }}-${{ inputs.env-name }}
+          toolchain: 1.94.1
+          components: clippy, rustfmt
+
+      - name: Install soldr 0.7.4
+        shell: bash
+        run: |
+          curl -fsSL https://raw.githubusercontent.com/zackees/soldr/v0.7.4/install.sh | bash -s -- --version 0.7.4
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
 
       - name: Restore fbuild toolchains
         uses: actions/cache/restore@v5
@@ -68,7 +72,7 @@ jobs:
 
       - name: Build fbuild binaries
         run: |
-          cargo build -p fbuild-cli -p fbuild-daemon
+          soldr cargo build -p fbuild-cli -p fbuild-daemon
 
       - name: Add fbuild to PATH
         run: echo "${{ github.workspace }}/target/debug" >> $GITHUB_PATH
@@ -89,10 +93,6 @@ jobs:
           test -f ${{ inputs.test-dir }}/.fbuild/build/${{ inputs.env-name }}/release/firmware.${{ inputs.firmware-ext }}
           echo "Release build successful - firmware.${{ inputs.firmware-ext }} generated"
 
-      - name: Cleanup zccache
-        if: always()
-        uses: zackees/zccache/action/cleanup@main
-
       - name: Save fbuild toolchains
         if: always()
         uses: actions/cache/save@v5

.github/workflows/template_native_build.yml

@@ -46,24 +46,39 @@ jobs:
         with:
           ref: ${{ inputs.ref || github.sha }}
 
+      - uses: actions/checkout@v6
+        with:
+          repository: zackees/soldr
+          ref: v0.7.4
+          path: soldr
+
       - uses: dtolnay/rust-toolchain@stable
         with:
+          toolchain: 1.94.1
+          components: clippy, rustfmt
           targets: ${{ inputs.target }}
 
-      # rust-toolchain.toml pins 1.94.1 which overrides the above;
-      # ensure the target stdlib is installed for the pinned toolchain too
-      - name: Add Rust target
-        run: rustup target add ${{ inputs.target }}
-
       - uses: actions/setup-python@v6
-        if: ${{ !inputs.linux_cross && !inputs.macos_cross || inputs.linux_cross }}
         with:
           python-version: "3.13"
 
-      - name: Setup zccache
-        uses: zackees/zccache@main
-        with:
-          shared-key: ${{ inputs.target }}
+      - name: Install soldr bootstrap
+        shell: bash
+        run: python -m pip install soldr==0.7.4
+
+      - name: Build soldr from source
+        shell: bash
+        working-directory: soldr
+        run: soldr cargo build --package soldr-cli --release --locked
+
+      - name: Add soldr to PATH
+        shell: bash
+        run: echo "${{ github.workspace }}/soldr/target/release" >> "$GITHUB_PATH"
+
+      # rust-toolchain.toml pins 1.94.1 which overrides the above;
+      # ensure the target stdlib is installed for the pinned toolchain too
+      - name: Add Rust target
+        run: rustup target add ${{ inputs.target }}
 
       # Linux musl toolchain (libudev is auto-excluded for musl targets by serialport)
       - name: Install Linux dependencies
@@ -85,11 +100,11 @@ jobs:
         shell: bash
         run: |
           if [ "${{ inputs.linux_cross }}" = "true" ]; then
-            cargo-zigbuild build --release --target ${{ inputs.target }} -p fbuild-cli
-            cargo-zigbuild build --release --target ${{ inputs.target }} -p fbuild-daemon
+            soldr cargo zigbuild --release --target ${{ inputs.target }} -p fbuild-cli
+            soldr cargo zigbuild --release --target ${{ inputs.target }} -p fbuild-daemon
           else
-            cargo build --release --target ${{ inputs.target }} -p fbuild-cli
-            cargo build --release --target ${{ inputs.target }} -p fbuild-daemon
+            soldr cargo build --release --target ${{ inputs.target }} -p fbuild-cli
+            soldr cargo build --release --target ${{ inputs.target }} -p fbuild-daemon
           fi
 
       # PyO3 extension — built for ALL targets, including cross-compiled.
@@ -112,17 +127,17 @@ jobs:
             ARCH="${TARGET%%-*}"
             PYO3_TARGET="${ARCH}-unknown-linux-gnu"
             rustup target add "$PYO3_TARGET"
-            PYO3_NO_PYTHON=1 cargo-zigbuild build --release \
+            PYO3_NO_PYTHON=1 soldr cargo zigbuild --release \
               --target "${PYO3_TARGET}.2.17" -p fbuild-python \
               --features extension-module
           elif [ "${{ inputs.macos_cross }}" = "true" ]; then
-            PYO3_NO_PYTHON=1 cargo build --release \
+            PYO3_NO_PYTHON=1 soldr cargo build --release \
               --target ${{ inputs.target }} -p fbuild-python \
               --features extension-module
           elif [ "${{ runner.os }}" = "macOS" ]; then
-            cargo build --release -p fbuild-python --features extension-module
+            soldr cargo build --release -p fbuild-python --features extension-module
           else
-            cargo build --release -p fbuild-python --features extension-module
+            soldr cargo build --release -p fbuild-python --features extension-module
           fi
 
       - name: Stage artifacts
@@ -175,7 +190,3 @@ jobs:
           name: binaries-${{ inputs.target }}
           path: staging/
           if-no-files-found: error
-
-      - name: Cleanup zccache
-        if: always()
-        uses: zackees/zccache/action/cleanup@main

CLAUDE.md

@@ -4,7 +4,7 @@ fbuild is a PlatformIO-compatible embedded build tool (11 crates). See @docs/CLA
 
 ## Essential Rules
 
-- **Always use `uv run`, `soldr`, or `_cargo`/`_rustc`/`_rustfmt` trampolines to execute Rust commands.** Bare cargo/rustc are blocked by hook. All three forms resolve through [soldr](https://github.com/zackees/soldr), which uses `rustup which` to pick the rustup-managed toolchain; the cargo path adds `--no-cache` so the previous bare-cargo semantics are preserved.
+- **Always use `uv run`, `soldr`, or `_cargo`/`_rustc`/`_rustfmt` trampolines to execute Rust commands.** Bare cargo/rustc are blocked by hook. All three forms resolve through [soldr](https://github.com/zackees/soldr), which uses `rustup which` to pick the rustup-managed toolchain. The standard Cargo path is `soldr cargo ...`; do not add repo-specific `RUSTC_WRAPPER` wiring for normal builds.
 - **Always use `uv` for Python.** Bare `python`/`pip` are blocked by hook. Use `uv run ...` or `uv pip ...`.
 - MSRV: 1.75 | Edition: 2021 | Toolchain: 1.94.1 pinned in `rust-toolchain.toml` (clippy + rustfmt)
 - CI: Linux, macOS, Windows. All warnings denied (`RUSTFLAGS="-D warnings"`)
@@ -36,9 +36,6 @@ uv run cargo run -p fbuild-cli -- test-emu tests/platform/mega -e megaatmega2560
 ./_cargo clippy --workspace --all-targets -- -D warnings
 ./_rustfmt --check <file.rs>
 
-# Local zccache setup (optional, configures rustc-wrapper)
-uv run python ci/zccache_setup.py
-
 # Board definition management
 uv run python ci/validate_boards.py                    # validate against PlatformIO
 uv run python ci/validate_boards.py --external         # compare against Arduino + Zephyr
@@ -61,6 +58,12 @@ uv run python ci/build_dist.py --ref main
 ./publish
 ```
 
+Optional wrapper-mode only; do not use for standard soldr builds:
+
+```bash
+uv run python ci/zccache_setup.py  # writes rustc-wrapper = "zccache"
+```
+
 ## Hooks (enforced automatically)
 
 All hooks are Python scripts in `ci/hooks/`, invoked via `uv run`:

CODEX.md

@@ -22,7 +22,7 @@ Codex working notes for this repo. Start with [CLAUDE.md](./CLAUDE.md) for the f
 - Repo hooks enforce this.
 - All three forms dispatch through [soldr](https://github.com/zackees/soldr), which resolves each tool via `rustup which` so the rustup-managed toolchain is always used instead of a stale system or Chocolatey install.
 - `uv run cargo ...` works because `ci/dev-tools` registers `cargo`/`rustc`/`rustfmt` as repo-local uv scripts that now dispatch through `ci/trampoline.py` → `soldr`.
-- The `cargo` path passes `--no-cache` so the previous bare-cargo semantics are preserved (no RUSTC_WRAPPER / managed zccache inserted).
+- The normal Cargo path is `soldr cargo ...`; do not add repo-specific `RUSTC_WRAPPER` wiring for standard builds.
 - If you bypass them, you can hit wrong-toolchain errors.
 
 ## Use these
@@ -41,10 +41,16 @@ uv run cargo fmt --all
 uv run test
 uv run test --full
 uv run test -p fbuild-build -- some_test_name
+```
+
+## Optional wrapper-mode
 
+```powershell
 uv run python ci/zccache_setup.py
 ```
 
+This configures `rustc-wrapper = "zccache"` for local wrapper-mode experiments. Standard builds should use `uv run`, `soldr`, or the `_cargo`/`_rustc`/`_rustfmt` trampolines above.
+
 ## Allowed fallback
 
 - Repo trampolines: `_cargo`, `_rustc`, `_rustfmt`
@@ -56,4 +62,4 @@ uv run python ci/zccache_setup.py
 - First check whether you used one of the approved wrapper forms above.
 - If not, rerun it the required way before debugging anything else.
 - If the pinned toolchain is missing, run `./install` via `uv run --script install`.
-Read CLAUDE.md for repo instructions.
+Read CLAUDE.md for repo instructions.

_cargo

@@ -1,5 +1,4 @@
 #!/bin/bash
 # Trampoline: runs cargo through soldr so the rustup-managed toolchain
-# is always used. --no-cache keeps the compilation wrapper off to
-# match the previous bare-cargo behavior.
-exec uv run soldr --no-cache cargo "$@"
+# is always used.
+exec uv run soldr cargo "$@"

ci/README.md

@@ -11,7 +11,7 @@ Python scripts for CI, packaging, and development tooling. All invoked via `uv r
 - **`test.py`** -- Workspace test runner with `--full` (stress + integration) and per-crate filtering
 - **`trampoline.py`** -- Rust toolchain trampolines (cargo, rustc, rustfmt, clippy-driver) registered as `uv` project scripts
 - **`validate_boards.py`** -- Validates fbuild board JSON assets against PlatformIO board definitions
-- **`zccache_setup.py`** -- Optional local setup for zccache as the Cargo rustc-wrapper
+- **`zccache_setup.py`** -- Optional local wrapper-mode setup for zccache; not used by the standard soldr build path
 
 ## Subdirectories