mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +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]>
546 lines
31 KiB
HTML
546 lines
31 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-build-system-selection</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-build-system-selection.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/build-systems-build-system-selection">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/build-systems-build-system-selection.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-build-system-selection</h1><p class="lede">Decision matrix for choosing between Make, CMake, Gradle, Maven, Bazel, and other build systems based on project requirements, language, and scale.</p><h1>Build System Selection</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>Starting a new project and choosing build system</li><li>Migrating from one build system to another</li><li>Evaluating build system trade-offs for team/project</li><li>Deciding between language-native vs polyglot build tools</li><li>Assessing monorepo vs polyrepo build strategies</li></ul>
|
|
<p><strong>Prerequisites</strong>: Understanding of project requirements, language ecosystem, team size</p>
|
|
<h2>Decision Framework</h2>
|
|
<h3>Quick Decision Tree</h3>
|
|
<pre><code>What language(s)?
|
|
├─ Pure C/C++
|
|
│ ├─ Simple project → Make
|
|
│ ├─ Cross-platform → CMake
|
|
│ └─ Monorepo/Google-scale → Bazel
|
|
├─ Pure Java/Kotlin
|
|
│ ├─ Convention over configuration → Maven
|
|
│ ├─ Flexibility/performance → Gradle
|
|
│ └─ Monorepo → Bazel
|
|
├─ Pure Rust → Cargo (no alternatives)
|
|
├─ Pure Go → go build (no alternatives)
|
|
├─ Pure Python → uv, pip-tools, Poetry
|
|
├─ Pure JavaScript/TypeScript → npm, pnpm, Bun
|
|
├─ Polyglot (multiple languages)
|
|
│ ├─ <50k files → Language-specific tools + orchestration
|
|
│ └─ >50k files → Bazel or Pants
|
|
└─ Monorepo (many projects)
|
|
├─ Pure JVM → Gradle multi-project
|
|
└─ Mixed languages → Bazel</code></pre>
|
|
<h2>Build System Comparison Matrix</h2>
|
|
<h3>Feature Matrix</h3>
|
|
<p>| Feature | Make | CMake | Maven | Gradle | Bazel | Cargo | Go | |---------|------|-------|-------|--------|-------|-------|------| | <strong>Languages</strong> | Any | C/C++ | JVM | JVM+ | Any | Rust | Go | | <strong>Learning Curve</strong> | Medium | Steep | Low | Medium | Steep | Low | Low | | <strong>Performance</strong> | Good | Good | Slow | Fast | Fastest | Fast | Fast | | <strong>Incremental</strong> | Good | Good | Good | Excellent | Excellent | Excellent | Excellent | | <strong>Caching</strong> | Basic | Basic | Local | Local+Remote | Remote | Local | Local | | <strong>Cross-platform</strong> | Manual | Excellent | Excellent | Excellent | Excellent | Excellent | Excellent | | <strong>IDE Support</strong> | Basic | Excellent | Excellent | Excellent | Good | Excellent | Excellent | | <strong>Dependency Mgmt</strong> | Manual | Manual | Excellent | Excellent | Excellent | Excellent | Excellent | | <strong>Monorepo</strong> | Poor | Medium | Good | Good | Excellent | N/A | N/A | | <strong>Ecosystem</strong> | Mature | Mature | Mature | Growing | Growing | Growing | Mature |</p>
|
|
<h3>Performance Benchmarks (2024 Data)</h3>
|
|
<p><strong>Clean Build</strong> (medium project, ~10k files):</p>
|
|
<ul><li>Make: ~60s</li><li>CMake+Ninja: ~50s</li><li>Maven: ~120s</li><li>Gradle: ~90s (cold), ~30s (warm daemon)</li><li>Bazel: ~100s (hermetic overhead)</li><li>Cargo: ~40s</li><li>Go: ~20s</li></ul>
|
|
<p><strong>Incremental Build</strong> (1% file change):</p>
|
|
<ul><li>Make: ~5s</li><li>CMake+Ninja: ~4s</li><li>Maven: ~30s</li><li>Gradle: ~3s</li><li>Bazel: ~2s</li><li>Cargo: ~2s</li><li>Go: ~1s</li></ul>
|
|
<p><strong>Note</strong>: Bazel with remote cache: ~0.5s (cache hit)</p>
|
|
<h2>Language-Specific Recommendations</h2>
|
|
<h3>C/C++ Projects</h3>
|
|
<pre><code>Project Type → Recommendation
|
|
─────────────────────────────────────
|
|
Simple CLI tool → Make
|
|
Cross-platform lib → CMake
|
|
Large monorepo → Bazel
|
|
Game engine → CMake + custom scripts
|
|
Embedded → CMake with toolchains</code></pre>
|
|
<p><strong>Make</strong>:</p>
|
|
<ul><li>✅ Ubiquitous, minimal dependencies</li><li>✅ Fast for small projects</li><li>❌ Poor cross-platform support</li><li>❌ Manual dependency tracking</li></ul>
|
|
<p><strong>CMake</strong>:</p>
|
|
<ul><li>✅ Excellent cross-platform</li><li>✅ Rich ecosystem (find_package)</li><li>✅ IDE integration (Visual Studio, Xcode)</li><li>❌ Steep learning curve</li><li>❌ Verbose configuration</li></ul>
|
|
<p><strong>Bazel</strong>:</p>
|
|
<ul><li>✅ Hermetic builds</li><li>✅ Remote caching</li><li>✅ Polyglot support</li><li>❌ Steep learning curve</li><li>❌ Setup overhead for small projects</li></ul>
|
|
<p><strong>Example: CMake for Cross-Platform C++ Library</strong></p>
|
|
<pre><code class="lang-cmake">cmake_minimum_required(VERSION 3.20)
|
|
project(MyLib VERSION 1.0.0)
|
|
|
|
add_library(mylib src/lib.cpp)
|
|
target_include_directories(mylib PUBLIC include)
|
|
|
|
# Works on Windows, macOS, Linux
|
|
install(TARGETS mylib DESTINATION lib)</code></pre>
|
|
<h3>JVM Projects (Java, Kotlin, Scala)</h3>
|
|
<pre><code>Project Type → Recommendation
|
|
─────────────────────────────────────
|
|
Spring Boot app → Maven or Gradle
|
|
Android app → Gradle (only option)
|
|
Microservices → Maven (standardization)
|
|
Multi-module lib → Gradle (performance)
|
|
Large monorepo → Bazel</code></pre>
|
|
<p><strong>Maven</strong>:</p>
|
|
<ul><li>✅ Convention over configuration</li><li>✅ Mature, stable, well-documented</li><li>✅ Excellent IDE support</li><li>✅ Central repository ecosystem</li><li>❌ Slower than Gradle</li><li>❌ XML verbosity</li><li>❌ Limited flexibility</li></ul>
|
|
<p><strong>Gradle</strong>:</p>
|
|
<ul><li>✅ Faster than Maven (2-3x with cache)</li><li>✅ Flexible (Kotlin DSL)</li><li>✅ Better multi-module support</li><li>✅ Android default</li><li>❌ Steeper learning curve</li><li>❌ More complex than Maven</li><li>❌ Configuration can be inconsistent</li></ul>
|
|
<p><strong>Bazel</strong>:</p>
|
|
<ul><li>✅ Best for large monorepos</li><li>✅ Remote caching</li><li>✅ Polyglot (Java + C++ + Python)</li><li>❌ Steep learning curve</li><li>❌ Less JVM-specific tooling than Maven/Gradle</li></ul>
|
|
<p><strong>Example: Maven for Spring Boot</strong></p>
|
|
<pre><code class="lang-xml"><parent>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-starter-parent</artifactId>
|
|
<version>3.2.0</version>
|
|
</parent>
|
|
|
|
<!-- Convention: no plugin config needed -->
|
|
<build>
|
|
<plugins>
|
|
<plugin>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-maven-plugin</artifactId>
|
|
</plugin>
|
|
</plugins>
|
|
</build></code></pre>
|
|
<p><strong>Example: Gradle for Multi-Module</strong></p>
|
|
<pre><code class="lang-kotlin">// settings.gradle.kts
|
|
include("core", "api", "app")
|
|
|
|
// Fast incremental builds, parallel execution
|
|
// ./gradlew build --parallel</code></pre>
|
|
<h3>Rust Projects</h3>
|
|
<pre><code>Cargo is the ONLY choice
|
|
- Integrated with rustc
|
|
- Excellent dependency management (crates.io)
|
|
- Fast incremental builds
|
|
- No alternative needed</code></pre>
|
|
<pre><code class="lang-toml"># Cargo.toml
|
|
[package]
|
|
name = "myapp"
|
|
version = "0.1.0"
|
|
|
|
[dependencies]
|
|
serde = "1.0"
|
|
tokio = { version = "1.35", features = ["full"] }</code></pre>
|
|
<h3>Go Projects</h3>
|
|
<pre><code>go build is the standard
|
|
- Built into Go toolchain
|
|
- Zero configuration for simple projects
|
|
- Fast compilation
|
|
- Minimal alternatives (Bazel for large monorepos)</code></pre>
|
|
<pre><code class="lang-go">// go.mod
|
|
module github.com/user/project
|
|
|
|
go 1.21
|
|
|
|
require (
|
|
github.com/gorilla/mux v1.8.1
|
|
)</code></pre>
|
|
<h3>Python Projects</h3>
|
|
<pre><code>Project Type → Recommendation
|
|
─────────────────────────────────────
|
|
Modern app/lib → uv (fastest, 2024)
|
|
Legacy project → pip + requirements.txt
|
|
Library → Poetry or uv
|
|
Monorepo → Bazel or Pants</code></pre>
|
|
<p><strong>uv</strong> (Recommended, 2024):</p>
|
|
<ul><li>✅ 10-100x faster than pip</li><li>✅ Rust-based (rye successor)</li><li>✅ Modern resolver</li><li>✅ Lock files</li></ul>
|
|
<p><strong>Poetry</strong>:</p>
|
|
<ul><li>✅ Good dependency management</li><li>✅ Mature ecosystem</li><li>❌ Slower than uv</li><li>❌ Lock file conflicts</li></ul>
|
|
<p><strong>pip-tools</strong>:</p>
|
|
<ul><li>✅ Simple, minimal</li><li>✅ Reproducible builds</li><li>❌ Manual workflow</li></ul>
|
|
<h3>JavaScript/TypeScript Projects</h3>
|
|
<pre><code>Package Manager → Recommendation
|
|
─────────────────────────────────────
|
|
New project → pnpm or Bun (fast)
|
|
Legacy → npm
|
|
Monorepo → pnpm workspaces or Turborepo</code></pre>
|
|
<p><strong>pnpm</strong>:</p>
|
|
<ul><li>✅ Faster than npm (3x)</li><li>✅ Efficient disk usage</li><li>✅ Workspace support</li></ul>
|
|
<p><strong>Bun</strong>:</p>
|
|
<ul><li>✅ Fastest (Zig-based)</li><li>✅ Drop-in npm replacement</li><li>❌ Less mature ecosystem</li></ul>
|
|
<p><strong>npm</strong>:</p>
|
|
<ul><li>✅ Default, ubiquitous</li><li>✅ Stable</li><li>❌ Slower than alternatives</li></ul>
|
|
<h2>Monorepo vs Polyrepo</h2>
|
|
<h3>Monorepo Build Systems</h3>
|
|
<pre><code>Scale → Recommendation
|
|
─────────────────────────────────────
|
|
Small (<10 projects) → Language-native + Makefiles
|
|
Medium (10-50 projects) → Gradle/Maven multi-module
|
|
Large (50-200 projects) → Bazel or Pants
|
|
Google-scale (>200 projects) → Bazel</code></pre>
|
|
<p><strong>Bazel</strong>:</p>
|
|
<ul><li>✅ Built for monorepos</li><li>✅ Hermetic, reproducible</li><li>✅ Remote caching/execution</li><li>✅ Polyglot</li><li>❌ Steep learning curve</li><li>❌ Requires migration effort</li></ul>
|
|
<p><strong>Gradle Multi-Project</strong>:</p>
|
|
<ul><li>✅ Good JVM monorepo support</li><li>✅ Familiar to Java/Kotlin teams</li><li>✅ Gradle wrapper ensures consistency</li><li>❌ Less efficient than Bazel at scale</li><li>❌ JVM-centric</li></ul>
|
|
<p><strong>Pants</strong> (Alternative to Bazel):</p>
|
|
<ul><li>✅ Python-first</li><li>✅ Simpler than Bazel</li><li>✅ Remote caching</li><li>❌ Smaller community than Bazel</li></ul>
|
|
<h3>Polyrepo Build Systems</h3>
|
|
<pre><code>Use language-native tools:
|
|
- C/C++: CMake or Make
|
|
- Java: Maven or Gradle
|
|
- Rust: Cargo
|
|
- Go: go build
|
|
- Python: uv
|
|
- JS/TS: pnpm
|
|
|
|
Orchestrate with CI (GitHub Actions, GitLab CI)</code></pre>
|
|
<h2>Migration Strategies</h2>
|
|
<h3>Make → CMake</h3>
|
|
<p><strong>Rationale</strong>: Cross-platform support, better dependency management</p>
|
|
<pre><code class="lang-bash"># Before (Makefile)
|
|
gcc -o myapp main.c utils.c -I./include
|
|
|
|
# After (CMakeLists.txt)
|
|
add_executable(myapp main.c utils.c)
|
|
target_include_directories(myapp PRIVATE include)</code></pre>
|
|
<p><strong>Migration Steps</strong>:</p>
|
|
<ol><li>Create CMakeLists.txt with equivalent targets</li><li>Test on primary platform</li><li>Verify cross-platform builds</li><li>Migrate toolchain flags to target properties</li><li>Remove Makefile</li></ol>
|
|
<h3>Maven → Gradle</h3>
|
|
<p><strong>Rationale</strong>: Performance, multi-module flexibility</p>
|
|
<p><strong>Migration Tool</strong>:</p>
|
|
<pre><code class="lang-bash"># Gradle provides migration tool
|
|
gradle init # Converts existing Maven project</code></pre>
|
|
<p><strong>Manual Migration</strong>:</p>
|
|
<ol><li>Convert pom.xml to build.gradle.kts</li><li>Update dependency declarations</li><li>Migrate plugins</li><li>Test build lifecycle equivalence</li><li>Verify CI pipeline compatibility</li></ol>
|
|
<h3>Gradle/Maven → Bazel</h3>
|
|
<p><strong>Rationale</strong>: Monorepo scale, hermetic builds</p>
|
|
<p><strong>Migration Steps</strong>:</p>
|
|
<ol><li>Start with leaf modules (no dependencies)</li><li>Create BUILD files incrementally</li><li>Use rules_jvm_external for Maven dependencies</li><li>Migrate tests</li><li>Hybrid build during transition (Bazel + Gradle)</li><li>Full cutover after validation</li></ol>
|
|
<p><strong>Tools</strong>:</p>
|
|
<ul><li><code>rules_jvm_external</code> for Maven deps</li><li><code>migration-tooling</code> (Bazel repo)</li></ul>
|
|
<h2>Decision Checklist</h2>
|
|
<h3>Before Choosing Build System</h3>
|
|
<pre><code>[ ] What languages? (Pure vs polyglot)
|
|
[ ] Project size? (<1k, 1-10k, 10-100k, >100k files)
|
|
[ ] Team size? (1-5, 5-20, 20-100, >100)
|
|
[ ] Monorepo or polyrepo?
|
|
[ ] Cross-platform requirements?
|
|
[ ] Performance critical? (CI time budget?)
|
|
[ ] Remote caching needed?
|
|
[ ] Existing expertise on team?
|
|
[ ] Migration cost vs benefit?
|
|
[ ] IDE support requirements?
|
|
[ ] Open source or proprietary?</code></pre>
|
|
<h3>Red Flags</h3>
|
|
<pre><code>❌ Using Make for cross-platform C++ library
|
|
→ Use CMake
|
|
|
|
❌ Using Bazel for 5-person team, single language
|
|
→ Use language-native tool
|
|
|
|
❌ Using Maven for Android
|
|
→ Use Gradle (only option)
|
|
|
|
❌ Using custom scripts for polyglot monorepo
|
|
→ Use Bazel
|
|
|
|
❌ Using npm for large monorepo (>50 packages)
|
|
→ Use pnpm workspaces or Bazel</code></pre>
|
|
<h2>Build System Evolution Path</h2>
|
|
<h3>Small Project → Medium → Large</h3>
|
|
<pre><code>Phase 1: Small (1-5 developers, <1k files)
|
|
→ Language-native tools (Cargo, go build, npm)
|
|
→ Simple Makefiles for C/C++
|
|
|
|
Phase 2: Medium (5-20 developers, 1-10k files)
|
|
→ CMake for C/C++
|
|
→ Gradle or Maven for JVM
|
|
→ Monorepo with multi-module builds
|
|
|
|
Phase 3: Large (20-100 developers, 10-100k files)
|
|
→ Bazel for polyglot monorepo
|
|
→ Remote caching for CI acceleration
|
|
→ Hermetic builds for reproducibility
|
|
|
|
Phase 4: Google-scale (>100 developers, >100k files)
|
|
→ Bazel with remote execution
|
|
→ Build infrastructure team
|
|
→ Custom rules and optimizations</code></pre>
|
|
<h2>Anti-Patterns</h2>
|
|
<h3>❌ Premature Bazel Adoption</h3>
|
|
<pre><code>WRONG: 3-person team, 500 files, pure Java
|
|
→ Use Bazel (overkill, months of setup)
|
|
|
|
CORRECT: 3-person team, 500 files, pure Java
|
|
→ Use Maven (days of setup, team expertise)</code></pre>
|
|
<h3>❌ Language Mismatch</h3>
|
|
<pre><code>WRONG: Pure Rust project
|
|
→ Use CMake (fighting ecosystem)
|
|
|
|
CORRECT: Pure Rust project
|
|
→ Use Cargo (designed for Rust)</code></pre>
|
|
<h3>❌ Build System Fragmentation</h3>
|
|
<pre><code>WRONG: Monorepo with 10 different build systems
|
|
→ Each team uses own tool
|
|
→ Integration nightmare
|
|
|
|
CORRECT: Monorepo with unified build
|
|
→ Bazel or Gradle multi-project
|
|
→ Consistent builds across teams</code></pre>
|
|
<h3>❌ Not Using Build Cache</h3>
|
|
<pre><code>WRONG: CI rebuilds everything every time
|
|
→ 30-minute builds
|
|
|
|
CORRECT: Enable build cache (Gradle, Bazel)
|
|
→ 5-minute incremental builds</code></pre>
|
|
<h2>Quick Reference</h2>
|
|
<h3>Build System Selection Table</h3>
|
|
<p>| Project Profile | Recommended Build System | Runner-Up | |----------------|-------------------------|-----------| | C++ cross-platform lib | CMake | Bazel | | Java microservices | Maven | Gradle | | Kotlin Android app | Gradle | N/A | | Rust CLI tool | Cargo | N/A | | Go web service | go build | N/A | | Python app | uv | Poetry | | TypeScript React app | pnpm | Bun | | Polyglot monorepo | Bazel | Pants | | 100+ module Java monorepo | Bazel | Gradle | | Legacy C project | Make | CMake |</p>
|
|
<h3>Build System Strengths Summary</h3>
|
|
<p><strong>Make</strong>: Ubiquitous, minimal, fast for small C/C++ projects <strong>CMake</strong>: Cross-platform C/C++, excellent IDE support <strong>Maven</strong>: Standardized JVM builds, convention over configuration <strong>Gradle</strong>: Flexible JVM builds, fast incremental, Android <strong>Bazel</strong>: Large monorepos, hermetic, polyglot, remote cache <strong>Cargo</strong>: Rust builds, integrated ecosystem <strong>go build</strong>: Go builds, zero config <strong>uv</strong>: Python deps, fast, modern <strong>pnpm</strong>: JavaScript monorepos, efficient</p>
|
|
<h2>Python Integration Example</h2>
|
|
<pre><code class="lang-python"># build_selector.py - Choose build system based on project analysis
|
|
import os
|
|
import json
|
|
|
|
def analyze_project():
|
|
"""Analyze project to recommend build system."""
|
|
languages = set()
|
|
|
|
# Detect languages
|
|
for root, dirs, files in os.walk('.'):
|
|
for file in files:
|
|
if file.endswith('.java'):
|
|
languages.add('java')
|
|
elif file.endswith('.cpp') or file.endswith('.h'):
|
|
languages.add('cpp')
|
|
elif file.endswith('.py'):
|
|
languages.add('python')
|
|
elif file.endswith('.rs'):
|
|
languages.add('rust')
|
|
|
|
# Count files
|
|
file_count = sum(len(files) for _, _, files in os.walk('.'))
|
|
|
|
# Recommend
|
|
if len(languages) == 1:
|
|
lang = list(languages)[0]
|
|
if lang == 'rust':
|
|
return 'Cargo'
|
|
elif lang == 'python':
|
|
return 'uv'
|
|
elif lang == 'java':
|
|
return 'Maven' if file_count < 10000 else 'Gradle'
|
|
elif lang == 'cpp':
|
|
return 'CMake'
|
|
elif len(languages) > 1:
|
|
return 'Bazel' if file_count > 10000 else 'Language-native + orchestration'
|
|
|
|
return 'Unknown'
|
|
|
|
if __name__ == '__main__':
|
|
print(f"Recommended build system: {analyze_project()}")</code></pre>
|
|
<h2>Related Skills</h2>
|
|
<ul><li><code>make-fundamentals.md</code> - Make syntax and patterns</li><li><code>cmake-patterns.md</code> - CMake configuration</li><li><code>gradle-jvm-builds.md</code> - Gradle for JVM</li><li><code>maven-configuration.md</code> - Maven for Java</li><li><code>bazel-monorepos.md</code> - Bazel for monorepos</li><li><code>build-optimization.md</code> - Build performance</li><li><code>cross-platform-builds.md</code> - Multi-platform strategies</li></ul>
|
|
<h2>Summary</h2>
|
|
<p>Choosing the right build system is critical for long-term project success:</p>
|
|
<p><strong>Key Takeaways</strong>:</p>
|
|
<ol><li><strong>Language-native first</strong> - Use Cargo (Rust), go build (Go), uv (Python) when possible</li><li><strong>Scale matters</strong> - Small projects: simple tools; Large monorepos: Bazel</li><li><strong>Team expertise</strong> - Leverage existing knowledge (Maven → Gradle easier than Maven → Bazel)</li><li><strong>Migration cost</strong> - Factor in conversion effort vs benefit</li><li><strong>Performance</strong> - Gradle > Maven for JVM; Bazel > all for monorepos with cache</li><li><strong>Cross-platform</strong> - CMake best for C/C++; Bazel best for polyglot</li><li><strong>Ecosystem</strong> - Maven has largest JVM library ecosystem</li><li><strong>Future-proofing</strong> - Choose tools that scale with project growth</li></ol>
|
|
<p><strong>2024 Trends</strong>:</p>
|
|
<ul><li><strong>uv</strong> displacing pip/Poetry for Python (10-100x faster)</li><li><strong>Bun</strong> gaining traction for JavaScript (faster than npm/pnpm)</li><li><strong>Bazel</strong> adoption increasing for large companies (Uber, LinkedIn, Stripe)</li><li><strong>Gradle</strong> remains dominant for Android, growing for server-side JVM</li></ul>
|
|
<p><strong>Bottom Line</strong>: Start simple, migrate when complexity justifies it. Don't use Bazel for a 3-person team, but don't use Make for a 300-person monorepo.</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-build-system-selection.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |