docs: add Bazel build guide and bzlmod example

.github/workflows/ci-linux.yml

@@ -85,6 +85,49 @@ jobs:
               -DWITH_ASAN=ON -DCMAKE_POLICY_VERSION_MINIMUM=3.5 ..
         make -j ${{env.proc_num}} && make clean
 
+  compile-and-test-with-urma:
+    # WITH_URMA=ON is not covered by the jobs above: none of them set the flag,
+    # so src/brpc/urma/*.cpp and brpc_urma_unittest.cpp are never compiled.
+    # liburma is absent on the runner, so CMake falls back to the link-time
+    # mock (src/brpc/urma/mock_urma.cpp) and no URMA hardware is needed.
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ./.github/actions/install-essential-dependencies
+
+    # test/CMakeLists.txt does find_package(Gperftools) and links
+    # ${GPERFTOOLS_LIBRARIES} into every unittest target. The make-based
+    # unittest jobs never hit this, but the CMake generate step fails with
+    # NOTFOUND without it.
+    - name: install gperftools
+      run: sudo apt-get install -y libgoogle-perftools-dev
+
+    # DOWNLOAD_URMA_HEADERS fetches from atomgit.com, which is slow and often
+    # unreachable from CI. openEuler mirrors the same repo (identical tags and
+    # layout) on GitHub, so clone that and hand it to CMake via URMA_ROOT.
+    - name: fetch UMDK headers
+      run: |
+        git clone --depth 1 --branch v26.06.0_CAM \
+            https://github.com/openeuler-mirror/umdk.git $GITHUB_WORKSPACE/umdk
+        test -f $GITHUB_WORKSPACE/umdk/src/urma/lib/urma/core/include/urma_api.h
+
+    - name: gcc with URMA
+      env:
+        URMA_ROOT: ${{ github.workspace }}/umdk
+      run: |
+        export CC=gcc && export CXX=g++
+        mkdir urma_build && cd urma_build
+        cmake -DWITH_URMA=ON \
+              -DBUILD_UNIT_TESTS=ON -DBUILD_BRPC_TOOLS=OFF \
+              -DCMAKE_BUILD_TYPE=Debug -DCMAKE_POLICY_VERSION_MINIMUM=3.5 ..
+        # brpc_urma_unittest links brpc-shared-debug, built from
+        # SOURCES_DEBUG_LIB, which contains every urma_*.cpp plus
+        # mock_urma.cpp -- so this target compiles all the URMA code.
+        make -j ${{env.proc_num}} brpc_urma_unittest
+
+    - name: run brpc_urma_unittest
+      run: cd urma_build/test && ./brpc_urma_unittest
+
   gcc-compile-with-make-protobuf:
     runs-on: ubuntu-22.04
     steps:

CMakeLists.txt

@@ -31,6 +31,9 @@ option(WITH_URMA "With URMA (openEuler Unified Remote Memory Access)" OFF)
 option(DOWNLOAD_URMA_HEADERS
        "Download UMDK headers when WITH_URMA is enabled and headers are absent"
        ON)
+option(WITH_URMA_MOCK
+       "Explicitly allow linking brpc's URMA link-time mock when liburma is not found (WITH_URMA only). The mock cannot talk to real URMA hardware, so this must be opted into rather than silently substituted."
+       OFF)
 option(WITH_UBRING "With UB" OFF)
 option(WITH_DEBUG_BTHREAD_SCHE_SAFETY "With debugging bthread sche safety" OFF)
 option(WITH_DEBUG_LOCK "With debugging lock" OFF)
@@ -371,10 +374,17 @@ if(WITH_URMA)
     if(URMA_LIB)
         message(STATUS "Found URMA library: ${URMA_LIB}")
         set(URMA_USE_MOCK 0)
