# WORKSPACE 文件示例（最简形式，可以为空）workspace(name = "my_project")

工作区（Workspace）├── 主仓库（Main Repository）     ← 你的项目代码│   ├── WORKSPACE│   ├── src/│   └── lib/└── 外部仓库（External Repos）    ├── @com_google_absl          ← 通过 http_archive 引入    ├── @com_github_gtest         ← 通过 http_archive 引入    └── @local_config_cc          ← C++ 工具链配置

my-project/              ← 工作区根├── WORKSPACE├── BUILD                ← 根包 ""（空字符串）├── src/│   ├── BUILD            ← 包 "src"│   ├── main.cc│   └── util.cc├── src/io/│   ├── BUILD            ← 包 "src/io"│   ├── reader.cc│   └── writer.cc└── lib/    ├── BUILD            ← 包 "lib"    ├── math.cc    └── string.cc

✅ 推荐                                     ❌ 避免─────────────────────────                  ─────────────────────────每个有独立职责的目录放一个 BUILD            在根目录放一个巨大的 BUILD包的粒度适中（5-20个目标）                  单个包包含上百个目标按功能/模块划分包                           按文件类型划分包保持包之间的依赖关系清晰                    循环依赖

cc_binary(    name = "hello_world",    srcs = ["hello.cc"],    deps = [        "//lib:greeting",    ],)

cc_library(    name = "greeting",    srcs = ["greeting.cc"],    hdrs = ["greeting.h"],    deps = [        "//lib:string_utils",    ],)

cc_test(    name = "greeting_test",    srcs = ["greeting_test.cc"],    deps = [        "//src:greeting",        "@com_github_gtest//:gtest_main",    ],)

cc_proto_library(    name = "person_proto_cc",    deps = [":person_proto"],)proto_library(    name = "person_proto",    srcs = ["person.proto"],)

@repository//package:target

@com_google_absl//absl/strings:str_format│                  │             ││                  │             └── 目标名 (target)│                  └── 包路径 (package)└── 仓库名 (repository)

# 完整形式@com_google_absl//absl/strings:str_format# 主仓库中//lib/math:math_utils      # 完整//lib/math                  # 等价于 //lib/math:math（包名=目标名时）# 同包内的简写（最常用）:math_utils                 # 当前包的 math_utils 目标math_utils                  # 同上（省略冒号，但不推荐）# 根包//:hello                    # 根包的 hello 目标hello                       # 同上（仅根包适用）

# ✅ 推荐：跨包依赖使用完整标签deps = ["//lib/math:math_utils"]# ✅ 推荐：同包依赖使用冒号前缀deps = [":greeting"]# ❌ 避免：省略冒号（歧义，不推荐）deps = ["greeting"]# ❌ 避免：使用绝对路径引用本地文件# Bazel 不使用文件系统路径，始终使用标签

