GizStack
View .mdOpen in ChatGPTOpen in Claude

macOS

Gizlang builds, runs and ships on macOS 11 or later, on x86-64 and ARM64 (x86_64-apple-darwin, aarch64-apple-darwin). Read this page before you change code for macOS, port a feature to it, or fix a failure that only a Mac shows. Each fact below has one owner in the code; this page names the owner and does not repeat its rules.

The rule

  • A portable subject has one path on every system. Its code and its test use the SDK, never a system path, a system program or a process.platform branch.
  • A system difference lives in exactly one owner: the runtime file or the tool function that the table below names. Callers ask that owner. A second if macOS at a caller does not land.
  • A defect that a Mac shows is one of a class. Before you fix it, search for every site of the same shape on every system (Linux and Windows too), and fix the owner once.
  • A test that cannot run on a Mac says so with a needs file (tests/README). It never skips itself and never branches on the system to pass.

Owners

ConcernOwnerWhat it decides
The host's systemtools/cli/files.giz hostOS; bin/gizlang host_caps"macos" on Darwin. The test runner's macos capability.
The system a link targetstools/cli/toolchain.giz linkOSThe release target's system, else the host's. Every link flag asks this.
Link flags of a dylibtoolchain.giz loaderSymbols, wholeArchives, selfBound-undefined dynamic_lookup, -force_load, no -Bsymbolic.
Large modulestoolchain.giz MACHO_PARTSA large module's parts are joined into one object by ld64 -r. The text is in every macOS cache key.
Frameworkstools/cli/build.giz MACOS_FRAMEWORKS (and bin/gizlang darwin_inputs for the bootstrap)Security and CoreFoundation.
The compiler of a Mac buildtools/distribution/native.giz MACOS_CLANGApple clang of the Command Line Tools. A macOS toolchain ships no LLVM and no SDK.
Targetstools/distribution/targets.giz appleThe clang triple and the minimum version (11.0).
The runtime libraryRUNTIMEA program loads libgizlang_runtime.dylib; GIZLANG_RUNTIME_STATIC=1 links the archive.
Memory and code memoryruntime/memory.gizNo MAP_FIXED_NOREPLACE (a hint, then a check). Code memory is a mach_vm_remap alias: a shared mapping cannot be executed. MADV_DONTNEED frees nothing, so nativeDiscard maps over the pages.
CPUs, caches, memory factsruntime/machine.c, runtime/memory.gizsysctl and the Mach interfaces, never /proc.
Processesruntime/process.cNo parent-death signal: a guard that launchd adopts. The descriptor bound rises to the hard bound at start. Images and symbols come from the loader.
Tests in one programruntime/process.cNo fork: the tests run one after another in the process, each in its own World. A forked child without exec cannot reach system services (XPC).
ConfinementSYSTEM, agent isolationA sandbox profile (sandbox_init); reads are not confined.
TLS trustSYSTEMSecTrust with the SSL policy, unless SSL_CERT_FILE or SSL_CERT_DIR is set.
Error codesruntime/system.c gizlang_error_portablemacOS errno values differ from Linux ones. A code is mapped once, where a native returns it.
Debuggertools/cli/debug.gizlldb-dap, found with xcrun. macOS has no gdb.
Release payloadtools/native/payload.giz macosThe runtime archive, target.o and libuv, built on a Mac with MACOSX_DEPLOYMENT_TARGET.

Set up a Mac

  • Install the Command Line Tools (xcode-select --install), cmake and Node 24.
  • Install OpenSSL 3. A release loads the system's libcrypto.3.dylib (tools/distribution/builder.giz), and the system openssl program is LibreSSL 3.3, which the TLS tests allow for (see below).
  • Run bin/gizlang from sh. The login shell is zsh, which does not split words and stops at an unmatched glob.
  • Set GIZLANG_LOCAL=1: a Mac runs its own builds and tests. bin/gizlang bootstrap builds the compiler from its seed the same way as on Linux.
  • A program links with Apple clang and ld64. There is no ld.lld on a Mac, so a static Linux link (x86_64-unknown-linux-none, Harness.staticBuild) does not work there.
  • A fast (-O0) program loads the build folder's runtime dylib. A copy that must run without the toolchain is built with GIZLANG_RUNTIME_STATIC=1.
  • A shared object (a unit library, a live swap, a kernel) leaves the runtime's symbols to the program that loads it: link it with loaderSymbols(linkOS(env)), never with a flag list of your own.
  • Apple clang has no Wasm backend, so --wasm fails on a Mac.
  • ar and ranlib are the system's (/usr/bin). An archive in the cache that another tool wrote can break a link: delete the cache entry, do not add a guard.

Tests on a Mac

  • GIZLANG_LOCAL=1 bin/gizlang test PATH runs the tests on the Mac. A test whose needs the Mac lacks prints not run: PATH: needs linux and counts as not run. A run with no failure and some not-run tests exits 75.
  • A test of a Linux subject (/proc, FUSE, Landlock, seccomp, ELF tools, static Linux links, systemd) is its own suite folder with needs linux. Put the Linux part in its own folder; do not let it hold back the portable part.
  • A test runs a child with Harness.run, Harness.output or Suite.runWithin, never with timeout, stat, sed, cpio or other programs whose GNU and BSD forms differ. macOS has no timeout command.
  • A test that needs a count of open descriptors uses Harness.openDescriptors. A test that waits for a server waits on its listening callback, never on /proc or a retry loop.
  • A certificate for a test comes from Harness.selfSigned and Harness.ecKey, which work with both OpenSSL and LibreSSL. Harness.libreSsl is for the few expectations that differ.
  • A suite has no time bound on a Mac (no systemd scope). Run a long one in the background.
  • An expectation that differs by system (a socket option, thread counts, paths) is chosen by hostOS() in one place in the test, with a comment that says why.

A release for macOS

  1. Build the payload on a Mac: bin/gizlang tools/native/payload.giz build TARGET ARCHIVES WORK OUT. The payload holds the runtime archive, so rebuild it after each runtime change. An old payload links an old runtime.
  2. Build the candidate from a committed tree. It compiles with MACOS_CLANG and checks itself end to end.
  3. A change of the Mach-O object form changes MACHO_PARTS, which changes every macOS cache key.

Steps of a port or a fix

  1. Reproduce on a Mac with the smallest command: one test file or one program.
  2. Find the owner in the table above. If none owns the concern, add it to the module that owns the subject (the runtime for system calls, toolchain.giz for link flags), not to the caller.
  3. Search every site of the same shape (grep -rn for the call, the flag or the path) on all systems, and move them to the owner.
  4. Write or move the test: portable through the SDK, or a needs suite for a system subject.
  5. Run the changed tests on Linux and on the Mac, then land.

Open

  • --wasm builds on a Mac need a Wasm-capable clang.
  • sys.runBounded loses a child's partial output when it times out.
  • A suite has no time bound without systemd.
  • Apple GPU (Metal) work needs an Apple Silicon Mac; an x86-64 Mac has no Apple GPU.