trevon/gem
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
gem/docs/build/build-guide.md

2.6 KiB
Raw Permalink Blame History

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)

Configure and build

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

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