如何使用buck2构建系统管理大型c++ monorepo？ (Facebook出品)

buck2不适合直接管理大型c++ monorepo，因其默认配置会导致链接时间爆炸、头文件依赖爆炸、增量编译失效和远程缓存命中率低，且开源版缺乏facebook内部自研的分布式调度器、定制工具链与头文件指纹机制。

为什么 buck2 不适合直接管理大型 C++ monorepo？

它不是不能用，而是默认配置和常见实践会迅速暴露瓶颈：链接时间爆炸、头文件依赖爆炸、增量编译失效、远程缓存命中率低。Facebook 内部的 buck2 重度依赖自研的分布式构建调度器、定制化的 C++ 工具链（如 clang++-fb）、以及与内部源码管理系统深度集成的头文件指纹机制——这些全都不开源。

必须重写 toolchain 和 cxx_library 规则才能跑通

开源版 buck2 自带的 cxx 规则仅支持基础编译，无法处理大型项目常见的预编译头（PCH）、模块接口单元（C++20 Modules）、或细粒度头文件导出控制。你得自己定义 toolchain 并覆盖默认行为：

• 用 precompiled_header 属性显式声明 PCH，否则每个 cxx_library 都会重复解析标准库头文件
• 禁用默认的 header_mode = "SYMLINK"，改用 "copy" 或自定义 symlink 策略，避免 NFS 或容器挂载下的 inode 不一致问题
• 所有 cxx_library 必须显式声明 exported_headers，隐式包含（#include "foo.h" 而非 #include "third_party/foo.h"）会导致依赖图错误

toolchain(     name = "my_toolchain",     cxx = "//tools:clang",     cxx_flags = [         "-fno-rtti",         "-fno-exceptions",         "-Werror=return-type",     ],     precompiled_header = ":std_pch", )

buck2 build //... --show-output 会卡死？这是正常现象

在 >10k target 的 C++ monorepo 中，buck2 的目标图解析阶段（target graph resolution）本身不并行，且会加载全部 BUCK 文件并执行 Starlark 解析。这不是 bug，是设计取舍。应对方式只有三条：

• 永远不用 //...，改用 //src/... //lib/... 显式限定子树
• 把巨型 BUCK 拆成按目录层级嵌套的小文件，用 subinclude() 控制加载范围
• 启用 --unstable-enable-target-graph-cache（v2024.05+），但需确保所有 Starlark 函数是纯函数（无 read_file、无环境变量读取）

远程缓存几乎必然失效，除非你控制所有构建环境

buck2 的缓存 key 包含完整的 toolchain hash、所有输入文件 content hash、甚至 host OS 的 glibc 版本字符串。CI 使用 ubuntu 22.04，本地用 macOS，哪怕代码完全一样，缓存也 100% miss。真实可行的做法只有：

立即学习“C++免费学习笔记（深入）”；

• 强制统一所有环境使用 docker + FROM quay.io/facebook/buck2:latest
• 在 .buckconfig 中禁用 host-specific 变量：build.host_info = false
• 把所有第三方依赖（fmt、abseil）打包为预编译 prebuilt_cxx_library，而非从源码构建

头文件变更仍是最大痛点：一个 base/status.h 修改，可能触发 3000+ targets 重编译。没有 Facebook 内部的头文件依赖压缩算法，就只能靠人工拆分接口层与实现层，别无他法。