从一条构建命令，走到二进制世界

我曾经也习惯把 CMake、编译器、运行库统称为“工具链”，直到一次二进制兼容问题迫使我逐项核对，才发现这个词把太多责任压进了一个盒子。这里是原 XMind 的网页化重绘版：它保留“CMake → 原生构建系统 → 二进制工具链”的主干，并把最容易被一句“MSVC 工具链”掩盖的内部组件全部展开。

原来的三层模型——CMake、构建系统、工具链——是正确的，但最下面的“工具链”仍然太大。真正遇到二进制兼容问题时，必须继续拆。

术语必须精确到组件

CMakeLists.txt
   │  CMake -G Ninja
   ▼
build.ninja
   │  Ninja 调度
   ├── clang-cl /c a.cpp  ──► a.obj
   ├── clang-cl /c b.cpp  ──► b.obj
   └── lld-link a.obj b.obj libc++.lib ... ──► app.exe

CMake 不编译代码，Ninja 也不理解 C++ 语义。CMake 生成规则，Ninja 执行规则，编译器生成目标文件，链接器才把它们组装起来。

// 源代码
void* p = malloc(128);

// Clang 的任务（概念化）
// 1. 按 Microsoft x64 调用约定准备参数
// 2. 生成对 malloc 符号的调用

// 链接与运行时的任务
// 3. 从 Microsoft CRT 找到 malloc 的实现
// 4. 在程序运行时真正执行内存分配

编译器并不需要亲自实现 malloc。只要它生成的调用方式、符号和目标文件格式与运行时遵守同一份合同，就可以使用那个运行时。

API 是源码层面的接口，ABI 是编译以后仍必须一致的规则。ABI 通常包括：

Clang 在 Windows 的 MSVC target 下会生成 COFF，并努力兼容 Microsoft C++ ABI；clang-cl 还提供与 cl.exe 相似的命令行界面。这就是混用成为可能的基础。

Target triple 决定“面向哪个二进制世界”

x86_64-pc-windows-msvc
│      │  │       └── ABI / 环境：Microsoft
│      │  └────────── OS：Windows
│      └───────────── Vendor：pc（通常不是兼容判断重点）
└──────────────────── Architecture：x86-64

x86_64-w64-windows-gnu   // 同样是 Windows，但属于 MinGW/GNU 环境

“都由 Clang 编译”或“都运行在 Windows”都不足以证明兼容。至少还需确定环境字段、对象格式、运行时选择以及库自身的 ABI 配置。

接口类型决定跨模块风险

现代 Microsoft CRT 的实际拆分

工程口语中的“MSVC runtime”有时泛指前三项，但排错时必须说出具体库名。尤其是 _CxxFrameHandler3 属于异常处理支撑，而 std::string 属于 C++ 标准库；它们不是同一层问题。

这套交付包不是“Clang 使用整套 MSVC C++ 库”，而是把多家组件拼成一套满足 Chromium 二进制约束的组合。

build_client.bat
      │
      ├── 编译器：clang-cl 17
      ├── 目标：Windows x86 / COFF / Microsoft ABI
      ├── C++ 标准库：Chromium 同版本 libc++
      │                 ABI namespace = std::__Cr
      ├── C / 平台运行时：Microsoft CRT，/MT
      ├── 编译器辅助运行时：clang_rt.builtins-i386.lib
      └── 链接器：lld-link
                         │
                         ▼
                  client.lib + client.dll

为什么 std::__Cr 很重要

标准只规定源码里写 std::string，并不规定某一家标准库内部必须怎样布局。libc++ 默认使用类似 std::__1 的 inline ABI namespace，vendor 可在构建时通过 LIBCXX_ABI_NAMESPACE 定制。Chromium 的配置表现为 std::__Cr::basic_string；它改变名称修饰，用于隔离不同 libc++ 实例，但名字隔离并不会自动证明布局和配置一致。

还必须匹配 __config_site 中的 ABI flags。LLVM 明确指出，部分 ABI flags 会改变 basic_string、容器、智能指针等可观察类型的布局；这些 flags 应由 vendor 在构建 libc++ 时确定，而不是由使用者临时拼凑。

从源文件到 client.dll 的符号责任链

client.cpp
  │ include libc++/string + Chromium __config_site
  ▼
