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.

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

Workflow

1. Workspace structure

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. Basic BUILD file — 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 — modern dependency management

# 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. Dependency graph queries

# 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. Toolchain registration

# 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. Remote execution

# 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. Sandbox debugging

# 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

For Bazel C++ toolchain configuration, see 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

Bazel C++ Toolchain Reference

Source: https://bazel.build/docs/cc-toolchain-config-reference

Minimal Custom Toolchain

# toolchains/BUILD
load("@bazel_tools//tools/cpp:cc_toolchain_config.bzl", "cc_toolchain_config")

cc_toolchain_config(
    name = "k8_toolchain_config",
    cpu = "k8",
    compiler = "gcc",
    toolchain_identifier = "local",
    host_system_name = "local",
    target_system_name = "local",
    target_libc = "glibc_2.31",
    abi_version = "gcc",
    abi_libc_version = "glibc_2.31",
    tool_paths = {
        "ar":      "/usr/bin/ar",
        "cpp":     "/usr/bin/cpp",
        "gcc":     "/usr/bin/gcc",
        "gcov":    "/usr/bin/gcov",
        "ld":      "/usr/bin/ld",
        "nm":      "/usr/bin/nm",
        "objdump": "/usr/bin/objdump",
        "strip":   "/usr/bin/strip",
    },
    compile_flags = ["-Wall", "-Wextra"],
    opt_compile_flags = ["-O2", "-DNDEBUG"],
    dbg_compile_flags = ["-g", "-O0"],
    link_flags = ["-lpthread", "-lm"],
    cxx_flags = ["-std=c++17"],
)

cc_toolchain(
    name = "k8_toolchain",
    all_files = ":empty",
    ar_files = ":empty",
    as_files = ":empty",
    compiler_files = ":empty",
    dwp_files = ":empty",
    linker_files = ":empty",
    objcopy_files = ":empty",
    strip_files = ":empty",
    supports_param_files = 0,
    toolchain_config = ":k8_toolchain_config",
    toolchain_identifier = "k8-toolchain",
)

toolchain(
    name = "cc_toolchain_k8",
    exec_compatible_with = [
        "@platforms//cpu:x86_64",
        "@platforms//os:linux",
    ],
    target_compatible_with = [
        "@platforms//cpu:x86_64",
        "@platforms//os:linux",
    ],
    toolchain = ":k8_toolchain",
    toolchain_type = "@bazel_tools//tools/cpp:toolchain_type",
)

# placeholder
filegroup(name = "empty")

Cross-Compilation Toolchain

cc_toolchain_config(
    name = "arm64_toolchain_config",
    cpu = "aarch64",
    compiler = "gcc",
    toolchain_identifier = "cross-arm64",
    host_system_name = "x86_64-linux-gnu",
    target_system_name = "aarch64-linux-gnu",
    target_libc = "glibc_2.31",
    abi_version = "gcc",
    abi_libc_version = "glibc_2.31",
    tool_paths = {
        "ar":  "/usr/bin/aarch64-linux-gnu-ar",
        "gcc": "/usr/bin/aarch64-linux-gnu-gcc",
        "ld":  "/usr/bin/aarch64-linux-gnu-ld",
        "nm":  "/usr/bin/aarch64-linux-gnu-nm",
        "strip": "/usr/bin/aarch64-linux-gnu-strip",
    },
    compile_flags = ["--sysroot=/sysroots/aarch64"],
    link_flags = ["--sysroot=/sysroots/aarch64"],
    cxx_flags = ["-std=c++17"],
)

Common Build Flags

# Force optimized build
bazel build //... -c opt

# Force debug build
bazel build //... -c dbg

# Use specific toolchain
bazel build //... --extra_toolchains=//toolchains:cc_toolchain_k8

# Pass compiler flags
bazel build //... --copt=-fsanitize=address --linkopt=-fsanitize=address

# Target specific platform
bazel build //... --platforms=//platforms:linux_arm64