From 8ed07cb60eb6955fce81e7897a4aa3ce48cc959a Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Tue, 20 Oct 2026 15:13:37 +0200 Subject: [PATCH] feat: automate macOS cross-compilation with Zig --- README.md | 3 ++ docs/README.md | 1 + docs/macos.md | 103 ++++++++++++++++++++++++++++++++++++ docs/releases.md | 4 ++ scripts/build-macos.sh | 49 +++++++++++++++++ scripts/test-macos-build.py | 93 ++++++++++++++++++++++++++++++++ 6 files changed, 253 insertions(+) create mode 100644 docs/macos.md create mode 100755 scripts/build-macos.sh create mode 100644 scripts/test-macos-build.py diff --git a/README.md b/README.md index 489dce4..40912fd 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/README.md b/docs/README.md index c3dc2ee..6d8d4cc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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. diff --git a/docs/macos.md b/docs/macos.md new file mode 100644 index 0000000..9841d15 --- /dev/null +++ b/docs/macos.md @@ -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. diff --git a/docs/releases.md b/docs/releases.md index ae96425..88059bc 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -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 diff --git a/scripts/build-macos.sh b/scripts/build-macos.sh new file mode 100755 index 0000000..78edfc9 --- /dev/null +++ b/scripts/build-macos.sh @@ -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" diff --git a/scripts/test-macos-build.py b/scripts/test-macos-build.py new file mode 100644 index 0000000..f7d2ddf --- /dev/null +++ b/scripts/test-macos-build.py @@ -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()