Back to Details

bazel

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bazel

Bazel

Purpose

用途

Guide agents through Bazel for C/C++ projects: writing BUILD files, cc_library/cc_binary rules, toolchain registration, remote execution, dependency graph queries, Bzlmod dependency management, and sandbox debugging.
为C/C++项目的Bazel使用提供指导：编写BUILD文件、cc_library/cc_binary规则、工具链注册、远程执行、依赖图查询、Bzlmod依赖管理以及沙箱调试。

Triggers

触发场景

  • "How do I write a Bazel BUILD file for a C++ library?"
  • "How do I add external dependencies with Bzlmod?"
  • "How do I debug Bazel sandbox errors?"
  • "How do I query the Bazel dependency graph?"
  • "How do I set up remote execution with Bazel?"
  • "How do I register a custom C++ toolchain?"
  • "如何为C++库编写Bazel BUILD文件？"
  • "如何使用Bzlmod添加外部依赖？"
  • "如何调试Bazel沙箱错误？"
  • "如何查询Bazel依赖图？"
  • "如何为Bazel配置远程执行？"
  • "如何注册自定义C++工具链？"

Workflow

工作流程

1. Workspace structure

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
my-project/
├── MODULE.bazel         # Bzlmod依赖文件 (Bazel ≥6)
├── WORKSPACE            # 旧版配置（部分功能仍需使用）
├── BUILD                # 根构建文件
├── src/
│   ├── BUILD
│   └── main.cc
└── lib/
    ├── BUILD
    ├── mylib.cc
    └── mylib.h

2. Basic BUILD file — cc_library / cc_binary

2. 基础BUILD文件 — cc_library / cc_binary

python
undefined
python
undefined

lib/BUILD

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", ], )

```python
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", # 外部依赖 "//util:helpers", # 内部依赖 ], )
cc_test( name = "mylib_test", srcs = ["mylib_test.cc"], deps = [ ":mylib", "@com_google_googletest//:gtest_main", ], )

```python

src/BUILD

src/BUILD

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

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

```bash

Build

构建

bazel build //src:main bazel build //... # build everything
bazel build //src:main bazel build //... # 构建所有目标

Test

测试

bazel test //lib:mylib_test bazel test //... # run all tests
bazel test //lib:mylib_test bazel test //... # 运行所有测试

Run

运行

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

Output path

输出路径

bazel-bin/src/main
undefined
bazel-bin/src/main
undefined

3. Bzlmod — modern dependency management

3. Bzlmod — 现代依赖管理

python
undefined
python
undefined

MODULE.bazel

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")
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)

对于尚未加入BCR（Bazel中央仓库）的http_archive依赖

Use module extensions

使用模块扩展


```bash

