本文档解释了 llama.cpp 中使用的构建系统，涵盖了可用的构建方法、配置选项以及如何为不同平台以及各种优化选项编译项目。构建系统主要基于 CMake，并支持 Nix 和直接 Makefile 构建。
llama.cpp 存储库使用灵活的构建系统，支持
构建系统允许配置大量选项，包括硬件加速后端（CUDA、Metal、Vulkan 等）、特定于架构的优化（AVX、AVX2、NEON 等）以及各种构建目标（库、CLI 应用程序、服务器、示例、测试）。
来源：.github/workflows/build.yml1-1062 flake.nix1-186 ggml/CMakeLists.txt1-362 tests/CMakeLists.txt51-81
CMake 是 llama.cpp 的主要构建系统。它提供了一种在不同平台上一致编译项目的方法，同时支持各种后端和优化选项。
CMake 项目通过特定的后端管理函数进行分层组织
来源：ggml/CMakeLists.txt236 ggml/src/CMakeLists.txt287-322 ggml/src/ggml-cpu/CMakeLists.txt1-8 common/CMakeLists.txt49-53 tests/CMakeLists.txt51-81
使用 CMake 构建 llama.cpp
构建系统通过 -D 标志公开了许多可配置选项
| 选项 | 描述 | 默认 |
|---|---|---|
BUILD_SHARED_LIBS | 构建共享库 | ON（MinGW 和 WebAssembly 除外） |
GGML_BACKEND_DL | 将后端构建为动态库 | OFF |
GGML_STATIC | 静态链接库 | OFF |
GGML_NATIVE | 优化当前 CPU | ON（除非交叉编译） |
GGML_LTO | 启用链接时优化 | OFF |
GGML_CCACHE | 可用时使用 ccache | ON |
GGML_ALL_WARNINGS | 启用所有编译器警告 | ON |
GGML_FATAL_WARNINGS | 启用 -Werror 标志 | OFF |
GGML 张量库使用通过 ggml_add_backend() 进行动态后端注册的系统
| 选项 | 描述 | 默认 | 注册 |
|---|---|---|---|
GGML_CPU | 启用 CPU 后端 | ON | ggml_add_backend(CPU) |
GGML_CUDA | 启用 CUDA 后端 | OFF | ggml_add_backend(CUDA) |
GGML_METAL | 启用 Metal 后端 | ON（macOS） | ggml_add_backend(METAL) |
GGML_VULKAN | 启用 Vulkan 后端 | OFF | ggml_add_backend(Vulkan) |
GGML_SYCL | 启用 SYCL 后端 | OFF | ggml_add_backend(SYCL) |
GGML_OPENCL | 启用 OpenCL 后端 | OFF | ggml_add_backend(OpenCL) |
GGML_BLAS | 使用 BLAS | OFF（macOS 为 ON） | ggml_add_backend(BLAS) |
GGML_KOMPUTE | 使用 Kompute 后端 | OFF | ggml_add_backend(Kompute) |
GGML_RPC | 使用 RPC 后端 | OFF | ggml_add_backend(RPC) |
GGML_HIP | 为 AMD GPU 使用 HIP | OFF | ggml_add_backend(HIP) |
GGML_CANN | 为华为 Ascend 使用 CANN | OFF | ggml_add_backend(CANN) |
GGML_MUSA | 为 Moore Threads 使用 MUSA | OFF | ggml_add_backend(MUSA) |
来源：ggml/CMakeLists.txt155-204 ggml/src/CMakeLists.txt312-322
构建系统可以自动检测并启用特定于架构的优化
来源：ggml/src/ggml-cpu/CMakeLists.txt90-368
构建系统产生的主要目标包括
| 目标 | 描述 |
|---|---|
libllama | 核心库 |
llama-cli | 命令行界面 |
llama-server | 用于服务模型的 HTTP 服务器 |
llama-quantize | 模型量化工具 |
llama-embedding | 嵌入生成工具 |
| 测试 | 各种测试可执行文件 |
| 示例 | 各种示例应用程序 |
来源：.github/workflows/build.yml65-69 examples/server/CMakeLists.txt1-51
该项目还包括一个 Nix 构建系统，支持跨环境的可复现构建。该系统定义在 flake.nix 文件以及 .devops/nix/ 目录下的各种文件中。
来源：flake.nix1-186 .devops/nix/scope.nix1-42 .devops/nix/package.nix1-247 .devops/nix/docker.nix1-38 .devops/nix/sif.nix1-28 .devops/nix/jetson-support.nix1-40
Nix 构建选项在 package.nix 中定义，并包含与 CMake 系统类似的选项
| 选项 | 描述 | 默认 |
|---|---|---|
useBlas | 使用 BLAS | 取决于平台 |
useCuda | 使用 CUDA | 取决于 config.cudaSupport |
useMetalKit | 使用 MetalKit | Apple ARM 上为 True |
useMpi | 使用 MPI | 否 |
useRocm | 使用 ROCm | 取决于 config.rocmSupport |
useVulkan | 使用 Vulkan | 否 |
enableCurl | 启用 Curl 支持 | True |
enableStatic | 构建静态库 | 取决于平台 |
来源：.devops/nix/package.nix21-43
Nix Flake 产生多个输出
| 输出 | 描述 |
|---|---|
默认 | 默认 CPU 后端构建 |
vulkan | 构建 Vulkan 支持 |
windows | Windows 交叉编译构建 |
python-scripts | Python 脚本包 |
cuda | 构建 CUDA 支持 |
mpi-cpu | 构建 MPI 支持 |
rocm | 构建 ROCm 支持 |
来源： flake.nix157-172
该项目使用 GitHub Actions，其中包含特定于作业的 CMake 配置和 ctest 执行。
来源： .github/workflows/build.yml1-25 .github/workflows/build.yml47-96 .github/workflows/build.yml157-209
CI 工作流程使用特定的 CMake 命令模式来处理不同的配置
每个作业都运行 ctest，带有标签： ctest -L 'main|curl' --verbose --timeout 900
来源： .github/workflows/build.yml47-56 .github/workflows/build.yml135-138 .github/workflows/build.yml832-840 .github/workflows/build.yml421-426 .github/workflows/build.yml665-666 .github/workflows/build.yml142-144
以下是一些常见的构建场景
构建系统支持使用 ggml_add_cpu_backend_variant() 构建优化的变体
函数 ggml_add_cpu_backend_variant_impl() 用于创建专用后端库
| 变体名称 | 特性 | 目标函数调用 |
|---|---|---|
x64 | 基础 x64 | ggml_add_cpu_backend_variant(x64) |
sse42 | SSE42 | ggml_add_cpu_backend_variant(sse42, SSE42) |
sandybridge | SSE42, AVX | ggml_add_cpu_backend_variant(sandybridge, SSE42, AVX) |
haswell | SSE42, AVX, F16C, AVX2, BMI2, FMA | ggml_add_cpu_backend_variant(haswell, SSE42, AVX, F16C, AVX2, BMI2, FMA) |
skylakex | SSE42, AVX, F16C, AVX2, BMI2, FMA, AVX512 | ggml_add_cpu_backend_variant(skylakex, SSE42, AVX, F16C, AVX2, BMI2, FMA, AVX512) |
icelake | skylakex + AVX512_VBMI, AVX512_VNNI | ggml_add_cpu_backend_variant(icelake, ..., AVX512_VBMI, AVX512_VNNI) |
alderlake | SSE42, AVX, F16C, AVX2, BMI2, FMA, AVX_VNNI | ggml_add_cpu_backend_variant(alderlake, ..., AVX_VNNI) |
sapphirerapids | icelake + AVX512_BF16, AMX_TILE, AMX_INT8 | ggml_add_cpu_backend_variant(sapphirerapids, ..., AMX_TILE, AMX_INT8) |
来源： ggml/src/CMakeLists.txt289-310 ggml/src/ggml-cpu/CMakeLists.txt1-8
构建系统支持交叉编译到不同的平台
来源： .github/workflows/build.yml607-707 .github/workflows/build.yml752-800
构建系统配置分布在几个关键文件中
来源： ggml/CMakeLists.txt1-362 ggml/src/CMakeLists.txt1-343 ggml/src/ggml-cpu/CMakeLists.txt1-483 common/CMakeLists.txt1-145 tests/CMakeLists.txt1-161 examples/server/CMakeLists.txt1-51 flake.nix1-186 .github/workflows/build.yml1-1062
缺失的依赖项：确保您拥有所选后端所需的依赖项
CMake 配置问题：如果 CMake 找不到依赖项，您可能需要使用 CMake 变量手动指定其路径，例如
优化编译错误：如果使用特定架构优化进行构建导致编译错误，请尝试禁用它们
链接错误：使用多个后端进行构建时，请确保所有必需的库都可用。对于静态构建，请添加 -DLLAMA_STATIC=ON 以避免动态链接问题。
来源： .github/workflows/build.yml183-218 ggml/src/CMakeLists.txt69-88
在 Windows 上，构建系统同时支持 MSVC 和 MinGW 编译器
在运行 Apple Silicon 的 macOS 上，Metal 默认启用
在带 CUDA 的 Linux 上，请指定架构能力
来源： .github/workflows/build.yml752-982 .github/workflows/build.yml183-218 .github/workflows/build.yml984-1017