Bazel

Bazel

Bazel for C/C++ projects: BUILD files, Bzlmod dependencies, toolchain registration, remote execution, dependency graph queries, and sandbox debugging. Grounded against Bazel 9.2.0, where Bzlmod is always enabled, all WORKSPACE logic is removed, and every C++ rule loads from @rules_cc.

Contract

Inputs

• Project layout (required): the source tree and where BUILD files should live.
• Bazel version (required if not inferrable): run bazel version. Bazel 9 removed WORKSPACE and the native C++ rules; instructions below assume Bazel 9.
• External dependencies (optional): library names; versions come from the Bazel Central Registry.
• Remote execution endpoint (optional): a user-supplied remote execution or cache service URL.

Procedure

1. Lay out the workspace. Bazel 9 uses MODULE.bazel as the only dependency file; there is no WORKSPACE. Put a BUILD file in each package directory. Done when: MODULE.bazel exists at the root and each package has a BUILD file.

my-project/
├── MODULE.bazel
├── BUILD
├── src/
│   ├── BUILD
│   └── main.cc
└── lib/
    ├── BUILD
    ├── mylib.cc
    └── mylib.h

2. Write BUILD rules. Load every C++ rule from @rules_cc; the native cc_library/cc_binary/cc_test rules were removed from Bazel 9. Done when: every target builds with bazel build.

# lib/BUILD
load("@rules_cc//cc:defs.bzl", "cc_library", "cc_test")

cc_library(
    name = "mylib",
    srcs = ["mylib.cc"],
    hdrs = ["mylib.h"],
    copts = ["-Wall", "-Wextra", "-std=c++23"],
    visibility = ["//visibility:public"],
    deps = [
        "@abseil-cpp//absl/strings",
        "//util:helpers",
    ],
)

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

# src/BUILD
load("@rules_cc//cc:defs.bzl", "cc_binary")

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

bazel build //src:main
bazel build //...
bazel test //lib:mylib_test
bazel run //src:main -- arg1 arg2
# Binary lands at bazel-bin/src/main

3. Declare dependencies in MODULE.bazel with bazel_dep. Versions come from the Bazel Central Registry; the pins below are the versions Bazel 9.2.0 itself depends on. Done when: bazel mod graph resolves without errors.

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

bazel_dep(name = "rules_cc", version = "0.2.17")
bazel_dep(name = "platforms", version = "1.0.0")
bazel_dep(name = "abseil-cpp", version = "20250814.1")
bazel_dep(name = "googletest", version = "1.17.0.bcr.2")

bazel mod graph        # full resolved dependency graph
bazel mod deps         # direct and indirect module deps
bazel mod tidy         # fix up MODULE.bazel declarations

4. Query the dependency graph. Done when: the query answers the question asked.

bazel query "deps(//src:main)"                  # transitive deps
bazel query "rdeps(//..., //lib:mylib)"         # reverse deps
bazel query "somepath(//src:main, //lib:mylib)" # dependency path
bazel cquery "deps(//src:main)" --output=files  # configuration-aware
bazel cquery "//lib:mylib" --output=build       # effective rule
bazel aquery "//src:main"                       # action graph: flags, inputs, outputs

5. Register toolchains with platforms. Define a platform with constraint values, a toolchain binding a toolchain target to a toolchain type, then register_toolchains in MODULE.bazel. The C++ toolchain configuration API lives in rules_cc under cc/toolchains; see references/bazel-cpp-toolchain.md. Done when: bazel build --platforms=//platforms:<name> selects the registered toolchain.

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

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

6. Configure remote execution or caching when the user supplies an endpoint. Done when: the build runs against the endpoint or the flag is rejected and reported.

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

# Cache only, no remote execution
bazel build //... --remote_cache=grpc://cache.example.com:9092

7. Debug sandbox failures. Done when: the failing action is identified and its missing input or disallowed write is fixed.

bazel build //src:main --sandbox_debug        # show sandbox inputs/outputs
bazel build //src:main --verbose_failures --sandbox_debug
bazel build //src:main --spawn_strategy=local # bypass sandbox to isolate it
bazel build //src:main --subcommands          # print each command run

Common sandbox causes: "No such file or directory" means a missing data or srcs entry; "Permission denied" means a write outside the sandbox, fixed by routing outputs through declared rule outputs.

Failure and recovery

• bazel build fails on a missing load: add load("@rules_cc//cc:defs.bzl", ...) for the rule used; Bazel 9 has no native C++ rules.
• bazel_dep version not found: run bazel mod graph to see the error, then pick a version listed in the Bazel Central Registry.
• Sandbox error persists after adding inputs: reproduce with --spawn_strategy=local; if the local run passes, the sandbox is missing a declared input.
• Remote execution unreachable: drop --remote_executor and rebuild locally; report the endpoint failure rather than retrying blindly.
• Query returns empty: check the target pattern with bazel query "//..." first; an empty pattern means the package path is wrong.
• Migration from WORKSPACE: run the Bzlmod migration path (bazel mod tidy after declaring deps); do not recreate WORKSPACE, Bazel 9 ignores it.

Output

Working BUILD files and MODULE.bazel declarations, a verified bazel build/bazel test invocation, and for debugging tasks the identified failing action with its fix. For toolchain work, a registered toolchain plus platform pair verified by --platforms.