bazel

Bazel

用途

指导 Agent 为 C/C++ 项目使用 Bazel：编写 BUILD 文件、使用 cc_library/cc_binary 规则、注册工具链、配置远程执行、查询依赖关系图、使用 Bzlmod 管理依赖，以及调试沙箱问题。

触发条件

• “如何为 C++ 库编写 Bazel BUILD 文件？”
• “如何使用 Bzlmod 添加外部依赖？”
• “如何调试 Bazel 沙箱错误？”
• “如何查询 Bazel 依赖关系图？”
• “如何配置 Bazel 远程执行？”
• “如何注册自定义 C++ 工具链？”

工作流

1. 工作区结构

my-project/
├── MODULE.bazel         # Bzlmod dependency file (Bazel ≥6)
├── WORKSPACE            # legacy (still needed for some features)
├── BUILD                # root build file
├── src/
│   ├── BUILD
│   └── main.cc
└── lib/
    ├── BUILD
    ├── mylib.cc
    └── mylib.h

2. 基本 BUILD 文件 — cc_library / cc_binary

# lib/BUILD
cc_library(
    name = "mylib",
    srcs = ["mylib.cc"],
    hdrs = ["mylib.h"],
    copts = ["-Wall", "-Wextra", "-std=c++17"],
    visibility = ["//visibility:public"],
    deps = [
        "@com_google_absl//absl/strings",     # external dep
        "//util:helpers",                      # internal dep
    ],
)

cc_test(
    name = "mylib_test",
    srcs = ["mylib_test.cc"],
    deps = [
        ":mylib",
        "@com_google_googletest//:gtest_main",
    ],
)

# src/BUILD
cc_binary(
    name = "main",
    srcs = ["main.cc"],
    deps = ["//lib:mylib"],
    linkopts = ["-lpthread"],
)

# Build
bazel build //src:main
bazel build //...           # build everything

# Test
bazel test //lib:mylib_test
bazel test //...            # run all tests

# Run
bazel run //src:main -- arg1 arg2

# Output path
bazel-bin/src/main

3. Bzlmod — 现代依赖管理

# MODULE.bazel
module(
    name = "my_project",
    version = "1.0",
)

bazel_dep(name = "abseil-cpp", version = "20240116.2")
bazel_dep(name = "googletest", version = "1.14.0")
bazel_dep(name = "rules_cc", version = "0.0.9")
bazel_dep(name = "platforms", version = "0.0.8")

# For http_archive deps not yet in BCR (Bazel Central Registry)
# Use module extensions

# Check available versions
bazel mod graph | head -30

# Show dependency tree
bazel mod deps --depth=2

4. 依赖关系图查询

# Show all dependencies of a target
bazel query "deps(//src:main)"

# Find reverse dependencies (who depends on this?)
bazel query "rdeps(//..., //lib:mylib)"

# Find what changed between builds
bazel query "filter('//lib', deps(//src:main))"

# cquery — configuration-aware query
bazel cquery "deps(//src:main)" --output=files

# Show include paths for a target
bazel cquery "//lib:mylib" --output=build

# Find cycles in the build graph
bazel query --nohost_deps --noimplicit_deps \
  "somepath(//src:main, //lib:mylib)"

# aquery — action graph (shows compiler flags, inputs, outputs)
bazel aquery "//src:main"
bazel aquery "//src:main" --output=jsonproto | jq '.actions[0].arguments'

5. 工具链注册

# platforms/BUILD
platform(
    name = "linux_x86_64",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:x86_64",
    ],
)

# toolchains/BUILD
cc_toolchain_suite(
    name = "my_toolchain",
    toolchains = {
        "k8": ":my_k8_toolchain",
    },
)

cc_toolchain(
    name = "my_k8_toolchain",
    all_files = ":empty",
    compiler_files = ":compiler_wrapper",
    # ... other file groups
)

toolchain(
    name = "my_cc_toolchain",
    toolchain = ":my_k8_toolchain",
    toolchain_type = "@bazel_tools//tools/cpp:toolchain_type",
    target_compatible_with = ["@platforms//os:linux"],
)

# MODULE.bazel — register toolchain
register_toolchains("//toolchains:my_cc_toolchain")

6. 远程执行

# Use --remote_executor flag
bazel build //... \
  --remote_executor=grpc://buildgrid.example.com:50051 \
  --remote_instance_name=main

# Google Cloud Build Remote Execution
bazel build //... \
  --remote_executor=remotebuildexecution.googleapis.com \
  --remote_instance_name=projects/my-project/instances/default \
  --google_default_credentials

# Caching (without remote execution)
bazel build //... \
  --remote_cache=grpc://cache.example.com:9092

# Show what's cached
bazel build //... --remote_upload_local_results=true

7. 沙箱调试

# Show sandbox inputs and outputs
bazel build //src:main --sandbox_debug

# Run build with verbose sandboxing
bazel build //src:main --verbose_failures --sandbox_debug

# Disable sandbox entirely (for debugging)
bazel build //src:main --spawn_strategy=local

# Common sandbox errors
# "No such file or directory" → missing data dependency
#   Fix: add file to `data = [...]` attribute
# "Permission denied" → trying to write outside sandbox
#   Fix: use genrule output paths instead of hardcoded paths
# "FAILED: Build did NOT complete successfully" → check verbose output

# See the exact command Bazel ran
bazel build //src:main --subcommands

有关 Bazel C++ 工具链配置，请参阅 references/bazel-cpp-toolchain.md。

相关技能

• 使用 skills/build-systems/cmake 将 CMake 用作替代构建系统
• 使用 skills/build-systems/build-acceleration 将 sccache 集成到 Bazel 远程缓存
• 使用 skills/compilers/gcc 或 skills/compilers/clang 获取 Bazel copts 中使用的编译器标志