llama.cpp 二进制改名迁移实战：deprecation-warning 机制解析与新旧二进制名对照全表

2024 年 6 月 12 日，llama.cpp 将所有命令行工具统一加上 llama- 前缀（main 更名为 llama-cli，server 更名为 llama-server，以此类推），这是一次典型的破坏性变更。本文基于仓库中的迁移公告文档 examples/deprecation-warning/README.md 及其配套的警告桩程序 deprecation-warning.cpp，完整给出新旧二进制名对照表，并从源码层面剖析 llama.cpp 如何用一段几十行的 C++ 代码把"旧入口"变成"运行时自举警告"，帮助读者平滑升级自己的脚本与 CI 工作流。

一、迁移背景：为什么需要加 llama- 前缀

examples/deprecation-warning/README.md 开头即标注了迁移的时间点与动机：

[2024 Jun 12] Binaries have been renamed w/ a llama- prefix. main is now llama-cli, server is llama-server, etc.

该文档明确指出，这次改名虽然必要，但属于 breaking change，且对终端用户来说往往不会立即察觉，因此项目方要求"请更新所有脚本与工作流以使用新的二进制名"。

从当前仓库的目录结构可以印证这次迁移的最终形态：各工具均已按新命名规范组织在 tools/ 下，例如：

• tools/cli/ 构建 llama-cli（即原 main）；
• tools/server/ 构建 llama-server（即原 server）；
• tools/perplexity/、tools/quantize/、tools/tokenize/ 分别构建 llama-perplexity、llama-quantize、llama-tokenize；
• tools/llama-bench/ 构建 llama-bench（名称本就带前缀，未变）；
• examples/embedding/ 构建 llama-embedding，tools/gguf-split/、tools/imatrix/、tools/export-lora/ 等同样遵循 llama- 前缀。

带统一前缀带来的直接好处是：在共享二进制目录、PATH 聚合、容器镜像等场景中，llama.cpp 的工具不会与系统或其他项目中的 main、server、tokenize、quantize 等通用名称发生冲突。

二、新旧二进制名完整对照表

以下是原文档给出的完整迁移对照表，共 29 项。升级脚本时应逐项核对：

旧文件名	新文件名
main	llama-cli
server	llama-server
llama-bench	llama-bench
embedding	llama-embedding
quantize	llama-quantize
tokenize	llama-tokenize
export-lora	llama-export-lora
libllava.a	libllava.a
baby-llama	llama-baby-llama
batched	llama-batched
batched-bench	llama-batched-bench
benchmark-matmult	llama-benchmark-matmult
convert-llama2c-to-ggml	llama-convert-llama2c-to-ggml
eval-callback	llama-eval-callback
gbnf-validator	llama-gbnf-validator
gguf	llama-gguf
gguf-split	llama-gguf-split
gritlm	llama-gritlm
imatrix	llama-imatrix
infill	llama-infill
llava-cli	llama-llava-cli
lookahead	llama-lookahead
lookup	llama-lookup
lookup-create	llama-lookup-create
lookup-merge	llama-lookup-merge
lookup-stats	llama-lookup-stats
parallel	llama-parallel
passkey	llama-passkey
perplexity	llama-perplexity
q8dot	llama-q8dot
quantize-stats	llama-quantize-stats
retrieval	llama-retrieval
save-load-state	llama-save-load-state
simple	llama-simple
speculative	llama-speculative
vdot	llama-vdot
tests/test-c.o	tests/test-c.o

注意表中有三项是"无变化"的：llama-bench（本就带前缀）、libllava.a（静态库文件）、tests/test-c.o（测试目标文件）。这说明本次迁移的规则是补齐缺失的 llama- 前缀，而非无差别改名。

三、deprecation-warning 程序源码解析：旧名字的运行时"自举警告"

llama.cpp 处理这类破坏性变更的工程手段很巧妙：对于部分已被废弃的旧入口名，构建系统会把一个统一的"警告桩"程序编译成该旧名字。用户如果仍按旧名字调用二进制，程序不会静默执行错误逻辑，而是立即打印迁移提示并以非零码退出。

其全部实现就在 examples/deprecation-warning/deprecation-warning.cpp 中，核心逻辑如下：

// 1) 从 argv[0] 取得程序名，并只保留路径中的最后一段
std::string filename = "main";
if (argc >= 1) {
    filename = argv[0];
}
auto pos = filename.find_last_of("/\\");
if (pos != std::string::npos) {
    filename = filename.substr(pos + 1);
}

// 2) 默认替换规则：在文件名前拼接 "llama-"
auto replacement_filename = "llama-" + filename;

// 3) 特例：旧名 "main" 对应的新名是 "llama-cli" 而非 "llama-main"
if (filename == "main") {
    replacement_filename = "llama-cli";
}

// 4) 打印警告并返回失败退出码
fprintf(stdout, "\n");
fprintf(stdout, "WARNING: The binary '%s' is deprecated.\n", filename.c_str());
fprintf(stdout, " Please use '%s' instead.\n", replacement_filename.c_string());
fprintf(stdout, " See ...examples/deprecation-warning/README.md for more information.\n");
fprintf(stdout, "\n");

