chore(ci): add comments explaining why setup-zig is needed alongside pipx

Author: fengmk2

.github/workflows/ci.yml

@@ -58,6 +58,8 @@ jobs:
 
       - run: rustup target add x86_64-unknown-linux-musl
       - run: pipx install cargo-zigbuild
+      # pipx isolates cargo-zigbuild in its own venv, so its ziglang dependency
+      # (which bundles zig) isn't on PATH. Install zig separately.
       - uses: mlugg/setup-zig@d1434d08867e3ee9daa34448df10607b98908d29 # v2
 
       # --locked: verify Cargo.lock is up to date (replaces the removed `cargo check --locked`)
@@ -73,12 +75,20 @@ jobs:
         include:
           - os: namespace-profile-linux-x64-default
             target: x86_64-unknown-linux-gnu
+            cargo_cmd: cargo-zigbuild
+            build_target: x86_64-unknown-linux-gnu.2.17
           - os: windows-latest
             target: x86_64-pc-windows-msvc
+            cargo_cmd: cargo
+            build_target: x86_64-pc-windows-msvc
           - os: namespace-profile-mac-default
             target: aarch64-apple-darwin
+            cargo_cmd: cargo
+            build_target: aarch64-apple-darwin
           - os: namespace-profile-mac-default
             target: x86_64-apple-darwin
+            cargo_cmd: cargo
+            build_target: x86_64-apple-darwin
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -108,6 +118,8 @@ jobs:
       - run: pipx install cargo-zigbuild
         if: ${{ matrix.target == 'x86_64-unknown-linux-gnu' }}
 
+      # pipx isolates cargo-zigbuild in its own venv, so its ziglang dependency
+      # (which bundles zig) isn't on PATH. Install zig separately.
       - uses: mlugg/setup-zig@d1434d08867e3ee9daa34448df10607b98908d29 # v2
         if: ${{ matrix.target == 'x86_64-unknown-linux-gnu' }}
 
@@ -132,20 +144,10 @@ jobs:
       - run: pnpm install
 
       - name: Build tests
-        run: cargo test --no-run --target ${{ matrix.target }}
-        if: ${{ matrix.target != 'x86_64-unknown-linux-gnu' }}
-
-      - name: Build tests
-        run: cargo-zigbuild test --no-run --target x86_64-unknown-linux-gnu.2.17
-        if: ${{ matrix.target == 'x86_64-unknown-linux-gnu' }}
+        run: ${{ matrix.cargo_cmd }} test --no-run --target ${{ matrix.build_target }}
 
       - name: Run tests
-        run: cargo test --target ${{ matrix.target }}
-        if: ${{ matrix.target != 'x86_64-unknown-linux-gnu' }}
-
-      - name: Run tests
-        run: cargo-zigbuild test --target x86_64-unknown-linux-gnu.2.17
-        if: ${{ matrix.target == 'x86_64-unknown-linux-gnu' }}
+        run: ${{ matrix.cargo_cmd }} test --target ${{ matrix.build_target }}
 
   test-musl:
     needs: detect-changes