feat: automate macOS cross-compilation with Zig
Rust CI tiny-wb passed CI.
Gitea/tiny-wb/pipeline/head This commit looks good Details

This commit is contained in:
Dandaedre 2026-10-20 15:13:37 +02:00
parent 03503eebbc
commit 8ed07cb60e
6 changed files with 253 additions and 0 deletions

View File

@ -43,6 +43,9 @@ From the repository root:
cargo run --release
```
For Apple Silicon and Intel macOS binaries built from Linux, run
`./scripts/build-macos.sh`; see [macOS build requirements and validation](docs/macos.md).
Use `cargo run --release -- --live` to confirm the usual connection and scan
settings, then display repeated complete sweeps until stopped. Number keys select
average/hold/decay traces, `s` saves the visible buffer, and `q`, Escape, or

View File

@ -51,6 +51,7 @@ grows into many chapters, the files are already organized so that a future
- [Testing](testing.md): regression seams and hardware verification boundaries.
- [Agent/contributor guidance](../AGENTS.md): code structure, comments, documentation and atomic commits.
- [Releases](releases.md): release wrapper, prerequisites, collision checks and publication policy.
- [macOS cross-compilation](macos.md): automated Apple Silicon and Intel builds from Linux.
- [Basic and Ultra support](ultra-support.md): implemented range, model detection and qualification status.
- [Feature roadmap](roadmap.md): model-aware Basic/Ultra completion tasks.
- [Implementation task backlog](../task.md): detailed milestones and optional stretch goals.

103
docs/macos.md Normal file
View File

@ -0,0 +1,103 @@
# Building macOS binaries from Linux
Run from a Linux checkout with a working Podman or Docker installation:
```console
./scripts/build-macos.sh
```
The script prefers Podman when available. Select Docker explicitly with
`CONTAINER_ENGINE=docker ./scripts/build-macos.sh`. It works from another
directory too, using the checkout containing the script. Network access is
needed for the initial container and crate downloads. No Mac, Xcode installation
on the host, interactive container session, or publication token is required.
## Toolchain and dependencies
The script pins the upstream
[cargo-zigbuild container](https://github.com/rust-cross/cargo-zigbuild)
by SHA-256 manifest digest. The inspected image contains Rust 1.93.0,
cargo-zigbuild 0.23.4, Zig 0.16.0, both Apple Rust targets, and the macOS 11.3 SDK
at `/opt/MacOSX11.3.sdk` (`SDKROOT`). See the upstream
[Dockerfile](https://github.com/rust-cross/cargo-zigbuild/blob/main/Dockerfile)
for SDK provenance and image construction; the digest in the script, rather
than the moving upstream branch, identifies our actual build environment.
The SDK supplies IOKit and CoreFoundation for the existing `serialport`
dependency. No additional Cargo dependency or Homebrew package was necessary.
Linux's libudev and Windows's resource compiler are not needed for Apple
targets. The normal default features include both the terminal UI and serial
transport; these builds do not disable serial support to avoid linking it.
The declared deployment minimum is **macOS 13.0**, for both architectures.
During verification, requesting 11.0 still produced a 13.0 Mach-O minimum
with this toolchain. The script therefore explicitly requests 13.0. Supporting
older systems requires a separately verified toolchain and runtime testing;
the SDK directory's version is not the executable's deployment minimum.
The image pin fixes the compiler/SDK inputs, and `--locked` preserves the
dependency graph. This is not a claim of bit-for-bit reproducibility.
Container updates should rerun the checks below and inspect deployment
versions and dynamic dependencies before changing the pin.
## Outputs
Both release binaries are produced in one invocation:
| Architecture | Executable |
| --- | --- |
| Apple Silicon | `target/apple/aarch64-apple-darwin/release/tiny-wb` |
| Intel | `target/apple/x86_64-apple-darwin/release/tiny-wb` |
These are separate Mach-O executables, not a universal binary or `.app` bundle.
Cargo downloads, compilation outputs, and Zig caches live under ignored
`target/apple/`. Generated files belong to the invoking user. The container
mounts the checkout to compile it; use a checkout without concurrent builds
writing into the same Apple target directory.
The script only compiles. The existing [`release.sh` publisher](releases.md)
still handles its Linux/Windows matrix; it does not package or upload these
Apple artifacts. They have no Developer ID signature or notarization.
## Verification
Wrapper regression tests run without containers or network access:
```console
sh -n scripts/build-macos.sh
python3 scripts/test-macos-build.py
```
Run the normal [local quality gates](security-and-ci.md#local-verification)
and the real build script. On Linux with LLVM tools installed, inspect:
```console
file target/apple/*-apple-darwin/release/tiny-wb
llvm-objdump --macho --dylibs-used target/apple/aarch64-apple-darwin/release/tiny-wb
llvm-objdump --macho --private-headers target/apple/aarch64-apple-darwin/release/tiny-wb
llvm-objdump --macho --dylibs-used target/apple/x86_64-apple-darwin/release/tiny-wb
llvm-objdump --macho --private-headers target/apple/x86_64-apple-darwin/release/tiny-wb
```
Check the architecture, `LC_BUILD_VERSION` minimum of 13.0, and that loaded
libraries are Apple system paths rather than container/build-machine paths.
Observed on **2026-10-20**: both default-feature release binaries cross-compiled
on Linux using rootless Podman. Their dynamic dependencies were IOKit,
CoreFoundation, libSystem, libobjc, libiconv, and libcharset, all under
`/System/Library/Frameworks/` or `/usr/lib/`. A separate
`cargo zigbuild --locked --release --all-targets --all-features` invocation
with both Apple targets also compiled and linked the tests and examples.
The native Linux formatting, MSRV, feature-matrix checks/tests, Rustdoc,
Clippy, and release build passed. Docker execution is covered only by wrapper
argument tests, not a real Docker build.
Execution on macOS, terminal interaction, serial enumeration, actual USB
acquisition, Gatekeeper behavior, Jenkins execution, and publication remain
unverified. Cross-compiling tests does not run them on macOS.
On a Mac, first run `./tiny-wb --help`, then use the
[mock-device workflow](mock-device.md) for simulated acquisition and the
[hardware validation guide](hardware-validation.md) for a physical instrument.
Choose the actual enumerated macOS serial device in the UI; Linux/Windows
preferred port names in the defaults are preferences, not required devices.

View File

@ -1,5 +1,9 @@
# Releasing tiny-wb
For compile-only Apple Silicon and Intel macOS binaries using a pinned Zig
container, see [macOS cross-compilation](macos.md). That separate build command
does not add Apple artifacts to the publisher's Linux/Windows matrix below.
`release.sh` delegates to the deliberately named
[`rust_realease`](https://proxy.dandaedre.com/gitea/idle-org/rust_realease).
It is based on the

49
scripts/build-macos.sh Executable file
View File

@ -0,0 +1,49 @@
#!/bin/sh
# Compile-only Apple builds. See docs/macos.md for prerequisites and validation.
set -eu
if [ "$#" -ne 0 ]; then
echo "usage: $0 (set CONTAINER_ENGINE=podman or docker)" >&2
exit 2
fi
engine=${CONTAINER_ENGINE:-}
if [ -z "$engine" ]; then
if command -v podman >/dev/null 2>&1; then
engine=podman
else
engine=docker
fi
fi
case "$engine" in
podman|docker) ;;
*) echo "CONTAINER_ENGINE must be podman or docker" >&2; exit 2 ;;
esac
command -v "$engine" >/dev/null 2>&1 || {
echo "Install Podman or Docker before building macOS binaries." >&2
exit 1
}
repository_dir=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd -P)
# Pin the complete compiler/SDK environment, not the mutable latest tag.
image=ghcr.io/rust-cross/cargo-zigbuild@sha256:9b4f6b3eb9e8f9fefb3960fe288ddba576627d66d9eff851ce7f62d2455564a5
mkdir -p "$repository_dir/target/apple"
# Keep generated files owned by the invoking user on both container engines.
set -- run --rm --user "$(id -u):$(id -g)"
if [ "$engine" = podman ]; then
set -- "$@" --userns=keep-id
fi
"$engine" "$@" \
-v "$repository_dir:/io" -w /io \
-e HOME=/tmp \
-e CARGO_HOME=/io/target/apple/cargo-home \
-e CARGO_TARGET_DIR=/io/target/apple \
-e ZIG_GLOBAL_CACHE_DIR=/io/target/apple/zig-cache \
-e MACOSX_DEPLOYMENT_TARGET=13.0 \
"$image" \
cargo zigbuild --locked --release --bin tiny-wb \
--target aarch64-apple-darwin --target x86_64-apple-darwin
echo "Apple Silicon: $repository_dir/target/apple/aarch64-apple-darwin/release/tiny-wb"
echo "Intel: $repository_dir/target/apple/x86_64-apple-darwin/release/tiny-wb"

View File

@ -0,0 +1,93 @@
#!/usr/bin/env python3
"""Check the macOS wrapper without downloading images or starting containers."""
import json
import os
from pathlib import Path
import shutil
import subprocess
import tempfile
import unittest
SOURCE = Path(__file__).resolve().parent / "build-macos.sh"
class MacOSBuildTests(unittest.TestCase):
def setUp(self):
self.temp = tempfile.TemporaryDirectory()
self.addCleanup(self.temp.cleanup)
self.root = Path(self.temp.name)
self.repo = self.root / "checkout with spaces"
(self.repo / "scripts").mkdir(parents=True)
self.script = self.repo / "scripts" / SOURCE.name
shutil.copy2(SOURCE, self.script)
self.record = self.root / "arguments.json"
self.bin = self.root / "bin"
self.bin.mkdir()
for engine in ("podman", "docker"):
stub = self.bin / engine
stub.write_text(
"#!/usr/bin/env python3\n"
"import json, os, sys\n"
"with open(os.environ['ARGUMENT_RECORD'], 'w') as stream:\n"
" json.dump(sys.argv[1:], stream)\n"
"sys.exit(int(os.environ.get('ENGINE_STATUS', '0')))\n"
)
stub.chmod(0o755)
self.env = {
**os.environ,
"PATH": f"{self.bin}:{os.environ['PATH']}",
"ARGUMENT_RECORD": str(self.record),
"CONTAINER_ENGINE": "podman",
}
def run_script(self, *args):
return subprocess.run(
["sh", str(self.script), *args],
cwd=self.root,
env=self.env,
text=True,
capture_output=True,
)
def test_build_from_elsewhere_with_spaces_and_pinned_environment(self):
result = self.run_script()
self.assertEqual(result.returncode, 0, result.stderr)
args = json.loads(self.record.read_text())
self.assertIn(f"{self.repo}:/io", args)
self.assertIn("--userns=keep-id", args)
self.assertIn(f"{os.getuid()}:{os.getgid()}", args)
self.assertIn("MACOSX_DEPLOYMENT_TARGET=13.0", args)
image = next(arg for arg in args if arg.startswith("ghcr.io/"))
self.assertRegex(image, r"@sha256:[0-9a-f]{64}$")
self.assertIn("--locked", args)
self.assertIn("aarch64-apple-darwin", args)
self.assertIn("x86_64-apple-darwin", args)
self.assertTrue((self.repo / "target/apple").is_dir())
def test_docker_uses_caller_without_podman_namespace_option(self):
self.env["CONTAINER_ENGINE"] = "docker"
self.assertEqual(self.run_script().returncode, 0)
args = json.loads(self.record.read_text())
self.assertIn("--user", args)
self.assertNotIn("--userns=keep-id", args)
def test_failed_build_does_not_report_success(self):
self.env["ENGINE_STATUS"] = "42"
result = self.run_script()
self.assertEqual(result.returncode, 42)
self.assertNotIn("Apple Silicon:", result.stdout)
def test_invalid_engine_is_rejected_before_invocation(self):
self.env["CONTAINER_ENGINE"] = "docker --privileged"
self.assertEqual(self.run_script().returncode, 2)
self.assertFalse(self.record.exists())
def test_arguments_are_rejected_before_invocation(self):
self.assertEqual(self.run_script("--publish").returncode, 2)
self.assertFalse(self.record.exists())
if __name__ == "__main__":
unittest.main()