From 0eef7f31a2bced04be0468fa1967f0342bb48c9f Mon Sep 17 00:00:00 2001
From: Winchell <cw20050111@gmail.com>
Date: Thu, 13 Aug 2026 10:18:09 +0800
Subject: [PATCH 1/4] docs: add Bazel build instructions to getting_started

Official docs previously only covered config_brpc.sh and CMake, leaving
Bazel builders without guidance despite the repo already having full
Bazel/bzlmod support. Add a "Compile brpc with bazel" section (build,
run examples, run tests, and link to bazel_support.md for consuming
brpc as a dependency) to both docs/en and docs/cn getting_started.md,
with cross-reference links from the other OS sections matching the
existing cmake pattern.

Fixes apache/brpc#2991

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016u8i1npn8aMgNr5WiT97rt
---
 docs/cn/getting_started.md | 41 ++++++++++++++++++++++++++++++++++++++
 docs/en/getting_started.md | 41 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 82 insertions(+)

diff --git a/docs/cn/getting_started.md b/docs/cn/getting_started.md
index 334906a125..91363a9f2c 100644
--- a/docs/cn/getting_started.md
+++ b/docs/cn/getting_started.md
@@ -121,6 +121,41 @@ $ ./echo_client
 $ mkdir build && cd build && cmake -DBUILD_UNIT_TESTS=ON .. && make && make test
 ```
 
+### 使用bazel编译brpc
+
+brpc也可以直接使用[Bazel](https://bazel.build)编译，不需要先执行`config_brpc.sh`。`.bazelversion`中指定的版本已验证可用；使用[bzlmod](https://bazel.build/external/overview#bzlmod)（`MODULE.bazel`）的较新版本Bazel也可以使用。Bazel会自行解析protobuf/gflags/leveldb/openssl等依赖，不需要手动安装。
+
+git克隆brpc，进入到项目目录，然后运行：
+```shell
+$ bazel build -- //:brpc
+```
+
+如果需要一并编译样例：
+```shell
+$ bazel build -- //:brpc //example/...
+```
+
+修改编译器为clang，添加选项`--action_env=CC=clang --action_env=CXX=clang++`。
+
+可选功能通过`--define`开启，例如`--define with_glog=true`、`--define with_thrift=true`、`--define with_bthread_tracer=true`、`--define with_debug_lock=true`。完整的`--define`选项列表见`bazel/config/BUILD.bazel`。
+
+**用bazel运行样例**
+
+```shell
+$ bazel run //example:echo_c++_server &
+$ bazel run //example:echo_c++_client
+```
+
+**用bazel运行测试**
+
+```shell
+$ bazel test //test/...
+```
+
+**在自己的项目中把brpc作为bazel依赖**
+
+参考[Bazel Support](bazel_support.md)了解如何在其他Bazel项目中依赖brpc，`example/build_with_bazel_module`中有一个可运行的bzlmod样例。
+
 ## Fedora/CentOS
 
 ### 依赖准备
@@ -182,6 +217,9 @@ $ sh run_tests.sh
 ### 使用cmake编译brpc
 参考[这里](#使用cmake编译brpc)
 
+### 使用bazel编译brpc
+参考[这里](#使用bazel编译brpc)
+
 ### 使用vcpkg编译brpc
 
 [vcpkg](https://github.com/microsoft/vcpkg) 是一个全平台支持的包管理器，你可以使用以下步骤vcpkg轻松编译brpc:
@@ -309,6 +347,9 @@ $ sh run_tests.sh
 ### 使用cmake编译brpc
 参考[这里](#使用cmake编译brpc)
 
+### 使用bazel编译brpc
+参考[这里](#使用bazel编译brpc)
+
 ## Docker
 使用docker 编译brpc：
 
diff --git a/docs/en/getting_started.md b/docs/en/getting_started.md
index 32d4733766..ea27dc3bf5 100644
--- a/docs/en/getting_started.md
+++ b/docs/en/getting_started.md
@@ -108,6 +108,41 @@ Examples link brpc statically, if you need to link the shared version, remove `C
 $ mkdir build && cd build && cmake -DBUILD_UNIT_TESTS=ON .. && make && make test
 ```
 
+### Compile brpc with bazel
+
+brpc can also be built directly with [Bazel](https://bazel.build) without running `config_brpc.sh` first. The version pinned in `.bazelversion` is known to work; newer Bazel versions using [bzlmod](https://bazel.build/external/overview#bzlmod) (`MODULE.bazel`) also work. Bazel resolves protobuf/gflags/leveldb/openssl/... itself, so you don't need to install those deps manually.
+
+git clone brpc, cd into the repo and run:
+```shell
+$ bazel build -- //:brpc
+```
+
+To also build the examples:
+```shell
+$ bazel build -- //:brpc //example/...
+```
+
+To change compiler to clang, add `--action_env=CC=clang --action_env=CXX=clang++`.
+
+Optional features are toggled with `--define`, e.g. `--define with_glog=true`, `--define with_thrift=true`, `--define with_bthread_tracer=true`, `--define with_debug_lock=true`. See `bazel/config/BUILD.bazel` for the full list of `--define` switches.
+
+**Run example with bazel**
+
+```shell
+$ bazel run //example:echo_c++_server &
+$ bazel run //example:echo_c++_client
+```
+
+**Run tests with bazel**
+
+```shell
+$ bazel test //test/...
+```
+
+**Use brpc as a bazel dependency in your own project**
+
+See [Bazel Support](bazel_support.md) for how to depend on brpc from another Bazel project, and `example/build_with_bazel_module` for a runnable bzlmod example.
+
 ### Compile brpc with vcpkg
 
 [vcpkg](https://github.com/microsoft/vcpkg) is a package manager that supports all platforms,
@@ -186,6 +221,9 @@ $ sh run_tests.sh
 ### Compile brpc with cmake
 Same with [here](#compile-brpc-with-cmake)
 
+### Compile brpc with bazel
+Same with [here](#compile-brpc-with-bazel)
+
 ## Linux with self-built deps
 
 ### Prepare deps
@@ -318,6 +356,9 @@ $ sh run_tests.sh
 ### Compile brpc with cmake
 Same with [here](#compile-brpc-with-cmake)
 
+### Compile brpc with bazel
+Same with [here](#compile-brpc-with-bazel)
+
 # Supported deps
 
 ## GCC: 5.0-11.2

From 477f9bd2c3bcc025d86c3c87fcb81a10afc7a96c Mon Sep 17 00:00:00 2001
From: Winchell <cw20050111@gmail.com>
Date: Thu, 13 Aug 2026 11:20:39 +0800
Subject: [PATCH 2/4] docs: update Bazel dependency instructions

---
 docs/cn/bazel_support.md | 89 +++++++++++++++++++++++++++++++++-------
 docs/en/bazel_support.md | 87 +++++++++++++++++++++++++++++++++------
 2 files changed, 149 insertions(+), 27 deletions(-)

diff --git a/docs/cn/bazel_support.md b/docs/cn/bazel_support.md
index 0ff86119cb..82ccfaf651 100644
--- a/docs/cn/bazel_support.md
+++ b/docs/cn/bazel_support.md
@@ -1,20 +1,81 @@
-## bRPC 作为Bazel第三方依赖
-1. bRPC 依赖于一些开源库, 但这些库并没有提供bazel支持, 所以需要你手动将一部分依赖加入到你的构建项目中.
-2. 将 /example/build_with_bazel/*.BUILD 和 brpc_workspace.bzl 该文件移动到你的项目根目录下, 将
-```c++
-    load("@//:brpc_workspace.bzl", "brpc_workspace")
-    brpc_workspace();
+## bRPC 作为 Bazel 第三方依赖
+
+推荐在 Bazel 项目中使用 bzlmod（`MODULE.bazel`）依赖 bRPC。
+`example/build_with_bazel_module` 中有一个可运行的示例。
+
+先在你的 `.bazelrc` 中添加 bRPC 使用的 registry：
+
+```shell
+common --registry=https://bcr.bazel.build
+common --registry=https://baidu.github.io/babylon/registry
+common --registry=https://raw.githubusercontent.com/apache/brpc/master/registry
+```
+
+然后在 `MODULE.bazel` 中添加 bRPC：
+
+```python
+module(
+    name = "my_brpc_app",
+    version = "0.1.0",
+)
+
+bazel_dep(name = "protobuf", version = "27.3", repo_name = "com_google_protobuf")
+bazel_dep(name = "brpc", version = "1.17.0", repo_name = "apache_brpc")
+```
+
+如果需要依赖本地的 bRPC 源码，可以添加本地覆盖：
+
+```python
+local_path_override(
+    module_name = "brpc",
+    path = "/path/to/brpc",
+)
+```
+
+之后在目标中链接 bRPC：
+
+```python
+cc_binary(
+    name = "server",
+    srcs = ["server.cpp"],
+    deps = [
+        "@apache_brpc//:brpc",
+    ],
+)
 ```
