Bazel Build Optimization

1---
2name: bazel-build-optimization
3description: Optimize Bazel builds for large-scale monorepos. Use when configuring Bazel, implementing remote execution, or optimizing build performance for enterprise codebases.
4---
5 
6# Bazel Build Optimization
7 
8Production patterns for Bazel in large-scale monorepos.
9 
10## Do not use this skill when
11 
12- The task is unrelated to bazel build optimization
13- You need a different domain or tool outside this scope
14 
15## Instructions
16 
17- Clarify goals, constraints, and required inputs.
18- Apply relevant best practices and validate outcomes.
19- Provide actionable steps and verification.
20- If detailed examples are required, open `resources/implementation-playbook.md`.
21 
22## Use this skill when
23 
24- Setting up Bazel for monorepos
25- Configuring remote caching/execution
26- Optimizing build times
27- Writing custom Bazel rules
28- Debugging build issues
29- Migrating to Bazel
30 
31## Core Concepts
32 
33### 1. Bazel Architecture
34 
35```
36workspace/
37├── WORKSPACE.bazel       # External dependencies
38├── .bazelrc              # Build configurations
39├── .bazelversion         # Bazel version
40├── BUILD.bazel           # Root build file
41├── apps/
42│   └── web/
43│       └── BUILD.bazel
44├── libs/
45│   └── utils/
46│       └── BUILD.bazel
47└── tools/
48    └── bazel/
49        └── rules/
50```
51 
52### 2. Key Concepts
53 
54| Concept | Description |
55|---------|-------------|
56| **Target** | Buildable unit (library, binary, test) |
57| **Package** | Directory with BUILD file |
58| **Label** | Target identifier `//path/to:target` |
59| **Rule** | Defines how to build a target |
60| **Aspect** | Cross-cutting build behavior |
61 
62## Templates
63 
64### Template 1: WORKSPACE Configuration
65 
66```python
67# WORKSPACE.bazel
68workspace(name = "myproject")
69 
70load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
71 
72# Rules for JavaScript/TypeScript
73http_archive(
74    name = "aspect_rules_js",
75    sha256 = "...",
76    strip_prefix = "rules_js-1.34.0",
77    url = "https://github.com/aspect-build/rules_js/releases/download/v1.34.0/rules_js-v1.34.0.tar.gz",
78)
79 
80load("@aspect_rules_js//js:repositories.bzl", "rules_js_dependencies")
81rules_js_dependencies()
82 
83load("@rules_nodejs//nodejs:repositories.bzl", "nodejs_register_toolchains")
84nodejs_register_toolchains(
85    name = "nodejs",
86    node_version = "20.9.0",
87)
88 
89load("@aspect_rules_js//npm:repositories.bzl", "npm_translate_lock")
90npm_translate_lock(
91    name = "npm",
92    pnpm_lock = "//:pnpm-lock.yaml",
93    verify_node_modules_ignored = "//:.bazelignore",
94)
95 
96load("@npm//:repositories.bzl", "npm_repositories")
97npm_repositories()
98 
99# Rules for Python
100http_archive(
101    name = "rules_python",
102    sha256 = "...",
103    strip_prefix = "rules_python-0.27.0",
104    url = "https://github.com/bazelbuild/rules_python/releases/download/0.27.0/rules_python-0.27.0.tar.gz",
105)
106 
107load("@rules_python//python:repositories.bzl", "py_repositories")
108py_repositories()
109```
110 
111### Template 2: .bazelrc Configuration
112 
113```bash
114# .bazelrc
115 
116# Build settings
117build --enable_platform_specific_config
118build --incompatible_enable_cc_toolchain_resolution
119build --experimental_strict_conflict_checks
120 
121# Performance
122build --jobs=auto
123build --local_cpu_resources=HOST_CPUS*.75
124build --local_ram_resources=HOST_RAM*.75
125 
126# Caching
127build --disk_cache=~/.cache/bazel-disk
128build --repository_cache=~/.cache/bazel-repo
129 
130# Remote caching (optional)
131build:remote-cache --remote_cache=grpcs://cache.example.com
132build:remote-cache --remote_upload_local_results=true
133build:remote-cache --remote_timeout=3600
134 
135# Remote execution (optional)
136build:remote-exec --remote_executor=grpcs://remote.example.com
137build:remote-exec --remote_instance_name=projects/myproject/instances/default
138build:remote-exec --jobs=500
139 
140# Platform configurations
141build:linux --platforms=//platforms:linux_x86_64
142build:macos --platforms=//platforms:macos_arm64
143 
144# CI configuration
145build:ci --config=remote-cache
146build:ci --build_metadata=ROLE=CI
147build:ci --bes_results_url=https://results.example.com/invocation/
148build:ci --bes_backend=grpcs://bes.example.com
149 
150# Test settings
151test --test_output=errors
152test --test_summary=detailed
153 
154# Coverage
155coverage --combined_report=lcov
156coverage --instrumentation_filter="//..."
157 
158# Convenience aliases
159build:opt --compilation_mode=opt
160build:dbg --compilation_mode=dbg
161 
162# Import user settings
163try-import %workspace%/user.bazelrc
164```
165 
166### Template 3: TypeScript Library BUILD
167 
168```python
169# libs/utils/BUILD.bazel
170load("@aspect_rules_ts//ts:defs.bzl", "ts_project")
171load("@aspect_rules_js//js:defs.bzl", "js_library")
172load("@npm//:defs.bzl", "npm_link_all_packages")
173 
174npm_link_all_packages(name = "node_modules")
175 
176ts_project(
177    name = "utils_ts",
178    srcs = glob(["src/**/*.ts"]),
179    declaration = True,
180    source_map = True,
181    tsconfig = "//:tsconfig.json",
182    deps = [
183        ":node_modules/@types/node",
184    ],
185)
186 
187js_library(
188    name = "utils",
189    srcs = [":utils_ts"],
190    visibility = ["//visibility:public"],
191)
192 
193# Tests
194load("@aspect_rules_jest//jest:defs.bzl", "jest_test")
195 
196jest_test(
197    name = "utils_test",
198    config = "//:jest.config.js",
199    data = [
200        ":utils",
201        "//:node_modules/jest",
202    ],
203    node_modules = "//:node_modules",
204)
205```
206 
207### Template 4: Python Library BUILD
208 
209```python
210# libs/ml/BUILD.bazel
211load("@rules_python//python:defs.bzl", "py_library", "py_test", "py_binary")
212load("@pip//:requirements.bzl", "requirement")
213 
214py_library(
215    name = "ml",
216    srcs = glob(["src/**/*.py"]),
217    deps = [
218        requirement("numpy"),
219        requirement("pandas"),
220        requirement("scikit-learn"),
221        "//libs/utils:utils_py",
222    ],
223    visibility = ["//visibility:public"],
224)
225 
226py_test(
227    name = "ml_test",
228    srcs = glob(["tests/**/*.py"]),
229    deps = [
230        ":ml",
231        requirement("pytest"),
232    ],
233    size = "medium",
234    timeout = "moderate",
235)
236 
237py_binary(
238    name = "train",
239    srcs = ["train.py"],
240    deps = [":ml"],
241    data = ["//data:training_data"],
242)
243```
244 
245### Template 5: Custom Rule for Docker
246 
247```python
248# tools/bazel/rules/docker.bzl
249def _docker_image_impl(ctx):
250    dockerfile = ctx.file.dockerfile
251    base_image = ctx.attr.base_image
252    layers = ctx.files.layers
253 
254    # Build the image
255    output = ctx.actions.declare_file(ctx.attr.name + ".tar")
256 
257    args = ctx.actions.args()
258    args.add("--dockerfile", dockerfile)
259    args.add("--output", output)
260    args.add("--base", base_image)
261    args.add_all("--layer", layers)
262 
263    ctx.actions.run(
264        inputs = [dockerfile] + layers,
265        outputs = [output],
266        executable = ctx.executable._builder,
267        arguments = [args],
268        mnemonic = "DockerBuild",
269        progress_message = "Building Docker image %s" % ctx.label,
270    )
271 
272    return [DefaultInfo(files = depset([output]))]
273 
274docker_image = rule(
275    implementation = _docker_image_impl,
276    attrs = {
277        "dockerfile": attr.label(
278            allow_single_file = [".dockerfile", "Dockerfile"],
279            mandatory = True,
280        ),
281        "base_image": attr.string(mandatory = True),
282        "layers": attr.label_list(allow_files = True),
283        "_builder": attr.label(
284            default = "//tools/docker:builder",
285            executable = True,
286            cfg = "exec",
287        ),
288    },
289)
290```
291 
292### Template 6: Query and Dependency Analysis
293 
294```bash
295# Find all dependencies of a target
296bazel query "deps(//apps/web:web)"
297 
298# Find reverse dependencies (what depends on this)
299bazel query "rdeps(//..., //libs/utils:utils)"
300 
301# Find all targets in a package
302bazel query "//libs/..."
303 
304# Find changed targets since commit
305bazel query "rdeps(//..., set($(git diff --name-only HEAD~1 | sed 's/.*/"&"/' | tr '\n' ' ')))"
306 
307# Generate dependency graph
308bazel query "deps(//apps/web:web)" --output=graph | dot -Tpng > deps.png
309 
310# Find all test targets
311bazel query "kind('.*_test', //...)"
312 
313# Find targets with specific tag
314bazel query "attr(tags, 'integration', //...)"
315 
316# Compute build graph size
317bazel query "deps(//...)" --output=package | wc -l
318```
319 
320### Template 7: Remote Execution Setup
321 
322```python
323# platforms/BUILD.bazel
324platform(
325    name = "linux_x86_64",
326    constraint_values = [
327        "@platforms//os:linux",
328        "@platforms//cpu:x86_64",
329    ],
330    exec_properties = {
331        "container-image": "docker://gcr.io/myproject/bazel-worker:latest",
332        "OSFamily": "Linux",
333    },
334)
335 
336platform(
337    name = "remote_linux",
338    parents = [":linux_x86_64"],
339    exec_properties = {
340        "Pool": "default",
341        "dockerNetwork": "standard",
342    },
343)
344 
345# toolchains/BUILD.bazel
346toolchain(
347    name = "cc_toolchain_linux",
348    exec_compatible_with = [
349        "@platforms//os:linux",
350        "@platforms//cpu:x86_64",
351    ],
352    target_compatible_with = [
353        "@platforms//os:linux",
354        "@platforms//cpu:x86_64",
355    ],
356    toolchain = "@remotejdk11_linux//:jdk",
357    toolchain_type = "@bazel_tools//tools/jdk:runtime_toolchain_type",
358)
359```
360 
361## Performance Optimization
362 
363```bash
364# Profile build
365bazel build //... --profile=profile.json
366bazel analyze-profile profile.json
367 
368# Identify slow actions
369bazel build //... --execution_log_json_file=exec_log.json
370 
371# Memory profiling
372bazel build //... --memory_profile=memory.json
373 
374# Skip analysis cache
375bazel build //... --notrack_incremental_state
376```
377 
378## Best Practices
379 
380### Do's
381- **Use fine-grained targets** - Better caching
382- **Pin dependencies** - Reproducible builds
383- **Enable remote caching** - Share build artifacts
384- **Use visibility wisely** - Enforce architecture
385- **Write BUILD files per directory** - Standard convention
386 
387### Don'ts
388- **Don't use glob for deps** - Explicit is better
389- **Don't commit bazel-* dirs** - Add to .gitignore
390- **Don't skip WORKSPACE setup** - Foundation of build
391- **Don't ignore build warnings** - Technical debt
392 
393## Resources
394 
395- [Bazel Documentation](https://bazel.build/docs)
396- [Bazel Remote Execution](https://bazel.build/docs/remote-execution)
397- [rules_js](https://github.com/aspect-build/rules_js)
398