# 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](https://github.com/gizai/gizlang/blob/main/tests/README.md#capabilities)).
  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](runtime.md#files) | 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](system.md), [agent isolation](agent-isolation.md) | A sandbox profile (`sandbox_init`); reads are not confined. |
| TLS trust | [SYSTEM](system.md) | `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
  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.

## Build and link

- 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.