```bash

Check available versions

查看可用版本

bazel mod graph | head -30
bazel mod graph | head -30

Show dependency tree

显示依赖树

bazel mod deps --depth=2
undefined
bazel mod deps --depth=2
undefined

4. Dependency graph queries

4. 依赖图查询

bash
undefined
bash
undefined

Show all dependencies of a target

显示某个目标的所有依赖

bazel query "deps(//src:main)"
bazel query "deps(//src:main)"

Find reverse dependencies (who depends on this?)

查找反向依赖（哪些目标依赖于当前目标？）

bazel query "rdeps(//..., //lib:mylib)"
bazel query "rdeps(//..., //lib:mylib)"

Find what changed between builds

查找两次构建之间的变更

bazel query "filter('//lib', deps(//src:main))"
bazel query "filter('//lib', deps(//src:main))"

cquery — configuration-aware query

cquery — 感知配置的查询

bazel cquery "deps(//src:main)" --output=files
bazel cquery "deps(//src:main)" --output=files

Show include paths for a target

显示目标的包含路径

bazel cquery "//lib:mylib" --output=build
bazel cquery "//lib:mylib" --output=build

Find cycles in the build graph

查找构建图中的循环依赖

bazel query --nohost_deps --noimplicit_deps
"somepath(//src:main, //lib:mylib)"
bazel query --nohost_deps --noimplicit_deps
"somepath(//src:main, //lib:mylib)"

aquery — action graph (shows compiler flags, inputs, outputs)

aquery — 动作图（显示编译器参数、输入、输出）

bazel aquery "//src:main" bazel aquery "//src:main" --output=jsonproto | jq '.actions[0].arguments'
undefined
bazel aquery "//src:main" bazel aquery "//src:main" --output=jsonproto | jq '.actions[0].arguments'
undefined

5. Toolchain registration

5. 工具链注册

python
undefined
python
undefined

platforms/BUILD

platforms/BUILD

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

toolchains/BUILD

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"], )

```python
cc_toolchain_suite( name = "my_toolchain", toolchains = { "k8": ":my_k8_toolchain", }, )
cc_toolchain( name = "my_k8_toolchain", all_files = ":empty", compiler_files = ":compiler_wrapper", # ... 其他文件组 )
toolchain( name = "my_cc_toolchain", toolchain = ":my_k8_toolchain", toolchain_type = "@bazel_tools//tools/cpp:toolchain_type", target_compatible_with = ["@platforms//os:linux"], )

```python

MODULE.bazel — register toolchain

MODULE.bazel — 注册工具链

register_toolchains("//toolchains:my_cc_toolchain")
undefined
register_toolchains("//toolchains:my_cc_toolchain")
undefined

6. Remote execution

6. 远程执行

bash
undefined
bash
undefined

Use --remote_executor flag

使用 --remote_executor 参数

bazel build //...
--remote_executor=grpc://buildgrid.example.com:50051
--remote_instance_name=main
bazel build //...
--remote_executor=grpc://buildgrid.example.com:50051
--remote_instance_name=main

Google Cloud Build Remote Execution

Google Cloud Build 远程执行

bazel build //...
--remote_executor=remotebuildexecution.googleapis.com
--remote_instance_name=projects/my-project/instances/default
--google_default_credentials
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
bazel build //...
--remote_cache=grpc://cache.example.com:9092

Show what's cached

查看已缓存内容

bazel build //... --remote_upload_local_results=true
undefined
bazel build //... --remote_upload_local_results=true
undefined

7. Sandbox debugging

7. 沙箱调试

bash
undefined
bash
undefined

Show sandbox inputs and outputs

显示沙箱的输入和输出

bazel build //src:main --sandbox_debug
bazel build //src:main --sandbox_debug

Run build with verbose sandboxing

启用详细沙箱日志运行构建

bazel build //src:main --verbose_failures --sandbox_debug
bazel build //src:main --verbose_failures --sandbox_debug

Disable sandbox entirely (for debugging)

完全禁用沙箱（用于调试）

bazel build //src:main --spawn_strategy=local
bazel build //src:main --spawn_strategy=local

Common sandbox errors

常见沙箱错误

"No such file or directory" → missing data dependency

"No such file or directory" → 缺少数据依赖

Fix: add file to 
data = [...]
attribute

修复方法：将文件添加到 
data = [...]
属性中

"Permission denied" → trying to write outside sandbox

"Permission denied" → 尝试向沙箱外写入内容

Fix: use genrule output paths instead of hardcoded paths

修复方法：使用genrule输出路径而非硬编码路径

"FAILED: Build did NOT complete successfully" → check verbose output

"FAILED: Build did NOT complete successfully" → 查看详细输出信息

See the exact command Bazel ran

查看Bazel执行的具体命令

bazel build //src:main --subcommands

For Bazel C++ toolchain configuration, see [references/bazel-cpp-toolchain.md](references/bazel-cpp-toolchain.md).
bazel build //src:main --subcommands

关于Bazel C++工具链配置，请参考 [references/bazel-cpp-toolchain.md](references/bazel-cpp-toolchain.md)。

Related skills

相关技能

  • Use 
    skills/build-systems/cmake
    for CMake as an alternative build system
  • Use 
    skills/build-systems/build-acceleration
    for sccache integration with Bazel remote cache
  • Use 
    skills/compilers/gcc
    or 
    skills/compilers/clang
    for compiler flags used in Bazel 
    copts
  • 若使用替代构建系统CMake，请使用 
    skills/build-systems/cmake
  • 若需将sccache与Bazel远程缓存集成，请使用 
    skills/build-systems/build-acceleration
  • 若需了解Bazel 
    copts
    中使用的编译器参数，请使用 
    skills/compilers/gcc
    或 
    skills/compilers/clang