docs: add Bazel build guide and bzlmod example

docs/cn/bazel_support.md

@@ -1,20 +1,100 @@
-## 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` 中有一个包含 server 和 client 的可运行示例：
+
+```shell
+$ cd example/build_with_bazel_module
+$ bazel build //:echo_c++_server //:echo_c++_client
+$ bazel run //:echo_c++_server &
+$ bazel run //:echo_c++_client
+```
+
+先在你的 `.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
 ```
-内容添加到你的WORKSPACE中.
 
-3. 链接请使用
-  ```c++
-  ...
-  deps = [
+然后在 `MODULE.bazel` 中添加 bRPC，并指向本地 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")
+
+local_path_override(
+    module_name = "brpc",
+    path = "/path/to/brpc",
+)
+
+single_version_override(
+    module_name = "leveldb",
+    registry = "https://raw.githubusercontent.com/secretflow/bazel-registry/main",
+)
+
+single_version_override(
+    module_name = "openssl",
+    version = "3.3.2.bcr.1",
+    registry = "https://raw.githubusercontent.com/secretflow/bazel-registry/main",
+)
+```
+
+`bazel_dep` 用来声明模块名和仓库映射，`local_path_override` 让 Bazel 使用本地源码，而不是从 registry 解析 bRPC。
+
+bzlmod 不会传递依赖模块中的 override。把 bRPC 当依赖时，需要在自己项目的根
+`MODULE.bazel` 里重复上面的 `single_version_override`；它们在 aarch64 上是必需的，否则 leveldb toolchain 解析会失败。
+
+之后在目标中链接 bRPC：
+
+```python
+cc_binary(
+    name = "server",
+    srcs = ["server.cpp"],
+    deps = [
+        "@apache_brpc//:brpc",
+    ],
+)
+```
+
+如果服务使用 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",
-  ]
-  ...
-  ```
+]
+```

docs/cn/getting_started.md

@@ -121,6 +121,19 @@ $ ./echo_client
 $ mkdir build && cd build && cmake -DBUILD_UNIT_TESTS=ON .. && make && make test
 ```
 
+### 使用 Bazel 编译 brpc
+
+bRPC 也支持 Bazel 构建。`example/build_with_bazel_module` 下的 bzlmod 示例会基于本地
+bRPC 源码构建 server 和 client：
+
+```shell
+$ cd example/build_with_bazel_module
+$ bazel build //:echo_c++_server //:echo_c++_client
+```
+
+如果要把 bRPC 作为 Bazel 依赖使用，包括需要配置的 registry 和 `MODULE.bazel`，
+请参考 [Bazel 支持](bazel_support.md)。
+
 ## Fedora/CentOS
 
 ### 依赖准备

docs/en/bazel_support.md

@@ -1,20 +1,105 @@
 ## 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 a local bRPC checkout from a Bazel project is
+to use bzlmod (`MODULE.bazel`). See `example/build_with_bazel_module` for a
+runnable example with both a server and a client:
+
+```shell
+$ cd example/build_with_bazel_module
+$ bazel build //:echo_c++_server //:echo_c++_client
+$ bazel run //:echo_c++_server &
+$ bazel run //:echo_c++_client
+```
+
+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
 ```
-to your WORKSPACE
 
-3. link apache_brpc like:
-  ```c++
-  ...
-  deps = [
+Add bRPC to your `MODULE.bazel`, and point it to your local bRPC checkout:
+
+```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")
+
+local_path_override(
+    module_name = "brpc",
+    path = "/path/to/brpc",
+)
+
+single_version_override(
+    module_name = "leveldb",
+    registry = "https://raw.githubusercontent.com/secretflow/bazel-registry/main",
+)
+
+single_version_override(
+    module_name = "openssl",
+    version = "3.3.2.bcr.1",
+    registry = "https://raw.githubusercontent.com/secretflow/bazel-registry/main",
+)
+```
+
+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.
+
+bzlmod does not propagate overrides from dependency modules. When using bRPC as
+a dependency, repeat the `single_version_override` entries above in your root
+`MODULE.bazel`; they are required on aarch64 because leveldb toolchain
+resolution otherwise fails.
+
+Then link bRPC from your targets:
+
+```python
+cc_binary(
+    name = "server",
+    srcs = ["server.cpp"],
+    deps = [
+        "@apache_brpc//:brpc",
+    ],
+)
+```
+
+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",
-  ]
-  ...
-  ```
+]
+```

docs/en/getting_started.md

@@ -108,6 +108,20 @@ 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 also supports Bazel builds. The bzlmod example under
+`example/build_with_bazel_module` builds a server and a client against the local
+bRPC checkout:
+
+```shell
+$ cd example/build_with_bazel_module
+$ bazel build //:echo_c++_server //:echo_c++_client
+```
+
+For using bRPC as a Bazel dependency, including the required registries and
+`MODULE.bazel` setup, see [Bazel support](bazel_support.md).
+
 ### Compile brpc with vcpkg
 
 [vcpkg](https://github.com/microsoft/vcpkg) is a package manager that supports all platforms,

example/build_with_bazel_module/BUILD.bazel

@@ -30,3 +30,14 @@ cc_binary(
         "@apache_brpc//:brpc",
     ],
 )
+
+cc_binary(
+    name = "echo_c++_client",
+    srcs = [
+        "client.cpp",
+    ],
+    deps = [
+        ":cc_echo_c++_proto",
+        "@apache_brpc//:brpc",
+    ],
+)

example/build_with_bazel_module/MODULE.bazel

@@ -27,4 +27,25 @@ bazel_dep(name = 'brpc', version = '1.17.0', repo_name = 'apache_brpc')
 local_path_override(
     module_name = "brpc",
     path = "../..",
-)
+)
+
+# Overrides only take effect in the root module. When this example is built,
+# `brpc-example` is the root module and `brpc` is just a dependency, so the
+# same two overrides in brpc's root MODULE.bazel are ignored and have to be
+# repeated here. Keep them in sync with the root MODULE.bazel.
+#
+# leveldb is published only in the secretflow registry — not in BCR, nor in
+# the babylon / apache-brpc registries added by .bazelrc. And brpc declares
+# `openssl 3.3.2`, which exists there only as `3.3.2.bcr.1`, hence the
+# version rewrite.
+
+single_version_override(
+    module_name = "leveldb",
+    registry = "https://raw.githubusercontent.com/secretflow/bazel-registry/main",
+)
+
+single_version_override(
+    module_name = "openssl",
+    version = "3.3.2.bcr.1",
+    registry = "https://raw.githubusercontent.com/secretflow/bazel-registry/main",
+)