-    else()
+    elseif(WITH_URMA_MOCK)
         message(STATUS
-            "liburma not found; building with the URMA link-time mock")
+            "liburma not found; WITH_URMA_MOCK=ON, building with the URMA "
+            "link-time mock")
         set(URMA_USE_MOCK 1)
+    else()
+        message(FATAL_ERROR
+            "Fail to find liburma. Install liburma, set URMA_ROOT, or "
+            "explicitly opt into brpc's link-time mock with "
+            "-DWITH_URMA_MOCK=ON (the mock cannot talk to real URMA "
+            "hardware; only enable it for CI/tests without URMA hardware).")
     endif()
 endif()
 

MODULE.bazel

@@ -62,4 +62,12 @@ git_repository(
     build_file = '//bazel/third_party/umdk:umdk.BUILD',
     remote = 'https://atomgit.com/openeuler/umdk.git',
     commit = '564ee727a55523d4351a8fb3c94292b388ebb924',  # v26.06.0_CAM
+    # umdk ships its own src/urma/BUILD.bazel, which turns src/urma into a
+    # separate Bazel package and silently empties the glob() in umdk.BUILD
+    # (glob cannot cross package boundaries). Drop it so the headers under
+    # src/urma/lib/urma/**/include stay part of this repository's root
+    # package.
+    patch_cmds = [
+        'rm -f src/urma/BUILD.bazel',
+    ],
 )

WORKSPACE

@@ -284,6 +284,14 @@ git_repository(
     build_file = "//bazel/third_party/umdk:umdk.BUILD",
     remote = "https://atomgit.com/openeuler/umdk.git",
     commit = "564ee727a55523d4351a8fb3c94292b388ebb924",  # v26.06.0_CAM
+    # umdk ships its own src/urma/BUILD.bazel, which turns src/urma into a
+    # separate Bazel package and silently empties the glob() in umdk.BUILD
+    # (glob cannot cross package boundaries). Drop it so the headers under
+    # src/urma/lib/urma/**/include stay part of this repository's root
+    # package.
+    patch_cmds = [
+        "rm -f src/urma/BUILD.bazel",
+    ],
 )
 
 # Header-only JSON library used by iobuf_unittest's IOBuf<->std::iostream

bazel/third_party/umdk/BUILD.bazel

@@ -0,0 +1,17 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# Thie empty BUILD.bazel file is required to make Bazel treat
+# this directory as a package.

config_brpc.sh

@@ -54,11 +54,12 @@ else
     LDD=ldd
 fi
 
-TEMP=`getopt -o v: --long headers:,libs:,cc:,cxx:,with-glog,with-thrift,with-rdma,with-urma,with-mesalink,with-bthread-tracer,with-debug-bthread-sche-safety,with-debug-lock,with-asan,with-riscv-zvbc,with-riscv-zbc,with-cpu-frequency,nodebugsymbols,werror -n 'config_brpc' -- "$@"`
+TEMP=`getopt -o v: --long headers:,libs:,cc:,cxx:,with-glog,with-thrift,with-rdma,with-urma,with-urma-mock,with-mesalink,with-bthread-tracer,with-debug-bthread-sche-safety,with-debug-lock,with-asan,with-riscv-zvbc,with-riscv-zbc,with-cpu-frequency,nodebugsymbols,werror -n 'config_brpc' -- "$@"`
 WITH_GLOG=0
 WITH_THRIFT=0
 WITH_RDMA=0
 WITH_URMA=0
+WITH_URMA_MOCK=0
 WITH_MESALINK=0
 WITH_BTHREAD_TRACER=0
 WITH_ASAN=0
@@ -92,6 +93,7 @@ while true; do
         --with-thrift) WITH_THRIFT=1; shift 1 ;;
         --with-rdma) WITH_RDMA=1; shift 1 ;;
         --with-urma) WITH_URMA=1; shift 1 ;;
