Context
PR #338 ("chore(release): v0.4.0 prep - musl linking fixes, browserslist pin") identified a maintenance debt in the aarch64-unknown-linux-musl build leg: a hand-rolled zig cc wrapper filters exactly one linker flag (-Wl,--fix-cortex-a53-843419), emitted by rustc >= 1.98.0 for both aarch64 linux targets.
The broader ecosystem has consolidated this work: cargo-zigbuild v0.23.0 (released 2026-06-18, >75 days soaked as of this issue date) implements a maintained filter list that grew over time (--no-undefined-version, -znostart-stop-gc, -plugin-opt, --fix-cortex-a53-843419, and others). Both x86_64-unknown-linux-musl and aarch64-unknown-linux-musl build legs should delegate to this library rather than maintaining separate wrappers.
Current risk: the x86_64 leg is safe today only because rustc gates -znostart-stop-gc to llvm_target x86_64-unknown-linux-gnu. If rustc emits a flag for x86_64-unknown-linux-musl in a future release, the current filter (matching only standalone -Wl, spelling, not comma-coalesced forms) would silently miss it.
Proposal
Replace the hand-rolled exec zig cc -target <triple> "$@" in both musl wrappers with exec cargo-zigbuild zig cc -target <triple> "$@" (public passthrough subcommand that applies filter_linker_args). Install cargo-zigbuild via taiki-e/install-action pinned to v0.23.0.
Alternatively, adopt napi's -x/--cross-compile flag which delegates to cargo-zigbuild, as the live napi-rs package template does with mlugg/setup-zig + taiki-e/install-action.
Note: cargo-zigbuild's other musl rewrites (-lgcc_s -> -lunwind, crt handling) represent behavioral deltas on a currently-working link line; validate with a branch dry-run plus the existing readelf gate, and note its version-keyed wrapper cache (~/.cache/cargo-zigbuild//) can serve a stale unfiltered wrapper after an upgrade.
Acceptance Criteria
- Both musl legs (x86_64 and aarch64) pass on a branch dry-run (gh workflow run release.yml --ref )
- readelf gate passes on both platform packages
- The one-flag filter (scripts/wrappers/zig-cc-aarch64-musl.sh or equivalent) and its self-check are removed
- RELEASING.md documents the new cargo-zigbuild dependency and version constraint
Related
Relates to PR #338
Context
PR #338 ("chore(release): v0.4.0 prep - musl linking fixes, browserslist pin") identified a maintenance debt in the aarch64-unknown-linux-musl build leg: a hand-rolled zig cc wrapper filters exactly one linker flag (-Wl,--fix-cortex-a53-843419), emitted by rustc >= 1.98.0 for both aarch64 linux targets.
The broader ecosystem has consolidated this work: cargo-zigbuild v0.23.0 (released 2026-06-18, >75 days soaked as of this issue date) implements a maintained filter list that grew over time (--no-undefined-version, -znostart-stop-gc, -plugin-opt, --fix-cortex-a53-843419, and others). Both x86_64-unknown-linux-musl and aarch64-unknown-linux-musl build legs should delegate to this library rather than maintaining separate wrappers.
Current risk: the x86_64 leg is safe today only because rustc gates -znostart-stop-gc to llvm_target x86_64-unknown-linux-gnu. If rustc emits a flag for x86_64-unknown-linux-musl in a future release, the current filter (matching only standalone -Wl, spelling, not comma-coalesced forms) would silently miss it.
Proposal
Replace the hand-rolled
exec zig cc -target <triple> "$@"in both musl wrappers withexec cargo-zigbuild zig cc -target <triple> "$@"(public passthrough subcommand that applies filter_linker_args). Install cargo-zigbuild via taiki-e/install-action pinned to v0.23.0.Alternatively, adopt napi's
-x/--cross-compileflag which delegates to cargo-zigbuild, as the live napi-rs package template does with mlugg/setup-zig + taiki-e/install-action.Note: cargo-zigbuild's other musl rewrites (-lgcc_s -> -lunwind, crt handling) represent behavioral deltas on a currently-working link line; validate with a branch dry-run plus the existing readelf gate, and note its version-keyed wrapper cache (~/.cache/cargo-zigbuild//) can serve a stale unfiltered wrapper after an upgrade.
Acceptance Criteria
Related
Relates to PR #338