61 lines
2.6 KiB
Markdown
61 lines
2.6 KiB
Markdown
# 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`.
|