+        --with-urma-mock) WITH_URMA_MOCK=1; shift 1 ;;
         --with-mesalink) WITH_MESALINK=1; shift 1 ;;
         --with-bthread-tracer) WITH_BTHREAD_TRACER=1; shift 1 ;;
         --with-debug-bthread-sche-safety ) BRPC_DEBUG_BTHREAD_SCHE_SAFETY=1; shift 1 ;;
@@ -554,9 +556,12 @@ if [ $WITH_URMA != 0 ]; then
         append_to_output_libs "$URMA_LIB"
         append_to_output "DYNAMIC_LINKINGS+=-lurma"
         append_to_output "URMA_USE_MOCK=0"
-    else
+    elif [ $WITH_URMA_MOCK != 0 ]; then
         append_to_output "URMA_USE_MOCK=1"
-        print_info "liburma not found; using URMA link-time mock"
+        print_info "liburma not found; --with-urma-mock given, using URMA link-time mock"
+    else
+        >&2 $ECHO "Fail to find liburma. Install liburma, or explicitly opt into brpc's link-time mock with --with-urma-mock (the mock cannot talk to real URMA hardware; only use it for CI/tests without URMA hardware)."
+        exit 1
     fi
 fi
 

docs/cn/bazel_support.md

@@ -1,20 +1,99 @@
-## 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 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/urma.md

@@ -20,7 +20,7 @@ WR。完成事件既可由 JFC 忙轮询获取，也可通过 JFCE 事件 fd 获
 ### CMake 编译
 
 ```bash
-# 带 URMA 支持编译 brpc
+# 带 URMA 支持编译 brpc（需要 liburma；无硬件/CI 场景见下方 mock 说明）
 cmake -B build -DWITH_URMA=ON
 make -C build -j$(nproc)
 
@@ -30,11 +30,37 @@ cmake -B build
 make -C build -j$(nproc)
 ```
 
+未安装 `liburma` 时（例如 CI 环境），需显式开启链接期 mock，而不是依赖
+隐式回退：
+
+```bash
+cmake -B build -DWITH_URMA=ON -DWITH_URMA_MOCK=ON
+make -C build -j$(nproc)
+```
+
 `WITH_URMA=ON` 使用上游 UMDK 头文件进行编译。CMake 优先使用系统安装的
 SDK；找不到头文件时，会参照 Mooncake 的 mock 构建方式下载固定版本的
 UMDK，可通过 `DOWNLOAD_URMA_HEADERS=OFF` 禁止下载。找到 `liburma` 时使用
-真实硬件数据通路，否则链接 brpc 的 mock，使 URMA 代码和测试仍可在无硬件
-环境编译。
+真实硬件数据通路；否则默认直接报错终止构建，避免静默回退到 mock 而产出
+一个看似支持 URMA、实际无法访问真实硬件的产物。需要在无硬件环境（例如
+CI）编译和测试 URMA 代码时，显式传入 `-DWITH_URMA_MOCK=ON`
+（Make 对应 `config_brpc.sh --with-urma-mock`）以主动选择链接 brpc 的
+mock。
+
+### Bazel 编译
+
+```bash
+# 带 URMA 支持编译 brpc
+bazel build --define=BRPC_WITH_URMA=true //:brpc
+```
+
+Bazel 下的 URMA 头文件来自 `WORKSPACE` / `MODULE.bazel` 中固定 commit 的
+`umdk` `git_repository`，没有 CMake `DOWNLOAD_URMA_HEADERS` 那样的开关：
+既不能改用系统已安装的 SDK 头文件，也无法禁止下载。此外 Bazel 构建目前
+未提供检测/链接真实 `liburma` 的逻辑，`src/brpc/urma/mock_urma.cpp` 会
+无条件编入，因此 Bazel 构建的 URMA 始终使用 mock 数据通路；如需链接真实
+硬件，请使用 CMake 或 Make 构建。`urma_performance` 示例目前也只有
+CMake/Make 构建脚本，尚无对应的 Bazel target。
 
 ## 使用