clang-cl 17  ── 语义/模板实例化/LLVM CodeGen
  │            └─ 生成 i686-pc-windows-msvc 的 COFF .obj
  │
  ├─ 未定义 C++ 标准库符号 ───────► libc++.lib
  ├─ 未定义 C / heap / stdio 符号 ─► libucrt.lib       (/MT)
  ├─ 未定义 EH / RTTI / startup ───► libvcruntime.lib  (/MT)
  ├─ 未定义 LLVM builtins ─────────► clang_rt.builtins-i386.lib
  └─ Win32 API 导入符号 ───────────► Windows SDK import libraries
                                      │
                                      ▼
                                  lld-link
                                      │
                                      ▼
                              client.dll + client.lib

clang-cl /MT source.cpp   // Clang 编译 + 静态 Microsoft CRT
clang-cl /MD source.cpp   // Clang 编译 + DLL 版 Microsoft CRT

// /MT 并不等于“用 cl.exe 编译”
// /MD 也不等于“整个程序只有一个堆”

Microsoft 文档要求同一次链接中的模块使用一致的运行时选项。工程上还要进一步约束 DLL 边界的所有权，因为独立构建的 DLL、插件与第三方分配器仍可能形成不同的内存域。

// 推荐：C ABI + 明确所有权
extern "C" {
  struct ClientResult {
    int code;
    const char* message;
  };

  ClientResult client_login(const char* username);
  void client_release_message(const char* message);
}

// 高风险：跨 DLL 暴露标准库实现细节
std::string client_login(std::vector<User> users);

C ABI 不是绝对无风险，但它显著缩小了兼容面。仍需固定结构体对齐、整数宽度、字符编码、调用约定、版本字段和内存所有权。

CMake 的 Generator 决定生成哪种原生构建文件；编译器、运行时和具体参数是另一组选择。以 Ninja + clang-cl 为例：

# 首次配置构建目录时选择 Generator 和编译器
cmake -S . -B build -G Ninja \
  -DCMAKE_C_COMPILER=clang-cl \
  -DCMAKE_CXX_COMPILER=clang-cl

# CMakeLists.txt：选择 MSVC ABI 风格工具链下的 CRT 模式
set(CMAKE_MSVC_RUNTIME_LIBRARY
    "MultiThreaded$<$<CONFIG:Debug>:Debug>")

# 使用非默认 libc++ 时，最好封装成专门的 toolchain/preset，
# 集中管理 include 顺序、库目录、ABI 宏、默认库抑制和链接依赖。

一个更准确的配置坐标

Build Configuration = {
  generator:      Ninja,
  compiler:       clang-cl 17,
  target:         i686-pc-windows-msvc,
  object_format:  COFF,
  cxx_abi:        Microsoft ABI,
  cxx_library:    Chromium libc++ / std::__Cr,
  c_runtime:      Microsoft CRT static (/MT),
  compiler_rt:    compiler-rt builtins,
  linker:         lld-link,
  sdk:            Windows SDK,
  flags_and_macros: exactly matched
}

默认库机制也是构建的一部分

在 MSVC 风格工具链中，编译器驱动与头文件可能通过对象文件的 .drectve 段写入 /DEFAULTLIB 指令，链接器据此自动选择库。使用 /NODEFAULTLIB、自定义 libc++ 或手写链接命令时，相当于接管这套责任，必须显式补齐 UCRT、VCRuntime、builtins、系统导入库及正确顺序。

1. 先确认真实命令。开启 verbose 构建，看到底调用了哪个编译器、链接器和参数，不依据 IDE 页面猜测。
2. 确认头文件来源。使用 /showIncludes 检查 <string> 究竟来自 libc++ 还是 Visual Studio。
3. 确认目标三元组与架构。x86、x64、ARM64 不能混；MSVC target 与 MinGW target 也不是同一生态。
4. 检查符号风格。dumpbin /symbols、llvm-nm 可帮助识别 std::__Cr、MSVC 名字修饰和缺失符号。
5. 检查默认链接库。/VERBOSE:LIB 可以看到链接器为何选中某个库、符号由谁提供。
6. 核对 ABI 宏和配置头。标准库 ABI namespace、iterator debug、异常、RTTI、结构体对齐都可能改变合同。
7. 审查模块边界。搜索跨 DLL 的 STL 类型、异常、new/delete、FILE*、locale 和回调调用约定。
8. 最后做运行验证。符号检查只证明“看起来像”，不能代替真实调用路径、异常路径和内存释放测试。

权威资料