企业官网建设流程全解析

Apache brpc 是一个用 C++ 编写的工业级 RPC 框架，源码与构建产物天然为 CMake 体系设计，其官方 Bazel 支持以"第三方依赖"形态交付。本文基于仓库中的 docs/cn/bazel_support.md 及配套示例目录展开，完整讲解：为什么 bRPC 需要手动补齐部分依赖、如何把brpc_workspace.bzl与各.BUILD文件搬入你的项目、如何在 WORKSPACE 中注册依赖、以及最终在 BUILD 文件里通过@apache_brpc//:bthread等目标完成链接。读完本文，你可以在一小时内把 bRPC 作为 Bazel 外部依赖接入自己的 C++ 项目并成功构建出可运行的可执行文件。

一、背景：为什么 bRPC 作为 Bazel 依赖需要"手动补齐"

Bazel 通过 WORKSPACE 声明外部仓库（external repository），而每个外部仓库都必须能被 Bazel 识别：要么该仓库自带BUILD/BUILD.bazel文件，要么由使用方提供独立的*.BUILD文件。

bRPC 自身依赖了 protobuf、leveldb、zlib、gflags、OpenSSL 等一批开源库，而这些库（尤其是其中的 C 库与历史版本）大多没有随上游源码提供 Bazel 构建描述。文档第一条明确指出了这一点：

bRPC 依赖于一些开源库, 但这些库并没有提供 bazel 支持, 所以需要你手动将一部分依赖加入到你的构建项目中。

这正是 bRPC 的 Bazel 接入无法做到"一条http_archive搞定"的根本原因。仓库通过 example/build_with_bazel/ 目录给出了官方认可的解法：用一套手工编写的.BUILD文件把没有 Bazel 支持的依赖"补上构建描述"，再用一个brpc_workspace.bzl把整个依赖注册过程封装成一个可复用的 Bazel 函数。

二、三步接入流程总览

文档给出的接入流程可以归纳为三步：

其中步骤 1 与步骤 2 是"一次性"的仓库级配置，步骤 3 是每个使用 bRPC 的编译目标都要做的事。下面逐一展开。

三、步骤一：复制.BUILD文件到项目根目录

需要复制的文件全部位于仓库的 example/build_with_bazel/ 目录下，包括：

• protobuf.BUILD：为 protobuf 3.19.1 提供cc_library("protobuf")、cc_library("protobuf_lite")、cc_library("protoc")、cc_library("protoc_lib")等目标，并裁剪了上游 BUILD 中非 C++ 的规则；
• leveldb.BUILD：为 leveldb 指定版本提供cc_library("leveldb")，内含完整的 db/、table/、util/、port/ 源码清单；
• zlib.BUILD：为 zlib 1.2.11 提供cc_library("zlib")；
• openssl.BUILD：为系统安装的 OpenSSL 提供cc_library("crypto")与cc_library("ssl")两个薄封装目标；
• brpc_workspace.bzl：封装所有外部仓库注册逻辑的 Starlark 文件。

从源码看，这些.BUILD文件都以package(default_visibility = ["//visibility:public"])开头（见 example/build_with_bazel/leveldb.BUILD），保证子项目任意包都能引用其中的目标。

3.1 为什么是"移动到项目根目录"

brpc_workspace.bzl内部使用build_file = "//:protobuf.BUILD"这样的标签来引用.BUILD文件（见 example/build_with_bazel/brpc_workspace.bzl）。//:xxx是"当前仓库根包"的写法，因此这些.BUILD文件必须与你的 WORKSPACE 同级，位于项目根目录，否则标签解析会失败。这是官方设计上的硬性约定，不能随意挪到子目录。

四、步骤二：在 WORKSPACE 中注册brpc_workspace()

将文件就位后，在项目根目录的WORKSPACE文件中追加文档给出的两行：

load("@//:brpc_workspace.bzl", "brpc_workspace") brpc_workspace();

