mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-21 09:33:35 +00:00
hanzoskills.com/llms.txt now opens with the install line, the API reference index and the company index, so an agent that lands on any one of the three can find the rest. robots.txt claimed 537 documents while llms.txt counts 920. The number is gone from robots.txt; llms.txt derives it. public/ is regenerated from scripts/site.py, which it had fallen behind: the copy-prompt menu and agent bar were in the generator and not in the committed pages. tests/site.mjs passes against the result. Co-authored-by: Hanzo Dev <[email protected]>
807 lines
33 KiB
HTML
807 lines
33 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>build-systems-bazel-monorepos</title>
|
|
<meta name="color-scheme" content="dark">
|
|
<style>
|
|
/* Committed to one visual world: a dark instrument panel. No light variant —
|
|
the dot field and the hairline rules only read on black, and a naive
|
|
inversion would wash both out. Every colour is painted explicitly so the page
|
|
never borrows a host background. */
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
|
|
|
:root{
|
|
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
|
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
|
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
|
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
|
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
|
--mono:var(--font-zen-mono);
|
|
--sans:var(--font-zen-sans);
|
|
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
|
--r:999px; --r-soft:14px;
|
|
}
|
|
*{box-sizing:border-box}
|
|
html{-webkit-text-size-adjust:100%}
|
|
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
|
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
|
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
|
|
|
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
|
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
|
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
|
would cut off the copy-prompt menu. */
|
|
.hero{position:relative;border-bottom:1px solid var(--line)}
|
|
.hero::before{content:"";position:absolute;inset:0;
|
|
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
|
background-size:7px 7px;
|
|
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
pointer-events:none}
|
|
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
|
|
|
nav{border-bottom:1px solid var(--line)}
|
|
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
|
justify-content:space-between;align-items:center;gap:1rem}
|
|
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
|
display:inline-flex;align-items:center;gap:.6rem}
|
|
.brand i{font-style:normal;color:var(--faint)}
|
|
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
|
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
|
nav a.up:hover{color:var(--ink)}
|
|
|
|
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
|
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
|
h1 em{font-style:normal;color:var(--faint)}
|
|
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
|
|
|
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
|
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
|
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
|
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
|
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
|
line-height:1.2;font-weight:400}
|
|
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
|
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
|
.btn.solid:hover{background:#d8d8d4}
|
|
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
|
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
|
|
|
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
|
.copy{position:relative;display:inline-flex}
|
|
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
|
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
|
padding:.4rem;display:flex;flex-direction:column;
|
|
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
|
.menu[hidden]{display:none}
|
|
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
|
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
|
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
|
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
|
white-space:nowrap}
|
|
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
|
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
|
.mi:hover .mark{color:var(--ink)}
|
|
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
|
letter-spacing:.1em;text-transform:uppercase}
|
|
|
|
/* Works-with bar: one scrolling row, name and mark per agent. */
|
|
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
|
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
|
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
|
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
|
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
|
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
|
display:flex;align-items:center}
|
|
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
|
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
|
-webkit-overflow-scrolling:touch;
|
|
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
|
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
|
.bar::-webkit-scrollbar{display:none}
|
|
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
|
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
|
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
|
text-decoration:none;background:var(--ground)}
|
|
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
|
.agent .mark{width:.95rem;height:.95rem}
|
|
|
|
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
|
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
|
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
|
p{margin:0 0 1rem;max-width:70ch}
|
|
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
|
li{margin:.22rem 0}
|
|
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
|
text-decoration-color:var(--line-hi)}
|
|
a:hover{text-decoration-color:var(--ink)}
|
|
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
|
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
|
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
|
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
|
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
|
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
|
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
|
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
|
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
|
display:block;overflow-x:auto}
|
|
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
|
|
|
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
|
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
|
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
|
white-space:pre;line-height:1.9}
|
|
.curl b{color:var(--ink);font-weight:400}
|
|
.curl i{font-style:normal;color:var(--faint)}
|
|
|
|
/* index */
|
|
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
|
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
|
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
|
#q:focus{outline:none;border-color:var(--soft)}
|
|
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
|
text-transform:uppercase;margin:0 0 2rem}
|
|
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
|
padding-bottom:.45rem}
|
|
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
|
border-radius:var(--r-soft);text-decoration:none}
|
|
.row:hover{background:#0a0a0a}
|
|
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
|
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
|
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
|
color:var(--faint);font-size:.85rem}
|
|
footer a{color:var(--soft)}
|
|
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
|
margin:0 0 2rem;font-size:.85rem}
|
|
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
|
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
|
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
|
.fmap a:hover{text-decoration:underline}
|
|
.fmap div{color:var(--faint);line-height:1.5}
|
|
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
|
|
|
@media (max-width:640px){
|
|
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
|
.btns{gap:.5rem}
|
|
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
|
.copy,.copy .btn{width:100%;justify-content:center}
|
|
.menu{left:0;right:0;min-width:0}
|
|
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
|
.strip b{border-right:0;padding-right:0}
|
|
.bar{width:100%}
|
|
}
|
|
</style>
|
|
<link rel="alternate" type="text/markdown" href="/build-systems-bazel-monorepos.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/build-systems-bazel-monorepos">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/build-systems-bazel-monorepos.md
|
|
Index: https://hanzoskills.com/llms.txt
|
|
Corpus: https://hanzoskills.com/all.md
|
|
Append .md to any path for the markdown twin. -->
|
|
<body>
|
|
<nav><div class="in">
|
|
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
|
<a class="up" href="/">All skills</a>
|
|
</div></nav>
|
|
|
|
<div class="wrap">
|
|
<h1>build-systems-bazel-monorepos</h1><p class="lede">Bazel BUILD files, WORKSPACE/MODULE.bazel, hermetic builds, remote caching, build rules, Starlark custom rules, and monorepo best practices for polyglot projects.</p><h1>Bazel Monorepos</h1>
|
|
<p><strong>Last Updated</strong>: 2025-10-26</p>
|
|
<h2>When to Use This Skill</h2>
|
|
<p>Use this skill when:</p>
|
|
<ul><li>Managing large-scale polyglot monorepos (multiple languages)</li><li>Requiring hermetic, reproducible builds</li><li>Needing fast incremental builds with remote caching</li><li>Building projects with complex dependency graphs</li><li>Targeting multiple platforms from single codebase</li><li>Working at Google-scale (Bazel powers Google's internal build)</li></ul>
|
|
<p><strong>Alternatives</strong>: Gradle (JVM), CMake (C/C++), Cargo (Rust), language-specific tools</p>
|
|
<p><strong>Prerequisites</strong>: Bazel 7.0+ installed (7.4.1 latest as of 2024), Bazelisk (version manager)</p>
|
|
<h2>Core Concepts</h2>
|
|
<h3>Bazel Philosophy</h3>
|
|
<pre><code>Hermetic: All dependencies explicit, no network during build
|
|
Incremental: Only rebuild what changed (fine-grained)
|
|
Parallel: Maximize parallelization across cores
|
|
Cacheable: Remote cache for team-wide sharing
|
|
Polyglot: Unified build for Java, C++, Python, Go, etc.</code></pre>
|
|
<h3>Bazelisk (Recommended)</h3>
|
|
<pre><code class="lang-bash"># Install Bazelisk (manages Bazel versions)
|
|
# macOS
|
|
brew install bazelisk
|
|
|
|
# Linux
|
|
wget https://github.com/bazelbuild/bazelisk/releases/latest/download/bazelisk-linux-amd64
|
|
chmod +x bazelisk-linux-amd64
|
|
sudo mv bazelisk-linux-amd64 /usr/local/bin/bazel
|
|
|
|
# Bazelisk reads .bazelversion for project-specific version
|
|
echo "7.4.1" > .bazelversion
|
|
|
|
# Use bazel command (Bazelisk transparently handles version)
|
|
bazel version</code></pre>
|
|
<h3>Project Structure</h3>
|
|
<pre><code>monorepo/
|
|
├── WORKSPACE.bazel # Workspace config (legacy)
|
|
├── MODULE.bazel # Module config (Bazel 6.0+, bzlmod)
|
|
├── .bazelversion # Bazel version (for Bazelisk)
|
|
├── .bazelrc # Build configuration
|
|
├── java/
|
|
│ ├── BUILD.bazel # Build rules for Java code
|
|
│ └── com/example/
|
|
│ └── Main.java
|
|
├── cpp/
|
|
│ ├── BUILD.bazel
|
|
│ └── lib.cc
|
|
├── python/
|
|
│ ├── BUILD.bazel
|
|
│ └── app.py
|
|
└── proto/
|
|
├── BUILD.bazel
|
|
└── service.proto</code></pre>
|
|
<h2>WORKSPACE and MODULE Files</h2>
|
|
<h3>WORKSPACE.bazel (Legacy)</h3>
|
|
<pre><code class="lang-python"># WORKSPACE.bazel - Legacy dependency management
|
|
workspace(name = "my_project")
|
|
|
|
# HTTP archive (external dependency)
|
|
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
|
|
|
|
http_archive(
|
|
name = "rules_java",
|
|
urls = ["https://github.com/bazelbuild/rules_java/archive/refs/tags/6.0.0.tar.gz"],
|
|
sha256 = "...",
|
|
)
|
|
|
|
http_archive(
|
|
name = "rules_python",
|
|
urls = ["https://github.com/bazelbuild/rules_python/releases/download/0.27.0/rules_python-0.27.0.tar.gz"],
|
|
sha256 = "...",
|
|
)
|
|
|
|
# Load rules
|
|
load("@rules_java//java:repositories.bzl", "rules_java_dependencies", "rules_java_toolchains")
|
|
rules_java_dependencies()
|
|
rules_java_toolchains()
|
|
|
|
load("@rules_python//python:repositories.bzl", "py_repositories")
|
|
py_repositories()</code></pre>
|
|
<h3>MODULE.bazel (Bzlmod, Bazel 6.0+)</h3>
|
|
<pre><code class="lang-python"># MODULE.bazel - Modern dependency management
|
|
module(
|
|
name = "my_project",
|
|
version = "1.0.0",
|
|
)
|
|
|
|
# Bazel Central Registry dependencies
|
|
bazel_dep(name = "rules_java", version = "6.0.0")
|
|
bazel_dep(name = "rules_python", version = "0.27.0")
|
|
bazel_dep(name = "rules_cc", version = "0.0.9")
|
|
bazel_dep(name = "protobuf", version = "24.4")
|
|
|
|
# Maven dependencies (Java)
|
|
maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")
|
|
maven.install(
|
|
artifacts = [
|
|
"com.google.guava:guava:32.1.3-jre",
|
|
"org.junit.jupiter:junit-jupiter:5.10.0",
|
|
],
|
|
repositories = [
|
|
"https://repo.maven.apache.org/maven2",
|
|
],
|
|
)
|
|
use_repo(maven, "maven")
|
|
|
|
# Python dependencies
|
|
pip = use_extension("@rules_python//python:extensions.bzl", "pip")
|
|
pip.parse(
|
|
hub_name = "pip",
|
|
python_version = "3.11",
|
|
requirements_lock = "//:requirements_lock.txt",
|
|
)
|
|
use_repo(pip, "pip")</code></pre>
|
|
<h2>BUILD Files</h2>
|
|
<h3>Java Build Rules</h3>
|
|
<pre><code class="lang-python"># java/BUILD.bazel
|
|
load("@rules_java//java:defs.bzl", "java_binary", "java_library", "java_test")
|
|
|
|
# Library
|
|
java_library(
|
|
name = "utils",
|
|
srcs = glob(["com/example/utils/*.java"]),
|
|
deps = [
|
|
"@maven//:com_google_guava_guava",
|
|
],
|
|
visibility = ["//visibility:public"],
|
|
)
|
|
|
|
# Binary (executable)
|
|
java_binary(
|
|
name = "app",
|
|
srcs = ["com/example/Main.java"],
|
|
main_class = "com.example.Main",
|
|
deps = [
|
|
":utils",
|
|
"//proto:service_java_proto",
|
|
],
|
|
)
|
|
|
|
# Test
|
|
java_test(
|
|
name = "utils_test",
|
|
srcs = glob(["com/example/utils/*Test.java"]),
|
|
test_class = "com.example.utils.UtilsTest",
|
|
deps = [
|
|
":utils",
|
|
"@maven//:org_junit_jupiter_junit_jupiter",
|
|
],
|
|
)</code></pre>
|
|
<h3>C++ Build Rules</h3>
|
|
<pre><code class="lang-python"># cpp/BUILD.bazel
|
|
load("@rules_cc//cc:defs.bzl", "cc_binary", "cc_library", "cc_test")
|
|
|
|
# Library
|
|
cc_library(
|
|
name = "mylib",
|
|
srcs = ["lib.cc"],
|
|
hdrs = ["lib.h"],
|
|
deps = [
|
|
"@com_google_absl//absl/strings",
|
|
],
|
|
visibility = ["//visibility:public"],
|
|
)
|
|
|
|
# Binary
|
|
cc_binary(
|
|
name = "app",
|
|
srcs = ["main.cc"],
|
|
deps = [":mylib"],
|
|
)
|
|
|
|
# Test
|
|
cc_test(
|
|
name = "mylib_test",
|
|
srcs = ["lib_test.cc"],
|
|
deps = [
|
|
":mylib",
|
|
"@com_google_googletest//:gtest_main",
|
|
],
|
|
)</code></pre>
|
|
<h3>Python Build Rules</h3>
|
|
<pre><code class="lang-python"># python/BUILD.bazel
|
|
load("@rules_python//python:defs.bzl", "py_binary", "py_library", "py_test")
|
|
|
|
# Library
|
|
py_library(
|
|
name = "utils",
|
|
srcs = ["utils.py"],
|
|
deps = [
|
|
"@pip//numpy",
|
|
],
|
|
visibility = ["//visibility:public"],
|
|
)
|
|
|
|
# Binary
|
|
py_binary(
|
|
name = "app",
|
|
srcs = ["app.py"],
|
|
main = "app.py",
|
|
deps = [
|
|
":utils",
|
|
"//proto:service_py_proto",
|
|
],
|
|
)
|
|
|
|
# Test
|
|
py_test(
|
|
name = "utils_test",
|
|
srcs = ["utils_test.py"],
|
|
deps = [
|
|
":utils",
|
|
"@pip//pytest",
|
|
],
|
|
)</code></pre>
|
|
<h3>Protobuf Build Rules</h3>
|
|
<pre><code class="lang-python"># proto/BUILD.bazel
|
|
load("@rules_proto//proto:defs.bzl", "proto_library")
|
|
load("@rules_java//java:defs.bzl", "java_proto_library")
|
|
load("@rules_python//python:proto.bzl", "py_proto_library")
|
|
|
|
# Proto definition
|
|
proto_library(
|
|
name = "service_proto",
|
|
srcs = ["service.proto"],
|
|
visibility = ["//visibility:public"],
|
|
)
|
|
|
|
# Java proto
|
|
java_proto_library(
|
|
name = "service_java_proto",
|
|
deps = [":service_proto"],
|
|
visibility = ["//visibility:public"],
|
|
)
|
|
|
|
# Python proto
|
|
py_proto_library(
|
|
name = "service_py_proto",
|
|
deps = [":service_proto"],
|
|
visibility = ["//visibility:public"],
|
|
)</code></pre>
|
|
<h2>Build Configuration</h2>
|
|
<h3>.bazelrc</h3>
|
|
<pre><code class="lang-bash"># .bazelrc - Build configuration
|
|
# Common flags
|
|
build --enable_platform_specific_config
|
|
build --incompatible_strict_action_env
|
|
build --verbose_failures
|
|
|
|
# Performance
|
|
build --jobs=8
|
|
build --local_ram_resources=HOST_RAM*.5
|
|
build --remote_cache=https://cache.example.com
|
|
|
|
# Output
|
|
build --show_timestamps
|
|
build --color=yes
|
|
|
|
# Java
|
|
build --java_runtime_version=remotejdk_11
|
|
build --tool_java_runtime_version=remotejdk_11
|
|
|
|
# C++
|
|
build:linux --cxxopt=-std=c++17
|
|
build:macos --cxxopt=-std=c++17
|
|
|
|
# Test
|
|
test --test_output=errors
|
|
test --test_summary=detailed
|
|
|
|
# Platform-specific (auto-selected)
|
|
build:linux --copt=-DLINUX
|
|
build:macos --copt=-DMACOS
|
|
build:windows --copt=/DWINDOWS</code></pre>
|
|
<h2>Remote Caching</h2>
|
|
<h3>Local Cache</h3>
|
|
<pre><code class="lang-bash"># Enable disk cache (default ~/.cache/bazel)
|
|
build --disk_cache=~/.cache/bazel</code></pre>
|
|
<h3>Remote Cache (HTTP)</h3>
|
|
<pre><code class="lang-bash"># .bazelrc
|
|
build --remote_cache=https://cache.example.com
|
|
build --remote_upload_local_results=true
|
|
|
|
# Or use Google Cloud Storage
|
|
build --remote_cache=https://storage.googleapis.com/my-bazel-cache
|
|
build --google_default_credentials</code></pre>
|
|
<h3>Remote Execution (Advanced)</h3>
|
|
<pre><code class="lang-bash"># Remote build execution (RBE)
|
|
build --remote_executor=grpcs://remotebuildexecution.googleapis.com
|
|
build --remote_instance_name=projects/my-project/instances/default_instance
|
|
build --google_default_credentials</code></pre>
|
|
<h2>Custom Rules (Starlark)</h2>
|
|
<h3>Simple Custom Rule</h3>
|
|
<pre><code class="lang-python"># rules/custom.bzl
|
|
def _my_rule_impl(ctx):
|
|
"""Implementation function for my_rule."""
|
|
# Access attributes
|
|
input_file = ctx.file.src
|
|
output_file = ctx.actions.declare_file(ctx.label.name + ".out")
|
|
|
|
# Run action
|
|
ctx.actions.run_shell(
|
|
inputs = [input_file],
|
|
outputs = [output_file],
|
|
command = "cat {} > {}".format(input_file.path, output_file.path),
|
|
)
|
|
|
|
# Return provider
|
|
return [DefaultInfo(files = depset([output_file]))]
|
|
|
|
# Define rule
|
|
my_rule = rule(
|
|
implementation = _my_rule_impl,
|
|
attrs = {
|
|
"src": attr.label(allow_single_file = True, mandatory = True),
|
|
},
|
|
)</code></pre>
|
|
<pre><code class="lang-python"># BUILD.bazel - Use custom rule
|
|
load("//rules:custom.bzl", "my_rule")
|
|
|
|
my_rule(
|
|
name = "processed",
|
|
src = "input.txt",
|
|
)</code></pre>
|
|
<h3>Advanced Custom Rule</h3>
|
|
<pre><code class="lang-python"># rules/code_gen.bzl
|
|
def _code_gen_impl(ctx):
|
|
"""Generate code from template."""
|
|
template = ctx.file.template
|
|
output = ctx.actions.declare_file(ctx.attr.output_name)
|
|
|
|
# Run Python script
|
|
ctx.actions.run(
|
|
executable = ctx.executable._generator,
|
|
arguments = [
|
|
"--template", template.path,
|
|
"--output", output.path,
|
|
"--config", ctx.attr.config,
|
|
],
|
|
inputs = [template],
|
|
outputs = [output],
|
|
mnemonic = "CodeGen",
|
|
progress_message = "Generating code from {}".format(template.short_path),
|
|
)
|
|
|
|
return [DefaultInfo(files = depset([output]))]
|
|
|
|
code_gen = rule(
|
|
implementation = _code_gen_impl,
|
|
attrs = {
|
|
"template": attr.label(allow_single_file = [".tpl"], mandatory = True),
|
|
"output_name": attr.string(mandatory = True),
|
|
"config": attr.string(default = "default"),
|
|
"_generator": attr.label(
|
|
default = Label("//tools:generator"),
|
|
executable = True,
|
|
cfg = "exec",
|
|
),
|
|
},
|
|
)</code></pre>
|
|
<h2>Monorepo Best Practices</h2>
|
|
<h3>Visibility Control</h3>
|
|
<pre><code class="lang-python"># Restrict visibility
|
|
java_library(
|
|
name = "internal_utils",
|
|
srcs = ["Utils.java"],
|
|
visibility = ["//java:__subpackages__"], # Only java/ subtree
|
|
)
|
|
|
|
# Public visibility
|
|
java_library(
|
|
name = "public_api",
|
|
srcs = ["Api.java"],
|
|
visibility = ["//visibility:public"], # Entire workspace
|
|
)
|
|
|
|
# Package group
|
|
package_group(
|
|
name = "backend_team",
|
|
packages = [
|
|
"//backend/...",
|
|
"//common/...",
|
|
],
|
|
)
|
|
|
|
java_library(
|
|
name = "backend_lib",
|
|
srcs = ["BackendLib.java"],
|
|
visibility = [":backend_team"],
|
|
)</code></pre>
|
|
<h3>Glob Patterns</h3>
|
|
<pre><code class="lang-python"># Glob source files
|
|
java_library(
|
|
name = "lib",
|
|
srcs = glob(["src/**/*.java"]),
|
|
resources = glob(["resources/**/*"]),
|
|
)
|
|
|
|
# Exclude patterns
|
|
java_library(
|
|
name = "lib",
|
|
srcs = glob(
|
|
["**/*.java"],
|
|
exclude = ["**/*Test.java", "**/testdata/**"],
|
|
),
|
|
)</code></pre>
|
|
<h3>Macros for Reusability</h3>
|
|
<pre><code class="lang-python"># macros/java.bzl
|
|
def java_module(name, srcs, deps = [], **kwargs):
|
|
"""Standard Java module with library and test."""
|
|
native.java_library(
|
|
name = name,
|
|
srcs = srcs,
|
|
deps = deps,
|
|
**kwargs
|
|
)
|
|
|
|
native.java_test(
|
|
name = name + "_test",
|
|
srcs = native.glob([name + "/**/*Test.java"]),
|
|
deps = [
|
|
":" + name,
|
|
"@maven//:org_junit_jupiter_junit_jupiter",
|
|
] + deps,
|
|
**kwargs
|
|
)</code></pre>
|
|
<pre><code class="lang-python"># BUILD.bazel
|
|
load("//macros:java.bzl", "java_module")
|
|
|
|
java_module(
|
|
name = "utils",
|
|
srcs = glob(["utils/**/*.java"]),
|
|
deps = ["@maven//:com_google_guava_guava"],
|
|
)</code></pre>
|
|
<h2>Performance Optimization</h2>
|
|
<h3>Query Dependencies</h3>
|
|
<pre><code class="lang-bash"># Show dependency graph
|
|
bazel query --output=graph //java/... > graph.dot
|
|
|
|
# Find dependencies
|
|
bazel query "deps(//java:app)"
|
|
|
|
# Reverse dependencies (what depends on X)
|
|
bazel query "rdeps(//..., //java:utils)"
|
|
|
|
# Find test targets
|
|
bazel query "tests(//java/...)"</code></pre>
|
|
<h3>Build Analysis</h3>
|
|
<pre><code class="lang-bash"># Profile build
|
|
bazel build //java:app --profile=profile.json
|
|
|
|
# View profile
|
|
bazel analyze-profile profile.json
|
|
|
|
# Show action timing
|
|
bazel build //java:app --experimental_show_artifacts --experimental_profile_cpu_usage</code></pre>
|
|
<h3>Incremental Builds</h3>
|
|
<pre><code class="lang-bash"># Bazel automatically detects changes
|
|
# Only rebuilds affected targets
|
|
|
|
# Force rebuild
|
|
bazel clean
|
|
bazel build //...
|
|
|
|
# Or specific target
|
|
bazel clean --expunge # Nuclear option (clears all caches)</code></pre>
|
|
<h2>Anti-Patterns</h2>
|
|
<h3>❌ Not Using Hermetic Builds</h3>
|
|
<pre><code class="lang-python"># WRONG: External system dependency
|
|
genrule(
|
|
name = "bad",
|
|
outs = ["output.txt"],
|
|
cmd = "curl https://example.com/data > $@", # Network access!
|
|
)
|
|
|
|
# CORRECT: Explicit dependency
|
|
http_file(
|
|
name = "data",
|
|
urls = ["https://example.com/data"],
|
|
sha256 = "...",
|
|
)
|
|
|
|
genrule(
|
|
name = "good",
|
|
srcs = ["@data//file"],
|
|
outs = ["output.txt"],
|
|
cmd = "cp $< $@",
|
|
)</code></pre>
|
|
<h3>❌ Overly Broad Globs</h3>
|
|
<pre><code class="lang-python"># WRONG: Too broad, includes unintended files
|
|
srcs = glob(["**/*.java"])
|
|
|
|
# CORRECT: Specific patterns
|
|
srcs = glob(
|
|
["src/**/*.java"],
|
|
exclude = [
|
|
"**/*Test.java",
|
|
"**/testdata/**",
|
|
"**/generated/**",
|
|
],
|
|
)</code></pre>
|
|
<h3>❌ Not Pinning Versions</h3>
|
|
<pre><code class="lang-python"># WRONG: Unpinned version (non-reproducible)
|
|
http_archive(
|
|
name = "rules_java",
|
|
urls = ["https://github.com/bazelbuild/rules_java/archive/refs/heads/main.zip"],
|
|
)
|
|
|
|
# CORRECT: Pinned version with SHA
|
|
http_archive(
|
|
name = "rules_java",
|
|
urls = ["https://github.com/bazelbuild/rules_java/archive/refs/tags/6.0.0.tar.gz"],
|
|
sha256 = "469b7f3b580b4fcf8112f4d6eb3e3d8239ef05f68a33e2c3c4f23d3a4e286994",
|
|
)</code></pre>
|
|
<h2>Quick Reference</h2>
|
|
<h3>Essential Bazel Commands</h3>
|
|
<pre><code class="lang-bash"># Build
|
|
bazel build //java:app # Build target
|
|
bazel build //java/... # Build all in java/
|
|
bazel build //... # Build entire workspace
|
|
|
|
# Test
|
|
bazel test //java:app_test # Run single test
|
|
bazel test //java/... # Run all tests in java/
|
|
bazel test //... --test_output=all # Verbose test output
|
|
|
|
# Run
|
|
bazel run //java:app # Build and run binary
|
|
|
|
# Clean
|
|
bazel clean # Clean build outputs
|
|
bazel clean --expunge # Nuclear clean (all caches)
|
|
|
|
# Query
|
|
bazel query //java/... # List targets
|
|
bazel query "deps(//java:app)" # Show dependencies
|
|
bazel query "rdeps(//..., //java:lib)" # Reverse dependencies
|
|
|
|
# Info
|
|
bazel info # Show workspace info
|
|
bazel version # Bazel version</code></pre>
|
|
<h3>Target Labels</h3>
|
|
<pre><code>//package:target # Absolute label
|
|
//package # Short form (target = package name)
|
|
:target # Relative to current package
|
|
//... # All targets in workspace
|
|
//package/... # All targets under package/
|
|
@repo//package:target # External repository</code></pre>
|
|
<h2>Bazel vs Gradle Performance (2024 Data)</h2>
|
|
<p><strong>Build Performance</strong> (Google internal data, 2024):</p>
|
|
<ul><li><strong>Cold build</strong>: Bazel ~15% slower (hermetic sandboxing overhead)</li><li><strong>Incremental build</strong>: Bazel 3-5x faster (fine-grained caching)</li><li><strong>Multi-language</strong>: Bazel scales better (unified graph)</li><li><strong>Remote cache</strong>: Bazel superior (built-in, action-level granularity)</li></ul>
|
|
<p><strong>When Bazel Excels</strong>:</p>
|
|
<ul><li>Large monorepos (>100k files)</li><li>Polyglot projects (Java + C++ + Python)</li><li>Multiple teams sharing cache</li><li>Strict reproducibility requirements</li></ul>
|
|
<p><strong>When Gradle Excels</strong>:</p>
|
|
<ul><li>Pure JVM projects</li><li>Smaller codebases (<50k files)</li><li>Flexible build logic needed</li><li>Android development (Gradle is default)</li></ul>
|
|
<h2>Python Integration Example</h2>
|
|
<pre><code class="lang-python"># tools/generator.py - Custom code generator
|
|
import argparse
|
|
|
|
def generate(template_path, output_path, config):
|
|
with open(template_path) as f:
|
|
template = f.read()
|
|
|
|
# Process template (simplified)
|
|
code = template.replace("{{CONFIG}}", config)
|
|
|
|
with open(output_path, 'w') as f:
|
|
f.write(code)
|
|
|
|
if __name__ == "__main__":
|
|
parser = argparse.ArgumentParser()
|
|
parser.add_argument("--template", required=True)
|
|
parser.add_argument("--output", required=True)
|
|
parser.add_argument("--config", default="default")
|
|
args = parser.parse_args()
|
|
|
|
generate(args.template, args.output, args.config)</code></pre>
|
|
<pre><code class="lang-python"># tools/BUILD.bazel
|
|
py_binary(
|
|
name = "generator",
|
|
srcs = ["generator.py"],
|
|
visibility = ["//visibility:public"],
|
|
)</code></pre>
|
|
<h2>Related Skills</h2>
|
|
<ul><li><code>build-system-selection.md</code> - Choosing between build systems</li><li><code>gradle-jvm-builds.md</code> - Alternative for JVM projects</li><li><code>cmake-patterns.md</code> - Alternative for C/C++ projects</li><li><code>build-optimization.md</code> - Caching and performance</li><li><code>cicd/ci-optimization.md</code> - Bazel in CI pipelines</li></ul>
|
|
<h2>Summary</h2>
|
|
<p>Bazel is Google's open-source build system designed for massive monorepos with hermetic, reproducible builds:</p>
|
|
<p><strong>Key Takeaways</strong>:</p>
|
|
<ol><li><strong>Hermetic builds</strong> - All dependencies explicit, no network during build</li><li><strong>Fine-grained caching</strong> - Action-level caching for fast incremental builds</li><li><strong>Remote cache/execution</strong> - Share build artifacts across team/CI</li><li><strong>Polyglot support</strong> - Unified build for Java, C++, Python, Go, etc.</li><li><strong>Bzlmod</strong> - Modern dependency management (Bazel 6.0+)</li><li><strong>Starlark rules</strong> - Extend Bazel with custom build logic</li><li><strong>Visibility control</strong> - Enforce module boundaries</li><li><strong>Incremental by default</strong> - Only rebuild what changed</li></ol>
|
|
<p><strong>When to Choose Bazel</strong>:</p>
|
|
<ul><li>Large monorepos (Google, Uber, LinkedIn scale)</li><li>Multiple languages in single codebase</li><li>Strict reproducibility requirements</li><li>Need for remote caching/execution</li></ul>
|
|
<p><strong>When to Choose Alternatives</strong>:</p>
|
|
<ul><li>Small projects (setup overhead not justified)</li><li>Pure JVM (Gradle simpler)</li><li>Pure C/C++ (CMake more familiar)</li><li>Rapid prototyping (Bazel has learning curve)</li></ul>
|
|
<p>Bazel excels at scale but requires investment in learning and setup. For projects expecting to grow to Google-scale complexity, the investment pays off.</p>
|
|
<footer>
|
|
<div class="fmap">
|
|
<div><b>Build</b>
|
|
<a href="https://hanzo.app">hanzo.app</a> app builder
|
|
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
|
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
|
<div><b>Run</b>
|
|
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
|
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
|
<div><b>Account</b>
|
|
<a href="https://hanzo.id">hanzo.id</a> sign in
|
|
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
|
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
|
<div><b>Company</b>
|
|
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
|
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
|
</div>
|
|
<div class="fend"><a href="/build-systems-bazel-monorepos.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |