Bazel Build Optimization

Production patterns for Bazel in large-scale monorepos.

When to Use This Skill

Setting up Bazel for monorepos
Configuring remote caching/execution
Optimizing build times
Writing custom Bazel rules
Debugging build issues
Migrating to Bazel

Core Concepts

Bazel Architecture

workspace/ ├── WORKSPACE.bazel # External dependencies ├── .bazelrc # Build configurations ├── .bazelversion # Bazel version ├── BUILD.bazel # Root build file ├── apps/ │ └── web/ │ └── BUILD.bazel ├── libs/ │ └── utils/ │ └── BUILD.bazel └── tools/ └── bazel/ └── rules/

Key Concepts

Concept Description

Target Buildable unit (library, binary, test)

Package Directory with BUILD file

Label Target identifier //path/to:target

Rule Defines how to build a target

Aspect Cross-cutting build behavior

Templates

Template 1: WORKSPACE Configuration

WORKSPACE.bazel

workspace(name = "myproject")

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

Rules for JavaScript/TypeScript

http_archive( name = "aspect_rules_js", sha256 = "...", strip_prefix = "rules_js-1.34.0", url = "https://github.com/aspect-build/rules_js/releases/download/v1.34.0/rules_js-v1.34.0.tar.gz", )

load("@aspect_rules_js//js:repositories.bzl", "rules_js_dependencies") rules_js_dependencies()

load("@rules_nodejs//nodejs:repositories.bzl", "nodejs_register_toolchains") nodejs_register_toolchains( name = "nodejs", node_version = "20.9.0", )

load("@aspect_rules_js//npm:repositories.bzl", "npm_translate_lock") npm_translate_lock( name = "npm", pnpm_lock = "//:pnpm-lock.yaml", verify_node_modules_ignored = "//:.bazelignore", )

load("@npm//:repositories.bzl", "npm_repositories") npm_repositories()

Rules for Python

http_archive( name = "rules_python", sha256 = "...", strip_prefix = "rules_python-0.27.0", url = "https://github.com/bazelbuild/rules_python/releases/download/0.27.0/rules_python-0.27.0.tar.gz", )

load("@rules_python//python:repositories.bzl", "py_repositories") py_repositories()

Template 2: .bazelrc Configuration

.bazelrc

Build settings

build --enable_platform_specific_config build --incompatible_enable_cc_toolchain_resolution build --experimental_strict_conflict_checks

Performance

build --jobs=auto build --local_cpu_resources=HOST_CPUS*.75 build --local_ram_resources=HOST_RAM*.75

Caching

build --disk_cache=~~/.cache/bazel-disk build --repository_cache=~~/.cache/bazel-repo

Remote caching (optional)

build:remote-cache --remote_cache=grpcs://cache.example.com build:remote-cache --remote_upload_local_results=true build:remote-cache --remote_timeout=3600

Remote execution (optional)

build:remote-exec --remote_executor=grpcs://remote.example.com build:remote-exec --remote_instance_name=projects/myproject/instances/default build:remote-exec --jobs=500

Platform configurations

build:linux --platforms=//platforms:linux_x86_64 build:macos --platforms=//platforms:macos_arm64

CI configuration

build:ci --config=remote-cache build:ci --build_metadata=ROLE=CI build:ci --bes_results_url=https://results.example.com/invocation/ build:ci --bes_backend=grpcs://bes.example.com

Test settings

test --test_output=errors test --test_summary=detailed

Coverage

coverage --combined_report=lcov coverage --instrumentation_filter="//..."

Convenience aliases

build:opt --compilation_mode=opt build:dbg --compilation_mode=dbg

Import user settings

try-import %workspace%/user.bazelrc

Template 3: TypeScript Library BUILD

libs/utils/BUILD.bazel

load("@aspect_rules_ts//ts:defs.bzl", "ts_project") load("@aspect_rules_js//js:defs.bzl", "js_library") load("@npm//:defs.bzl", "npm_link_all_packages")

npm_link_all_packages(name = "node_modules")

ts_project( name = "utils_ts", srcs = glob(["src/**/*.ts"]), declaration = True, source_map = True, tsconfig = "//:tsconfig.json", deps = [ ":node_modules/@types/node", ], )

js_library( name = "utils", srcs = [":utils_ts"], visibility = ["//visibility:public"], )

Tests

load("@aspect_rules_jest//jest:defs.bzl", "jest_test")