• load("@//:brpc_workspace.bzl", ...)从当前仓库（@//）根包加载brpc_workspace.bzl中的brpc_workspace符号；
• brpc_workspace()一次性完成所有外部依赖的注册。

仓库自带的官方示例 example/build_with_bazel/WORKSPACE 正是这样写的：

workspace(name = "brpc_test") load("@//:brpc_workspace.bzl", "brpc_workspace") brpc_workspace();

需要说明的是，示例使用的是经典 WORKSPACE 体系（workspace()声明）；如果你的项目启用了 Bzlmod，需要把brpc_workspace()的注册内容迁移到WORKSPACE.bzlmod对应的模块依赖机制中，这一点下文第五节会进一步解释。

五、深入brpc_workspace.bzl：依赖注册的完整清单

brpc_workspace()是整个接入方案的核心。对照 example/build_with_bazel/brpc_workspace.bzl，它依次注册了以下外部仓库：

几个值得注意的实现细节：

1. protobuf 需要打补丁。brpc_workspace.bzl对 protobuf 使用了patch_cmds/patch_cmds_win，删除protobuf.bzl中第 4 行与 417~508 行之间与 C++ 构建无关的规则（example/build_with_bazel/brpc_workspace.bzl），使其能被精简版protobuf.BUILD正确加载；Windows 下则通过 PowerShell 等价操作实现（patch_cmds_win），说明该方案同时考虑了 Linux/macOS 与 Windows 环境。

2. OpenSSL 直接复用系统安装。openssl通过native.new_local_repository(name = "openssl", path = "/usr", build_file = "//:openssl.BUILD")指向本机/usr（example/build_with_bazel/brpc_workspace.bzl），即依赖系统级 OpenSSL 头文件与动态库。对应地，example/build_with_bazel/openssl.BUILD 在非 macOS 平台通过linkopts = ["-lcrypto"]/["-lssl"]直接链接系统库，仅在 macOS 下改为链接/usr下的libcrypto.dylib/libssl.dylib。这意味着构建机必须预先安装 OpenSSL 开发包。

3. bRPC 本体自带 BUILD 文件。apache_brpc直接http_archive拉取 brpc-1.3.0 源码包（example/build_with_bazel/brpc_workspace.bzl），该包自带仓库根目录的BUILD.bazel，无需外部提供.BUILD。

4. 校验与来源。protobuf、zlib 均给出了sha256固定校验和；所有仓库均使用固定版本号或固定 commit 的strip_prefix快照，保证构建可复现。

六、步骤三：在 BUILD 文件中链接 bRPC 目标

接入的最后一步，是在需要使用 bRPC 的编译目标中声明依赖。文档给出的链接清单为：

... deps = [ "@apache_brpc//:bthread", "@apache_brpc//:brpc", "@apache_brpc//:butil", "@apache_brpc//:bvar", ] ...

这 4 个目标都定义在 bRPC 仓库根目录的 BUILD.bazel 中，其依赖关系为：

• @apache_brpc//:butil：基础工具库，直接依赖 gflags、zlib、protobuf 以及 OpenSSL/BoringSSL（见 BUILD.bazel）；
• @apache_brpc//:bvar：多线程计数器与指标库，依赖:butil（见 BUILD.bazel）；
• @apache_brpc//:bthread：M:N 协程调度库，依赖:butil与:bvar（见 BUILD.bazel）；
• @apache_brpc//:brpc：RPC 框架本体，依赖:bthread、:butil、:bvar、:json2pb、:mcpack2pb、leveldb 及内部 proto（见 BUILD.bazel）。

从上述依赖关系可以看出，@apache_brpc//:brpc本身已经传递性地包含了 bthread/butil/bvar，文档同时列出全部 4 个目标是为了显式声明、便于读者按需取用（例如只用 bthread 写协程程序时，可以只依赖@apache_brpc//:bthread，避免链接整个 RPC 框架）。另外，BUILD.bazel 通过//bazel/config:brpc_with_thrift的select支持按配置开关启用 thrift 协议支持，brpc目标的deps中也包含相应的select分支，说明 bRPC 的 Bazel 目标支持通过 config_setting 做特性裁剪。

