# Build guide

Building `gem` from source and running its test suite.

## Prerequisites

- macOS on Apple Silicon (developed against M4 Max) with Xcode Command Line Tools
  (`xcode-select --install`)
- CMake >= 3.24 (`brew install cmake`)
- A Gemma 4 GGUF model file (see [`getting-started.md`](../user_guide/getting-started.md))

## Configure and build

```sh
cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cmake --build build -j
```

`CMAKE_EXPORT_COMPILE_COMMANDS=ON` writes `build/compile_commands.json` (symlinked at the
repo root for clangd/LSP); it is a build convenience and is gitignored. The default build is
Release (`-O3 -arch arm64`), compiles strictly (`-Wall -Wextra -Wpedantic -Werror`), and links
only the system Metal/Foundation frameworks and libm — the production binary must never link
libllama/ggml or launch `llama-server` (enforced by dependency-guard tests).

Core targets:

| Target | Purpose |
|---|---|
| `gem` | CLI: `print-config`, `generate`, `serve`, `agent` |
| `gem-inspect` | GGUF metadata / tensor / binding inspection |
| `gem-logits` | dump a next-token logits vector for differentials |
| `gem-logit-compare` | compare two logits vectors |
| `gem-bench` | full-model prompt/generation benchmark (3-rep JSON) |
| `gem-tokenize` | tokenizer CLI |
| plus ~30 profiling/diagnostic binaries | `gem-kernel-bench`, `gem-decode-profile`, `gem-mtp-bench`, ... |

## Build variants

- **Address/UB sanitizers** — the project's sanitizer configuration mirrors the normal tests
  (ASan/UBSan). Configure separately, e.g. `-B build-asan` with the sanitizer flags used in CI.
- **Legacy launcher (transitional only)** — `cmake -S . -B build-legacy -DGEM_BUILD_LEGACY_LAUNCHER=ON`.
  Do not add features to it; it is a temporary llama.cpp-launching oracle and will be removed.
- All build trees (`build*/`, `CMakeFiles/`) are gitignored.

## Tests

```sh
ctest --test-dir build --output-on-failure
```

The suite covers GGUF parsing/topology, tokenizer parity, CPU layer math, sampler determinism,
chat/server behavior, Metal layer/attention operators, dependency guards (no llama/ggml linkage),
benchmark-gate analyzers, server SSE/probe/gate fixtures, and the **12B servability detector**
(`gem.12b_servability_gate`). Runs in about 1–2 minutes on an M4 Max.

## Benchmark protocol

Performance claims follow the one-axis protocol in
[`benchmark-protocol.md`](./benchmark-protocol.md): record `gem print-config`, raw JSON from three
repetitions of a single changed axis, and the analyzer verdict. Read that document before
promoting any setting. Durable evidence is indexed with `scripts/memory-index.sh`.