Files
alkane-toolkit/docs/macos.md
noahandClaude Opus 5.5 bb31a7befc
source / check (pull_request) Skipped
verify / verify (pull_request) Successful in 7m33s
verify / verify-windows (pull_request) Successful in 5m48s
macOS build: universal app for Apple Silicon and Intel, macOS 11+
- scripts/build-wx-macos.sh: static, monolithic, universal (arm64 +
  x86_64) wxOSX/Cocoa 3.3.3 from the vendored tree, with wx's bundled
  image/zlib/regex/expat so the app links only system frameworks.
  Minimum macOS 11.0: current SDKs' libc++ supports nothing older.
- scripts/build-gui-macos.sh: builds both Rust targets against that
  prefix and merges them with lipo.
- ci/package-macos.py: "Alkane Toolkit.app" (Info.plist, icon, local
  network usage string), ad-hoc signed, zipped with ditto as
  alkane-toolkit-vX.Y.Z-macos-universal.zip with LICENSE and README.
- crates/alkane-gui/macos: app icon (.icns) from the same glyph as the
  Windows icon, plus the script that makes it.
- wx-rs patch 0009: macOS goes through wx-config (drops the universal
  -arch flags, maps -framework), reports logical sizes like GTK/MSW
  instead of narrowing floats to ints, and links clang's compiler
  runtime for wxOSX's @available checks.
- docs/macos.md, README and the manual's install chapter.

Verified on an M1 running macOS 27.0.1: both slices build, all
workspace unit tests pass, and the headless UI self-test passes 52/52
on arm64.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 15:26:56 -06:00

2.7 KiB

macOS

The macOS build is one universal app, Alkane Toolkit.app, that runs natively on Apple Silicon and Intel Macs with macOS 11 (Big Sur) or later. It ships as alkane-toolkit-vX.Y.Z-macos-universal.zip, holding the app, LICENSE and a README.txt.

Using it

  • Settings live in ~/.config/alkane-toolkit, the same files as on Linux.
  • SSH actions use the system ssh; HTTP actions use the system curl.
  • The app is ad-hoc signed but not notarized, so macOS blocks the first launch. On macOS 15 or later, try to open it, then choose Open Anyway in System Settings > Privacy & Security. On macOS 11 to 14, Control-click the app and choose Open. Or clear the quarantine flag once: xattr -dr com.apple.quarantine "/Applications/Alkane Toolkit.app".
  • The first scan asks for permission to find devices on the local network (macOS 15 and later). Scanning needs it.
  • Offline demo: ALKANE_FAKE_SCAN=1 "/Applications/Alkane Toolkit.app/Contents/MacOS/alkane-toolkit".

Building

macOS builds only on a Mac. It needs the Xcode Command Line Tools (xcode-select --install) and rustup with both Apple targets:

rustup target add aarch64-apple-darwin x86_64-apple-darwin
scripts/build-wx-macos.sh      # once: universal static wxOSX 3.3.3 in ~/.cache/wx-3.3.3-macos
scripts/build-gui-macos.sh     # both slices, merged with lipo
python3 ci/package-macos.py X.Y.Z target/universal-apple-darwin/release/alkane-toolkit dist

build-wx-macos.sh builds wxWidgets once for arm64 and x86_64 together, with wx's bundled image, zlib, regex and expat libraries, so the app links only against system frameworks. build-gui-macos.sh builds each Rust target against that prefix and merges them. package-macos.py writes the bundle (Info.plist, icon), ad-hoc signs it and zips it with ditto.

To test on the Mac:

ALKANE_SELFTEST=1 target/universal-apple-darwin/release/alkane-toolkit   # headless UI self-test
cargo test --release --offline --target aarch64-apple-darwin --workspace --exclude wx-rs

The self-test opens a window briefly, so it needs a logged-in desktop session. Running the x86_64 slice on Apple Silicon needs Rosetta 2.

Why macOS 11

Current Xcode SDKs ship a libc++ that supports macOS 11 and later only; building for an older target compiles, but the app could fail at run time on the older system. macOS 11 is also the first release for Apple Silicon. Older Intel Macs would need a build with an older SDK.

Notes for the bridge

wxOSX reports logical (point) sizes, like the GTK and MSW bridges; the bridge never scales to physical pixels. wxOSX's Objective-C uses @available, so build.rs links clang's compiler runtime (libclang_rt.osx.a), which rustc's link does not include by itself. Both are wx-rs patch 0009.