6.1 官方示例：一个完整的可构建样例

仓库在 example/build_with_bazel/BUILD.bazel 给出了完整可运行的示例目标：

cc_binary( name = "test", srcs = ["test.cc"], deps = [ "@apache_brpc//:brpc", "@apache_brpc//:bthread", "@apache_brpc//:bvar", "@apache_brpc//:butil", ], )

对应源码 example/build_with_bazel/test.cc 只使用 bthread 启动一个后台协程并打印I Love bRPC：

#include <bthread/bthread.h> void *PrintHellobRPC(void *arg) { printf("I Love bRPC"); return nullptr; } int main(int argc, char **argv) { bthread_t th_1; bthread_start_background(&th_1, nullptr, PrintHellobRPC, nullptr); bthread_join(th_1, nullptr); return 0; }

6.2 从零到一的实操命令

假设你把上述 6 个文件（brpc_workspace.bzl+ 4 个.BUILD）与 WORKSPACE 配置就位、并写好自己的BUILD.bazel之后，构建命令为：

# 首次构建会自动拉取 protobuf/leveldb/zlib/gflags/brpc 等所有外部仓库 bazel build //:test # 运行产物 bazel run //:test

bazel build期间 Bazel 会依据brpc_workspace.bzl中的sha256校验下载的源码包，并从系统/usr链接 OpenSSL。

七、注意事项与适用前提

1. OpenSSL 依赖系统安装：由于openssl是new_local_repository(path = "/usr")，构建环境必须已安装 OpenSSL 头文件与库（Linux 通常为libssl-dev/openssl-devel）。若你的环境把 OpenSSL 装在非默认路径，需要修改brpc_workspace.bzl中的path参数。

2. 版本锁定：示例把 bRPC 固定为 1.3.0、protobuf 固定为 3.19.1、zlib 固定为 1.2.11。文档描述的是"作为第三方依赖接入"的标准姿势——在你自己项目里，bRPC 是作为apache_brpc外部仓库被拉取的，而不是直接编译当前仓库源码。

3. WORKSPACE 体系 vs Bzlmod：示例工程 example/build_with_bazel/WORKSPACE 使用经典workspace()体系；仓库根目录同时存在 WORKSPACE.bzlmod（当前为空文件）与根 WORKSPACE，说明 bRPC 仓库本身正处于从经典 WORKSPACE 向 Bzlmod 迁移的过渡阶段。如果你的项目启用了 Bzlmod，需要在MODULE.bazel中声明apache_brpc等依赖，并把brpc_workspace.bzl中的http_archive逻辑迁移为archive_override/local_path_override等模块机制——目前官方示例仍以经典 WORKSPACE 为准。

4. bRPC 仓库自身的 Bazel 构建：若你想直接在当前仓库源码上做 Bazel 构建与单测，仓库根目录的 BUILD.bazel 与 test/BUILD.bazel、bazel/config/BUILD.bazel 提供了完整的内部构建与测试目标（包括brpc_build_for_unittest、brpc_with_glog、brpc_with_boringssl等 config_setting），可参考 bazel/third_party/BUILD.bazel 下各依赖的 BUILD 定义。这与本文"第三方依赖接入"的用法互补：前者把 bRPC 当作品来构建，后者把 bRPC 当作库来消费。

八、小结

bRPC 的 Bazel 接入方案可以概括为"一份 Starlark 脚本 + 四个 BUILD 文件 + 一段 deps 清单"：brpc_workspace()负责把 protobuf、leveldb、zlib、gflags、OpenSSL 与 bRPC 本体注册进你的构建图，.BUILD文件为不提供 Bazel 支持的上游库补上构建描述，最终通过@apache_brpc//:brpc等 4 个公开目标链接进你的cc_binary/cc_library。这套方案完整、可复现，且被官方示例 example/build_with_bazel/ 直接验证，是 C++ 项目在 Bazel 体系下消费 bRPC 的首选路径。