return EXIT_FAILURE;

从源码结构看，这个桩程序有几个值得注意的设计点：

1. 自我感知（self-identifying）：它不依赖任何编译期宏或硬编码名字，而是解析 argv[0] 反推自己当前的可执行文件名（并兼容 / 与 \ 两种路径分隔符）。同一份源码可以编译成任意多个旧名字，运行时都能报出正确的"旧名 → 新名"映射。
2. 通用规则 + 单点特例：绝大多数旧名只需机械地加 llama- 前缀；唯一的例外是 main → llama-cli，因为 CLI 工具的新名字取的是语义名而非机械前缀拼接。这与第二节对照表完全一致。
3. 失败退出码：return EXIT_FAILURE; 保证自动化脚本（set -e 的 shell、CI 流水线）不会在旧二进制上继续静默运行，而是立刻暴露迁移问题。
4. 可追溯的提示文案：警告信息中直接指向迁移公告文档 examples/deprecation-warning/README.md，让用户能一步查到完整对照表。

四、实战案例：mtmd 模块如何用警告桩替代已废弃的旧 CLI

该桩程序在当前仓库中有一个真实的生产级用法：多模态模块 tools/mtmd/ 曾用多个独立的视觉模型 CLI（llava-cli、gemma3-cli 等），后来统一收敛为 llama-mtmd-cli。为了保证旧名字不会悄悄消失或产生误导，tools/mtmd/CMakeLists.txt 直接把 deprecation-warning.cpp 编译成这些旧名字：

if (LLAMA_BUILD_TOOLS)
    add_executable(llama-llava-cli    deprecation-warning.cpp)
    add_executable(llama-gemma3-cli   deprecation-warning.cpp)
    add_executable(llama-minicpmv-cli deprecation-warning.cpp)
    add_executable(llama-qwen2vl-cli  deprecation-warning.cpp)

    set(TARGET llama-mtmd-cli)
    add_executable         (${TARGET} mtmd-cli.cpp)
    set_target_properties  (${TARGET} PROPERTIES OUTPUT_NAME llama-mtmd-cli)
    ...

即：用户若仍调用 llama-llava-cli（或 llama-gemma3-cli、llama-minicpmv-cli、llama-qwen2vl-cli），得到的将是"该二进制已废弃，请使用 llama-<旧名> 之外的统一入口"这类警告，而真正可用的统一入口是紧随其后构建的 llama-mtmd-cli。这正是"第二节对照表中 llava-cli → llama-llava-cli"这一行在构建层面的落地方式。

值得注意的是，这四个警告桩的构建受 LLAMA_BUILD_TOOLS 开关控制（见 tools/mtmd/CMakeLists.txt 上方注释）：在仅打包库的独立构建场景（例如 Apple XCFramework 打包，LLAMA_BUILD_MTMD=ON 且 LLAMA_BUILD_TOOLS=OFF）下会整体跳过这些可执行文件，只保留库本身。

此外，CODEOWNERS 将 /examples/deprecation-warning/ 目录指定给核心维护者，说明该迁移公告与警告机制属于仓库中受重点看护的部分。

五、脚本与工作流迁移清单

结合上述文档与源码，给出一套可落地的升级步骤：

1. 全局替换：在自有脚本、Makefile、Dockerfile、CI 配置中，按第二节对照表将旧名批量替换为新名。最常见的两个高频入口是 main → llama-cli 与 server → llama-server。
2. 保留无变化项：llama-bench、libllava.a、tests/test-c.o 无需改动，避免误改。
3. 运行验证：升级后的构建产物中，若某个旧名仍存在且执行后打印 WARNING: The binary 'xxx' is deprecated. Please use 'llama-xxx' instead. 并以非零码退出，说明该二进制已变为警告桩，必须把调用方切到新名字（机制见第三节）。
4. 定位新入口：当前仓库中各工具的标准位置是 tools/CMakeLists.txt 列出的子目录——completion、perplexity、quantize、tokenize、mtmd 等在非 Emscripten 构建下默认参与构建；cli、server、ui 则额外受 LLAMA_BUILD_SERVER 开关控制。
5. 多模态场景专项：若流程中仍在调用 llava-cli、gemma3-cli、minicpmv-cli、qwen2vl-cli 系列旧 CLI，应统一迁移到 llama-mtmd-cli（构建配置见 tools/mtmd/CMakeLists.txt）。

小结

llama.cpp 的二进制改名迁移展示了 C++ 工程项目处理破坏性变更的完整闭环：一份逐项列明的对照表文档（examples/deprecation-warning/README.md）负责"告知"，一个自我感知、统一复用的警告桩程序（deprecation-warning.cpp）负责"兜底"，CMake 构建配置（tools/mtmd/CMakeLists.txt）负责"执行"。读者只需记住三步——对照表格全局替换、以非零退出码作为迁移是否彻底的信号、按当前 tools/ 目录结构确认新入口位置——即可安全完成从旧二进制名到新命名的全部升级。