build: macOS release builds DEFERRED — and the macOS cfg paths are compiled by nothing in CI #59

New issue

Open

opened 2026-08-05 08:32:22 +02:00 by buildagent · 0 comments

buildagent commented

2026-08-05 08:32:22 +02:00

Member

Decision record + tracking issue for the deliberate deferral of macOS release builds, and for the coverage hole that deferral leaves behind.

Decision: macOS builds are deferred

x86_64-apple-darwin and aarch64-apple-darwin are not built and not published. This is intentional, not a build failure. Every release from v0.8.4 through v0.9.0 has shipped four artifacts:

Shipped	Deferred
linux-x86_64 (glibc)	macos-x86_64
linux-x86_64-musl (static)	macos-aarch64
linux-aarch64	windows-aarch64 (needs Windows+MSVC runner)
windows-x86_64

The matrix entries in .forgejo/workflows/release.yml were already commented out (not merely continue-on-error) because a matrix entry whose runs-on label has no registered runner does not fail — it queues forever and hangs the whole run. continue-on-error tolerates failures, never never-scheduled jobs. That distinction is why commenting out is the correct mechanism here.

The README/packaging steps still carry macos-x86_64 / macos-aarch64 case arms. Those are deliberately kept pre-wired so re-enabling is a pure uncomment.

The part that is NOT just cosmetic

There is a windows-check CI job that cross-compiles --target x86_64-pc-windows-gnu to keep Windows-only code honest. There is no macOS equivalent. So these paths are compiled by nothing, anywhere in CI:

crates/indexer/src/watcher.rs — #[cfg(any(target_os = "windows", target_os = "macos"))] single recursive watch (FSEvents native subtree subscription), and the IN_Q_OVERFLOW/FSEvents overflow handling
crates/daemon/src/lifecycle.rs — #[cfg(target_os = "macos")] stale-PID detection, and the Linux/macOS flock EWOULDBLOCK path
crates/indexer/tests/watcher.rs / periodic_reconcile.rs — assertions gated on cfg!(target_os = "macos") that consequently never execute

These can bit-rot silently: a refactor that breaks the macOS arm produces a green CI run. Given the project's standing parity requirement (all languages × 3 OSes × 2 arches), this is the actual debt — not the missing binaries.

Why a cheap check-only gate does not work

cargo check --target aarch64-apple-darwin from the Linux container is not sufficient. cargo check still runs build scripts, and the seven tree-sitter-* grammar crates each compile C via cc in build.rs. That needs a darwin C toolchain (osxcross + the Apple SDK), not just rustup target add. So the options are:

Register a macOS runner (labelled macos, with Xcode CLT) → uncomment the two matrix entries; real builds and real tests.
osxcross + Apple SDK in ci-base → enables a macos-check compile gate, and possibly full cross-builds. Note the Apple SDK has redistribution constraints; this needs a licensing look before baking it into a shared image.
Accept the hole (status quo) → macOS users build from source; the cfg paths stay unverified.

Acceptance

Decide between options 1–3 above
If 1 or 2: uncomment the matrix entries, confirm 6 archives + 6 .sha256 publish, and add a macos-check job alongside windows-check
If 3: keep this issue open as the standing record; no code change
Either way: release notes must not imply macOS artifacts are imminent

Status

release.yml header comments and the release-notes footer are being corrected to state the deferral plainly (they previously described macOS as an attempted "best-effort" target, contradicting the disabled matrix entries).

Decision record + tracking issue for the deliberate deferral of macOS release builds, and for the coverage hole that deferral leaves behind. ## Decision: macOS builds are deferred `x86_64-apple-darwin` and `aarch64-apple-darwin` are **not built and not published**. This is intentional, not a build failure. Every release from v0.8.4 through v0.9.0 has shipped four artifacts: | Shipped | Deferred | |---|---| | linux-x86_64 (glibc) | macos-x86_64 | | linux-x86_64-musl (static) | macos-aarch64 | | linux-aarch64 | windows-aarch64 (needs Windows+MSVC runner) | | windows-x86_64 | | The matrix entries in `.forgejo/workflows/release.yml` were already commented out (not merely `continue-on-error`) because a matrix entry whose `runs-on` label has no registered runner does **not** fail — it queues forever and hangs the whole run. `continue-on-error` tolerates *failures*, never *never-scheduled* jobs. That distinction is why commenting out is the correct mechanism here. The README/packaging steps still carry `macos-x86_64` / `macos-aarch64` `case` arms. Those are deliberately kept pre-wired so re-enabling is a pure uncomment. ## The part that is NOT just cosmetic There is a `windows-check` CI job that cross-compiles `--target x86_64-pc-windows-gnu` to keep Windows-only code honest. **There is no macOS equivalent.** So these paths are compiled by nothing, anywhere in CI: - `crates/indexer/src/watcher.rs` — `#[cfg(any(target_os = "windows", target_os = "macos"))]` single recursive watch (FSEvents native subtree subscription), and the `IN_Q_OVERFLOW`/FSEvents overflow handling - `crates/daemon/src/lifecycle.rs` — `#[cfg(target_os = "macos")]` stale-PID detection, and the Linux/macOS `flock` `EWOULDBLOCK` path - `crates/indexer/tests/watcher.rs` / `periodic_reconcile.rs` — assertions gated on `cfg!(target_os = "macos")` that consequently never execute These can bit-rot silently: a refactor that breaks the macOS arm produces a green CI run. Given the project's standing parity requirement (all languages × 3 OSes × 2 arches), this is the actual debt — not the missing binaries. ## Why a cheap check-only gate does not work `cargo check --target aarch64-apple-darwin` from the Linux container is not sufficient. `cargo check` still **runs build scripts**, and the seven `tree-sitter-*` grammar crates each compile C via `cc` in `build.rs`. That needs a darwin C toolchain (osxcross + the Apple SDK), not just `rustup target add`. So the options are: 1. **Register a macOS runner** (labelled `macos`, with Xcode CLT) → uncomment the two matrix entries; real builds and real tests. 2. **osxcross + Apple SDK in `ci-base`** → enables a `macos-check` compile gate, and possibly full cross-builds. Note the Apple SDK has redistribution constraints; this needs a licensing look before baking it into a shared image. 3. **Accept the hole** (status quo) → macOS users build from source; the cfg paths stay unverified. ## Acceptance - [ ] Decide between options 1–3 above - [ ] If 1 or 2: uncomment the matrix entries, confirm 6 archives + 6 `.sha256` publish, and add a `macos-check` job alongside `windows-check` - [ ] If 3: keep this issue open as the standing record; no code change - [ ] Either way: release notes must not imply macOS artifacts are imminent ## Status `release.yml` header comments and the release-notes footer are being corrected to state the deferral plainly (they previously described macOS as an attempted "best-effort" target, contradicting the disabled matrix entries).

buildagent added the

labels

2026-08-05 08:32:32 +02:00