-内容添加到你的WORKSPACE中.
 
-3. 链接请使用
-  ```c++
-  ...
-  deps = [
+如果服务使用 protobuf，可以从 bRPC 加载 `brpc_proto_library`：
+
+```python
+load("@apache_brpc//bazel/tools:brpc_proto_library.bzl", "brpc_proto_library")
+
+brpc_proto_library(
+    name = "cc_echo_proto",
+    srcs = ["echo.proto"],
+)
+```
+
+## 旧版 WORKSPACE 用法
+
+仍在使用 `WORKSPACE` 的项目可以参考 `example/build_with_bazel`。
+
+1. 将 `example/build_with_bazel/*.BUILD` 和
+   `example/build_with_bazel/brpc_workspace.bzl` 移动到你的项目根目录下。
+2. 在 `WORKSPACE` 中添加：
+
+```python
+load("@//:brpc_workspace.bzl", "brpc_workspace")
+
+brpc_workspace()
+```
+
+3. 在目标中链接 `apache_brpc`：
+
+```python
+deps = [
     "@apache_brpc//:bthread",
     "@apache_brpc//:brpc",
     "@apache_brpc//:butil",
     "@apache_brpc//:bvar",
-  ]
-  ...
-  ```
+]
+```
diff --git a/docs/en/bazel_support.md b/docs/en/bazel_support.md
index 607cf9c462..fdde51cb32 100644
--- a/docs/en/bazel_support.md
+++ b/docs/en/bazel_support.md
@@ -1,20 +1,81 @@
 ## bRPC as a Bazel third-party dependency
-1. bRPC relies on a number of open source libraries that do not provide bazel support, so you will need to manually add some of these dependencies to your build project.
-2. Move the BUILD file /example/build_with_bazel/*.BUILD and brpc_workspace.bzl to the root of your project, and add the contents of 
-```c++
-    load("@//:brpc_workspace.bzl", "brpc_workspace")
-    brpc_workspace();
+
+The recommended way to depend on bRPC from a Bazel project is to use bzlmod
+(`MODULE.bazel`). See `example/build_with_bazel_module` for a runnable example.
+
+Add the registries used by bRPC to your `.bazelrc`:
+
+```shell
+common --registry=https://bcr.bazel.build
+common --registry=https://baidu.github.io/babylon/registry
+common --registry=https://raw.githubusercontent.com/apache/brpc/master/registry
+```
+
+Add bRPC to your `MODULE.bazel`:
+
+```python
+module(
+    name = "my_brpc_app",
+    version = "0.1.0",
+)
+
+bazel_dep(name = "protobuf", version = "27.3", repo_name = "com_google_protobuf")
+bazel_dep(name = "brpc", version = "1.17.0", repo_name = "apache_brpc")
+```
+
+When developing against a local bRPC checkout, add a local override:
+
+```python
+local_path_override(
+    module_name = "brpc",
+    path = "/path/to/brpc",
+)
+```
+
+Then link bRPC from your targets:
+
+```python
+cc_binary(
+    name = "server",
+    srcs = ["server.cpp"],
+    deps = [
+        "@apache_brpc//:brpc",
+    ],
+)
 ```
-to your WORKSPACE
 
-3. link apache_brpc like:
-  ```c++
-  ...
-  deps = [
+If your service uses protobuf, load `brpc_proto_library` from bRPC:
+
+```python
+load("@apache_brpc//bazel/tools:brpc_proto_library.bzl", "brpc_proto_library")
+
+brpc_proto_library(
+    name = "cc_echo_proto",
+    srcs = ["echo.proto"],
+)
+```
+
+## Legacy WORKSPACE usage
+
+For projects that still use `WORKSPACE`, see `example/build_with_bazel`.
+
+1. Move `example/build_with_bazel/*.BUILD` and
+   `example/build_with_bazel/brpc_workspace.bzl` to the root of your project.
+2. Add the following to your `WORKSPACE`:
+
+```python
+load("@//:brpc_workspace.bzl", "brpc_workspace")
+
+brpc_workspace()
+```
+
+3. Link `apache_brpc` from your targets:
+
+```python
+deps = [
     "@apache_brpc//:bthread",
     "@apache_brpc//:brpc",
     "@apache_brpc//:butil",
     "@apache_brpc//:bvar",
-  ]
-  ...
-  ```
+]
+```

From fd5868ddc6edbba1e0c35f28831edbb4d4b4f123 Mon Sep 17 00:00:00 2001
From: Winchell <cw20050111@gmail.com>
Date: Thu, 13 Aug 2026 11:31:59 +0800
Subject: [PATCH 3/4] docs: clarify Bazel build prerequisites

---
 docs/cn/getting_started.md | 10 ++++++++--
 docs/en/getting_started.md | 10 ++++++++--
 2 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/docs/cn/getting_started.md b/docs/cn/getting_started.md
index 91363a9f2c..009693f468 100644
--- a/docs/cn/getting_started.md
+++ b/docs/cn/getting_started.md
@@ -123,9 +123,15 @@ $ mkdir build && cd build && cmake -DBUILD_UNIT_TESTS=ON .. && make && make test
 
 ### 使用bazel编译brpc
 
-brpc也可以直接使用[Bazel](https://bazel.build)编译，不需要先执行`config_brpc.sh`。`.bazelversion`中指定的版本已验证可用；使用[bzlmod](https://bazel.build/external/overview#bzlmod)（`MODULE.bazel`）的较新版本Bazel也可以使用。Bazel会自行解析protobuf/gflags/leveldb/openssl等依赖，不需要手动安装。
+brpc也可以直接使用[Bazel](https://bazel.build)编译，不需要先执行`config_brpc.sh`。推荐使用Bazelisk或`.bazelversion`中固定的Bazel版本（`7.2.1`），这是当前仓库默认验证的版本。bzlmod（`MODULE.bazel`）构建会拉取其中声明的第三方库，例如protobuf、gflags、leveldb、openssl，但仍需要可用的C++工具链和平台SDK。Bazel构建已在Linux和macOS CI流程中覆盖。
 
-git克隆brpc，进入到项目目录，然后运行：
+克隆brpc并进入项目目录：
+```shell
+$ git clone https://github.com/apache/brpc.git
+$ cd brpc
+```
+
+然后编译brpc库：
 ```shell
 $ bazel build -- //:brpc
 ```
diff --git a/docs/en/getting_started.md b/docs/en/getting_started.md
index ea27dc3bf5..5076f614ea 100644
--- a/docs/en/getting_started.md
+++ b/docs/en/getting_started.md
@@ -110,9 +110,15 @@ $ mkdir build && cd build && cmake -DBUILD_UNIT_TESTS=ON .. && make && make test
 
 ### Compile brpc with bazel
 
-brpc can also be built directly with [Bazel](https://bazel.build) without running `config_brpc.sh` first. The version pinned in `.bazelversion` is known to work; newer Bazel versions using [bzlmod](https://bazel.build/external/overview#bzlmod) (`MODULE.bazel`) also work. Bazel resolves protobuf/gflags/leveldb/openssl/... itself, so you don't need to install those deps manually.
+brpc can also be built directly with [Bazel](https://bazel.build) without running `config_brpc.sh` first. Use Bazelisk or the Bazel version pinned in `.bazelversion` (`7.2.1`), which is the default version validated by this repository. The bzlmod (`MODULE.bazel`) build fetches the third-party libraries declared there, such as protobuf, gflags, leveldb, and openssl, but you still need a working C++ toolchain and platform SDK. Bazel builds are covered by the Linux and macOS CI workflows.
 
-git clone brpc, cd into the repo and run:
+Clone brpc, cd into the repo and run:
+```shell
+$ git clone https://github.com/apache/brpc.git
+$ cd brpc
+```
+
+Then build the brpc library:
 ```shell
 $ bazel build -- //:brpc
 ```

From 06545afb3131fcbc35da3f0c4d56c1353ff96ccd Mon Sep 17 00:00:00 2001
From: Winchell <cw20050111@gmail.com>
Date: Thu, 13 Aug 2026 11:38:23 +0800
Subject: [PATCH 4/4] docs: refine Bazel dependency guidance

---
 docs/cn/bazel_support.md   | 10 ++++------
 docs/cn/getting_started.md |  2 +-
 docs/en/bazel_support.md   | 15 ++++++++-------
 docs/en/getting_started.md |  2 +-
 4 files changed, 14 insertions(+), 15 deletions(-)

diff --git a/docs/cn/bazel_support.md b/docs/cn/bazel_support.md
index 82ccfaf651..3092950c0a 100644
--- a/docs/cn/bazel_support.md
+++ b/docs/cn/bazel_support.md
@@ -1,6 +1,6 @@
 ## bRPC 作为 Bazel 第三方依赖
 
-推荐在 Bazel 项目中使用 bzlmod（`MODULE.bazel`）依赖 bRPC。
+推荐在 Bazel 项目中使用 bzlmod（`MODULE.bazel`）依赖本地 bRPC 源码。
 `example/build_with_bazel_module` 中有一个可运行的示例。
 
 先在你的 `.bazelrc` 中添加 bRPC 使用的 registry：
@@ -11,7 +11,7 @@ common --registry=https://baidu.github.io/babylon/registry
 common --registry=https://raw.githubusercontent.com/apache/brpc/master/registry
 ```
 
-然后在 `MODULE.bazel` 中添加 bRPC：
+然后在 `MODULE.bazel` 中添加 bRPC，并指向本地 bRPC 源码：
 
 ```python
 module(
@@ -21,17 +21,15 @@ module(
 
 bazel_dep(name = "protobuf", version = "27.3", repo_name = "com_google_protobuf")
 bazel_dep(name = "brpc", version = "1.17.0", repo_name = "apache_brpc")
-```
-
-如果需要依赖本地的 bRPC 源码，可以添加本地覆盖：
 
-```python
 local_path_override(
     module_name = "brpc",
     path = "/path/to/brpc",
 )
 ```
 
+`bazel_dep` 用来声明模块名和仓库映射，`local_path_override` 让 Bazel 使用本地源码，而不是从 registry 解析 bRPC。
+
 之后在目标中链接 bRPC：
 
 ```python
diff --git a/docs/cn/getting_started.md b/docs/cn/getting_started.md
index 009693f468..d1731cc116 100644
--- a/docs/cn/getting_started.md
+++ b/docs/cn/getting_started.md
@@ -123,7 +123,7 @@ $ mkdir build && cd build && cmake -DBUILD_UNIT_TESTS=ON .. && make && make test
 
 ### 使用bazel编译brpc
 
-brpc也可以直接使用[Bazel](https://bazel.build)编译，不需要先执行`config_brpc.sh`。推荐使用Bazelisk或`.bazelversion`中固定的Bazel版本（`7.2.1`），这是当前仓库默认验证的版本。bzlmod（`MODULE.bazel`）构建会拉取其中声明的第三方库，例如protobuf、gflags、leveldb、openssl，但仍需要可用的C++工具链和平台SDK。Bazel构建已在Linux和macOS CI流程中覆盖。
+brpc也可以直接使用[Bazel](https://bazel.build)编译，不需要先执行`config_brpc.sh`。推荐使用Bazelisk或`.bazelversion`中固定的Bazel版本（`7.2.1`），这是当前仓库默认验证的版本。bzlmod（`MODULE.bazel`）构建会拉取其中声明的第三方库，例如protobuf、gflags、leveldb、openssl，但仍需要可用的C++工具链和平台SDK。Bazel构建已在Linux CI中覆盖，brpc库目标也在macOS CI中覆盖。
 
 克隆brpc并进入项目目录：
 ```shell
diff --git a/docs/en/bazel_support.md b/docs/en/bazel_support.md
index fdde51cb32..23357e16bb 100644
--- a/docs/en/bazel_support.md
+++ b/docs/en/bazel_support.md
@@ -1,7 +1,8 @@
 ## bRPC as a Bazel third-party dependency
 
-The recommended way to depend on bRPC from a Bazel project is to use bzlmod
-(`MODULE.bazel`). See `example/build_with_bazel_module` for a runnable example.
+The recommended way to depend on a local bRPC checkout from a Bazel project is
+to use bzlmod (`MODULE.bazel`). See `example/build_with_bazel_module` for a
+runnable example.
 
 Add the registries used by bRPC to your `.bazelrc`:
 
@@ -11,7 +12,7 @@ common --registry=https://baidu.github.io/babylon/registry
 common --registry=https://raw.githubusercontent.com/apache/brpc/master/registry
 ```
 
-Add bRPC to your `MODULE.bazel`:
+Add bRPC to your `MODULE.bazel`, and point it to your local bRPC checkout:
 
 ```python
 module(
@@ -21,17 +22,17 @@ module(
 
 bazel_dep(name = "protobuf", version = "27.3", repo_name = "com_google_protobuf")
 bazel_dep(name = "brpc", version = "1.17.0", repo_name = "apache_brpc")
-```
-
-When developing against a local bRPC checkout, add a local override:
 
-```python
 local_path_override(
     module_name = "brpc",
     path = "/path/to/brpc",
 )
 ```
 
+The `bazel_dep` keeps the module name and repository mapping, while
+`local_path_override` makes Bazel use the local checkout instead of resolving
+bRPC from a registry.
+
 Then link bRPC from your targets:
 
 ```python
diff --git a/docs/en/getting_started.md b/docs/en/getting_started.md
index 5076f614ea..d9444df675 100644
--- a/docs/en/getting_started.md
+++ b/docs/en/getting_started.md
@@ -110,7 +110,7 @@ $ mkdir build && cd build && cmake -DBUILD_UNIT_TESTS=ON .. && make && make test
 
 ### Compile brpc with bazel
 
-brpc can also be built directly with [Bazel](https://bazel.build) without running `config_brpc.sh` first. Use Bazelisk or the Bazel version pinned in `.bazelversion` (`7.2.1`), which is the default version validated by this repository. The bzlmod (`MODULE.bazel`) build fetches the third-party libraries declared there, such as protobuf, gflags, leveldb, and openssl, but you still need a working C++ toolchain and platform SDK. Bazel builds are covered by the Linux and macOS CI workflows.
+brpc can also be built directly with [Bazel](https://bazel.build) without running `config_brpc.sh` first. Use Bazelisk or the Bazel version pinned in `.bazelversion` (`7.2.1`), which is the default version validated by this repository. The bzlmod (`MODULE.bazel`) build fetches the third-party libraries declared there, such as protobuf, gflags, leveldb, and openssl, but you still need a working C++ toolchain and platform SDK. Bazel builds are covered by Linux CI; the brpc library target is also covered by macOS CI.
 
 Clone brpc, cd into the repo and run:
 ```shell