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.platformbranch. - 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 macOSat 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
needsfile (tests/README). It never skips itself and never branches on the system to pass.
Owners
| Concern | Owner | What it decides |
|---|---|---|
| The host's system | tools/cli/files.giz hostOS; bin/gizlang host_caps | "macos" on Darwin. The test runner's macos capability. |
| The system a link targets | tools/cli/toolchain.giz linkOS | The release target's system, else the host's. Every link flag asks this. |
| Link flags of a dylib | toolchain.giz loaderSymbols, wholeArchives, selfBound | -undefined dynamic_lookup, -force_load, no -Bsymbolic. |
| Large modules | toolchain.giz MACHO_PARTS | A large module's parts are joined into one object by ld64 -r. The text is in every macOS cache key. |
| Frameworks | tools/cli/build.giz MACOS_FRAMEWORKS (and bin/gizlang darwin_inputs for the bootstrap) | Security and CoreFoundation. |
| The compiler of a Mac build | tools/distribution/native.giz MACOS_CLANG | Apple clang of the Command Line Tools. A macOS toolchain ships no LLVM and no SDK. |
| Targets | tools/distribution/targets.giz apple | The clang triple and the minimum version (11.0). |
| The runtime library | RUNTIME | A program loads libgizlang_runtime.dylib; GIZLANG_RUNTIME_STATIC=1 links the archive. |
| Memory and code memory | runtime/memory.giz | No 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 facts | runtime/machine.c, runtime/memory.giz | sysctl and the Mach interfaces, never /proc. |
| Processes | runtime/process.c | No 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 program | runtime/process.c | No 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). |
| Confinement | SYSTEM, agent isolation | A sandbox profile (sandbox_init); reads are not confined. |
| TLS trust | SYSTEM | SecTrust with the SSL policy, unless SSL_CERT_FILE or SSL_CERT_DIR is set. |
| Error codes | runtime/system.c gizlang_error_portable | macOS errno values differ from Linux ones. A code is mapped once, where a native returns it. |
| Debugger | tools/cli/debug.giz | lldb-dap, found with xcrun. macOS has no gdb. |
| Release payload | tools/native/payload.giz macos | The 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 systemopensslprogram is LibreSSL 3.3, which the TLS tests allow for (see below). - Run
bin/gizlangfromsh. 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 bootstrapbuilds the compiler from its seed the same way as on Linux.
Build and link
- A program links with Apple clang and
ld64. There is nold.lldon 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
--wasmfails on a Mac. arandranlibare 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 PATHruns the tests on the Mac. A test whoseneedsthe Mac lacks printsnot run: PATH: needs linuxand 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 withneeds 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.outputorSuite.runWithin, never withtimeout,stat,sed,cpioor other programs whose GNU and BSD forms differ. macOS has notimeoutcommand. - A test that needs a count of open descriptors uses
Harness.openDescriptors. A test that waits for a server waits on itslisteningcallback, never on/procor a retry loop. - A certificate for a test comes from
Harness.selfSignedandHarness.ecKey, which work with both OpenSSL and LibreSSL.Harness.libreSslis 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
- 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. - Build the candidate from a committed tree. It compiles with
MACOS_CLANGand checks itself end to end. - A change of the Mach-O object form changes
MACHO_PARTS, which changes every macOS cache key.
Steps of a port or a fix
- Reproduce on a Mac with the smallest command: one test file or one program.
- 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.gizfor link flags), not to the caller. - Search every site of the same shape (
grep -rnfor the call, the flag or the path) on all systems, and move them to the owner. - Write or move the test: portable through the SDK, or a
needssuite for a system subject. - Run the changed tests on Linux and on the Mac, then land.
Open
--wasmbuilds on a Mac need a Wasm-capable clang.sys.runBoundedloses 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.