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