jest_test( name = "utils_test", config = "//:jest.config.js", data = [ ":utils", "//:node_modules/jest", ], node_modules = "//:node_modules", )

Template 4: Python Library BUILD

libs/ml/BUILD.bazel

load("@rules_python//python:defs.bzl", "py_library", "py_test", "py_binary") load("@pip//:requirements.bzl", "requirement")

py_library( name = "ml", srcs = glob(["src/**/*.py"]), deps = [ requirement("numpy"), requirement("pandas"), requirement("scikit-learn"), "//libs/utils:utils_py", ], visibility = ["//visibility:public"], )

py_test( name = "ml_test", srcs = glob(["tests/**/*.py"]), deps = [ ":ml", requirement("pytest"), ], size = "medium", timeout = "moderate", )

py_binary( name = "train", srcs = ["train.py"], deps = [":ml"], data = ["//data:training_data"], )

Template 5: Custom Rule for Docker

tools/bazel/rules/docker.bzl

def _docker_image_impl(ctx): dockerfile = ctx.file.dockerfile base_image = ctx.attr.base_image layers = ctx.files.layers

# Build the image
output = ctx.actions.declare_file(ctx.attr.name + ".tar")

args = ctx.actions.args()
args.add("--dockerfile", dockerfile)
args.add("--output", output)
args.add("--base", base_image)
args.add_all("--layer", layers)

ctx.actions.run(
    inputs = [dockerfile] + layers,
    outputs = [output],
    executable = ctx.executable._builder,
    arguments = [args],
    mnemonic = "DockerBuild",
    progress_message = "Building Docker image %s" % ctx.label,
)

return [DefaultInfo(files = depset([output]))]

docker_image = rule( implementation = _docker_image_impl, attrs = { "dockerfile": attr.label( allow_single_file = [".dockerfile", "Dockerfile"], mandatory = True, ), "base_image": attr.string(mandatory = True), "layers": attr.label_list(allow_files = True), "_builder": attr.label( default = "//tools/docker:builder", executable = True, cfg = "exec", ), }, )

Template 6: Query and Dependency Analysis

Find all dependencies of a target

bazel query "deps(//apps/web:web)"

Find reverse dependencies (what depends on this)

bazel query "rdeps(//..., //libs/utils:utils)"

Find all targets in a package

bazel query "//libs/..."

Find changed targets since commit

bazel query "rdeps(//..., set($(git diff --name-only HEAD~1 | sed 's/.*/"&"/' | tr '\n' ' ')))"

Generate dependency graph

bazel query "deps(//apps/web:web)" --output=graph | dot -Tpng > deps.png

Find all test targets

bazel query "kind('.*_test', //...)"

Find targets with specific tag

bazel query "attr(tags, 'integration', //...)"

Compute build graph size

bazel query "deps(//...)" --output=package | wc -l

Template 7: Remote Execution Setup

platforms/BUILD.bazel

platform( name = "linux_x86_64", constraint_values = [ "@platforms//os:linux", "@platforms//cpu:x86_64", ], exec_properties = { "container-image": "docker://gcr.io/myproject/bazel-worker:latest", "OSFamily": "Linux", }, )

platform( name = "remote_linux", parents = [":linux_x86_64"], exec_properties = { "Pool": "default", "dockerNetwork": "standard", }, )

toolchains/BUILD.bazel

toolchain( name = "cc_toolchain_linux", exec_compatible_with = [ "@platforms//os:linux", "@platforms//cpu:x86_64", ], target_compatible_with = [ "@platforms//os:linux", "@platforms//cpu:x86_64", ], toolchain = "@remotejdk11_linux//:jdk", toolchain_type = "@bazel_tools//tools/jdk:runtime_toolchain_type", )

Performance Optimization

Profile build

bazel build //... --profile=profile.json bazel analyze-profile profile.json

Identify slow actions

bazel build //... --execution_log_json_file=exec_log.json

Memory profiling

bazel build //... --memory_profile=memory.json

Skip analysis cache

bazel build //... --notrack_incremental_state

Best Practices

Do's

Use fine-grained targets - Better caching
Pin dependencies - Reproducible builds
Enable remote caching - Share build artifacts
Use visibility wisely - Enforce architecture
Write BUILD files per directory - Standard convention

Don'ts

Don't use glob for deps - Explicit is better
Don't commit bazel-* dirs - Add to .gitignore
Don't skip WORKSPACE setup - Foundation of build
Don't ignore build warnings - Technical debt