编译·调试·贡献Build & contribute

Once you can read the source, the natural next step is to act: change a line, fix a bug, add a feature, then turn it into a PR that can be merged. But "acting" has its own process - how to compile this million-line C++ project, how to confirm a change did not break something else, and what rules a PR must follow. This lesson teaches no new internals; it walks you through that real development loop end to end, so the "reading" from thirty-some lessons turns into "can change it, can contribute".

The loop is really three parts: build (use one set of CMake commands to turn source into binaries under build/bin/, flipping a flag to switch to CUDA / Metal / Vulkan and other backends), test (run automated cases with ctest, where test-backend-ops specifically checks that operators agree across backends), and contribute (open a PR per CONTRIBUTING.md: one feature per PR, CPU support first, align style with clang-format). String the three together and you have a full path from "edit code locally" to "accepted upstream". Walk this path once and the playbook for almost any unfamiliar large C++ open-source project looks much the same.

One thing must be stated up front, especially since you may be reading this course with AI help: llama.cpp's CONTRIBUTING.md has an explicit AI policy - it does not accept PRs that are fully or predominantly AI-generated, and it requires contributors to independently understand, debug, and maintain the code they submit. This lesson states that policy as-is, because it directly determines "what kind of contribution this project will accept". Roadmap: build (with a "lifecycle of one contribution" trace) -> test -> debug -> contribution rules -> two deep-dive accordions. To set the tone in one line: every tool in this lesson ultimately serves the same goal - making your change both correct and something the project can carry for the long haul.

Build: one set of CMake commands, switching backends

It all starts with the build. llama.cpp builds with CMake, and the basics are just two commands: first configure (detect the compiler and dependencies, generate the build system), then build (actually compile source into binaries). The build output lands under build/bin/ - the llama-cli and llama-server you know are right there. To switch backends (say, to use an NVIDIA GPU) you do not touch the source; you add one flag at the configure step:

# the basic build: configure + build (from docs/build.md)
cmake -B build                              # configure: detect compiler/deps, generate the build system
cmake --build build --config Release        # build: actually compile, output to build/bin/

# switching backend only changes the "configure" step, e.g. enable CUDA:
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

Each backend has a -DGGML_* flag, backed by the backend machinery from L31-L33 - the same compute graph, a different set of operator implementations. The table below lists the common backends with their flags and target platforms; pick from it before you build:

Building is only the start of the development loop. Freeze the whole "change one thing, end up merged" path into a flow and you see how build, test, and rules string into one line:

Test: ctest and test-backend-ops

After a change, how do you confirm nothing else broke? Run the tests. llama.cpp's tests are organized with CTest: a pile of test-*.cpp under tests/, registered as cases by a few macros in tests/CMakeLists.txt. The most common are llama_build_and_test (compile a test source and register it) and llama_test (register the same test program with different arguments as several cases - e.g. test-tokenizer-0 runs once per vocab). Once registered, one ctest in build/ runs them all:

# tests/CMakeLists.txt: macros register a test-*.cpp as a ctest case
llama_build_and_test(test-backend-ops.cpp)         # compile and register
llama_test(test-tokenizer-0 NAME ... ARGS ...)     # parameterized: one program, many vocabs

# run tests in build/:
ctest --test-dir build                 # run every case
ctest --test-dir build -R backend-ops  # only those whose name contains backend-ops

Tests fall into a few groups, each minding its own patch: test-tokenizer-* checks that tokenization matches the reference (recall L20), test-quantize-* checks that quantize/dequantize error stays in range (recall L06/L12), test-sampling checks the sampling logic (recall L21). But the heaviest of all is test-backend-ops: it runs every ggml operator on each backend and compares results elementwise. This is what lets llama.cpp dare to maintain a dozen-plus backends at once - if any operator on any backend is wrong, this test catches it on the spot. So it is not just "a test" but the correctness foundation of the whole multi-backend system. A note on its running cost: because it computes on several backends and compares elementwise, test-backend-ops is not fast to run; but that is exactly its value - it presses the hardest-to-eyeball bug, "might some backend quietly compute wrong", into one repeatable automated comparison, trading the machine's patience for the human's peace of mind.

Debug: Debug builds, sanitizers, and operator checking

Tests tell you "it broke"; debugging helps you find "where it broke". The first move is a Debug build (-DCMAKE_BUILD_TYPE=Debug): with debug symbols and aggressive optimization off, you can read the call stack at a crash and single-step. The second is sanitizers - CI has a dedicated build-sanitize that runs tests under ASan / UBSan, catching out-of-bounds access and undefined behavior, the kind of "usually silent, occasionally explodes" bug. When reproducing a CI failure locally, building with the same sanitizer flags often makes the problem surface at once. A handy rule of thumb: an intermittent, hard-to-reproduce crash under a Release build is almost always a memory overrun or undefined behavior - rebuild with Debug + sanitizer and rerun, and that usually beats staring at the code guessing; letting the tools catch the error scene for you is the first principle of debugging.

If you are touching a ggml operator, debugging has a dedicated weapon - the same one: test-backend-ops. It runs the operator you changed on both CPU and the target backend and compares elementwise, telling you immediately "is the result right, and from which element does it diverge". This is exactly why CONTRIBUTING calls it out: change or add a ggml operator and you must run (and extend) test-backend-ops. Add the --verbose logging of the various examples / tools and you can locate the vast majority of inference-level problems. This section only points the way - real debugging skill is earned by practice, but you should at least know where these handy tools sit. There is also a class of problems that live not in the C++ but in the Python conversion scripts or build config - there the python-lint / python-type-check CI checks are your first hint; running them locally saves a round of "submit, then find out the format fails".

Contribution rules: what kind of PR gets accepted

With the tools in hand, the last gate is the rules. CONTRIBUTING.md lists few requirements, but each exists so maintainers can take on your code for the long haul: one feature per PR (a focused change is reviewable), CPU support first (do the new thing on CPU, leave other backends to follow-up PRs), run and extend test-backend-ops if you touched a ggml operator, and align style with clang-format (clang-tools v15+). Maintainers merge by squash, with a commit title in the form <module> : <title> (#NNNN). Laid out as a pass/fail checklist:

Last, the one to take most seriously - the AI usage policy. CONTRIBUTING.md states it plainly: PRs that are fully or predominantly AI-generated are not accepted; AI-written-then-human-edited still counts as AI-generated. It requires contributors to independently understand, debug, and maintain the code they submit, to disclose how AI was used, and explicitly forbids using AI to write the human-facing parts - PR descriptions, issues, comments. The intent is not hard to see: a PR is a long-term commitment - maintainers review it, integrate it, support it for the long haul; the project never cares "where the code came from" but whether there is a person who can be responsible for it. So if you are learning this course with AI, the safest stance is: let it help you read the code, and keep "design, decisions, being able to explain the why" firmly in your own hands. Put plainly, this policy protects not the form of "handwritten only" but the substance of "someone really understands this code and can carry it when it breaks" - and that substance is exactly the state this whole course wants to bring you to: not just knowing how to use tools, but having solid ground under your feet.

Deeper: CPU-first and the CI matrix

Two accordions answering two "why is it required this way" questions - understand them and the earlier rules stop being rigid clauses and become reasoned engineering choices. This is also the right way to read the rules: do not treat them as dogma to memorize, but ask of each one "what bad case is it preventing" - once you see what is being prevented, you remember it naturally and are more willing to follow it.