cc_library(    name = "app",    srcs = ["app.cc"],          # srcs 中的文件是 app 的依赖    hdrs = ["app.h"],    deps = [                     # deps 声明对其他目标的依赖        ":core",        "//lib:utils",    ],)

依赖类型        传播方向            说明─────────      ────────           ──────srcs           不传播              仅当前目标使用hdrs           传播给依赖者        公共头文件，依赖者可 #includedeps           传播给依赖者        传递依赖（A→B→C，则 A 可用 C）implementation_deps  不传播给依赖者  仅当前库实现使用，不暴露给上层data           不传播              运行时数据文件

cc_binary //:app├── cc_library //:core│   ├── cc_library //lib:utils│   │   └── cc_library //lib:base│   └── @com_google_absl//absl/strings└── cc_library //:io    └── cc_library //lib:utils

# 根目录 BUILDcc_binary(    name = "app",    srcs = ["app.cc"],    deps = [        ":core",        ":io",    ],)cc_library(    name = "core",    srcs = ["core.cc"],    hdrs = ["core.h"],    deps = [        "//lib:utils",        "@com_google_absl//absl/strings",    ],)cc_library(    name = "io",    srcs = ["io.cc"],    hdrs = ["io.h"],    deps = ["//lib:utils"],)

# lib/BUILDcc_library(    name = "utils",    srcs = ["utils.cc"],    hdrs = ["utils.h"],    deps = [":base"],)cc_library(    name = "base",    srcs = ["base.cc"],    hdrs = ["base.h"],)

# 查询目标的所有依赖bazel query "deps(//:app)"# 查询依赖某个目标的所有目标bazel query "rdeps(//..., //lib:base)"# 生成依赖图（需要 graphviz）bazel query "deps(//:app)" --output=graph | dot -Tpng -o deps.png# 查询目标的直接依赖bazel query "deps(//:app, 1)"# 查找两个目标之间的依赖路径bazel query "somepath(//:app, //lib:base)"# 查看包中的所有目标bazel query "//lib:*"

cc_library(    name = "internal_util",    srcs = ["internal_util.cc"],    hdrs = ["internal_util.h"],    visibility = ["//visibility:private"],  # 仅同包可见（默认）)cc_library(    name = "public_api",    srcs = ["public_api.cc"],    hdrs = ["public_api.h"],    visibility = ["//visibility:public"],   # 对所有包可见)cc_library(    name = "team_api",    srcs = ["team_api.cc"],    hdrs = ["team_api.h"],    visibility = [        "//src:__pkg__",       # 仅 src 包可见        "//tests:__pkg__",     # 仅 tests 包可见        "//lib/...:__pkg__",   # lib 下所有包可见    ],)

配置 = 选项组合 + 平台 + 工具链

# 快速构建（默认）—— 不优化，带调试信息，构建速度快bazel build //:app -c fastbuild# 调试模式 —— 不优化，完整调试信息bazel build //:app -c dbg# 优化模式 —— 开启优化，适合发布bazel build //:app -c opt

cc_library(    name = "platform_lib",    srcs = ["platform_lib.cc"],    hdrs = ["platform_lib.h"],    copts = select({        "//:windows": ["/O2", "/W4"],          # Windows MSVC 选项        "//:linux": ["-O2", "-Wall"],           # Linux GCC 选项        "//:macos": ["-O2", "-Wall", "-stdlib=libc++"],        "//conditions:default": ["-O2"],         # 默认选项    }),    deps = select({        "//:use_absl": ["@com_google_absl//absl/strings"],        "//conditions:default": [],    }),)

# 根 BUILD 文件config_setting(    name = "windows",    constraint_values = [        "@platforms//os:windows",    ],)config_setting(    name = "linux",    constraint_values = [        "@platforms//os:linux",    ],)config_setting(    name = "use_absl",    define_values = {        "use_absl": "true",    },)

bazel build //:platform_lib --define use_absl=true

# 构建bazel build //:target                    # 构建指定目标bazel build //...                        # 构建工作区所有目标bazel build //src:all                    # 构建指定包所有目标# 运行bazel run //:target                      # 构建并运行bazel run //:target -- --arg1 --arg2     # 传递参数（用 -- 分隔）# 测试bazel test //:all                        # 运行所有测试bazel test //tests:math_test             # 运行指定测试bazel test //... --test_output=all       # 显示所有测试输出# 清理bazel clean                             # 清理构建输出bazel clean --expunge                   # 完全清理（包括缓存）# 查询bazel query //...                        # 列出所有目标bazel query "kind(cc_library, //...)"    # 列出所有 cc_librarybazel query "deps(//:app)"              # 查询依赖

# 并发控制bazel build //:app --jobs=8              # 使用 8 个并发任务# 输出控制bazel build //:app --verbose_failures    # 失败时显示完整命令bazel build //:app --action_env=VAR=val  # 设置环境变量# 配置bazel build //:app -c opt               # 优化模式bazel build //:app --config=release      # 使用 .bazelrc 中定义的配置# 远程缓存bazel build //:app --remote_cache=grpc://cache.example.com:9092