feat: automate macOS cross-compilation with Zig
Rust CI tiny-wb passed CI.
Gitea/tiny-wb/pipeline/head This commit looks good
Details
Rust CI tiny-wb passed CI.
Gitea/tiny-wb/pipeline/head This commit looks good
Details
This commit is contained in:
parent
03503eebbc
commit
8ed07cb60e
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
@ -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()
|
||||
Loading…
Reference in New Issue