https://abaj.ai/tags/dag/Recent content in Dag on Aayush Bajaj's Augmenting InfrastructureHugoen© 2026 Aayush BajajFri, 10 Jul 2026 08:20:16 +1000https://abaj.ai/wiki/se/implementation/build-systems/Thu, 09 Jul 2026 21:02:56 +1000https://abaj.ai/wiki/se/implementation/build-systems/<p>every build system — make, ninja, bazel, cargo, even npm scripts pretending otherwise — is the same machine: a directed acyclic graph of files and commands, plus a policy for deciding which part of the graph is stale. everything else is syntax.</p> <h2 id="the-model-a-dag-of-targets">the model: a dag of targets<a href="#the-model-a-dag-of-targets" class="post-heading__anchor" aria-hidden="true">#</a> </h2> <ul> <li>a <strong>target</strong> is a file the build can produce; a <strong>rule</strong> says how (a command) and from what (its <strong>dependencies</strong>).</li> <li>dependencies point from outputs to inputs; because outputs of one rule are inputs to another, the whole thing is a dag — a cycle would mean &ldquo;to build a you must first build a&rdquo;.</li> <li>a build is then two steps: <ol> <li><strong>mark dirty</strong>: a target is dirty if it is missing, if any dependency is dirty, or if the staleness policy (timestamps or hashes, below) says an input changed. dirtiness propagates along edges — one flipped source poisons its whole downstream cone.</li> <li><strong>evaluate in topological order</strong>: run each dirty target&rsquo;s command after all its dependencies are up to date (Cormen, Thomas H. and Leiserson, Charles E. and Rivest, Ronald L. and Stein, Clifford, 2009). independent dirty targets can run in parallel (<code>-j8</code>) — the dag <em>is</em> the parallelism plan, which is why builds are embarrassingly parallel until the link step serialises everything.</li> </ol> </li> <li>the entire correctness contract: <strong>the graph must be complete</strong>. every undeclared dependency is a future &ldquo;works after <code>make clean</code>&rdquo; bug — the build system faithfully skips rebuilding things it was never told could change.</li> </ul> <figure class="tikz-figure lateximage"> <script type="text/tikz" > \usepackage{xcolor} \usetikzlibrary{positioning,calc,arrows.meta} \begin{document} \begin{tikzpicture}[font=\small, >={Stealth[length=4pt]}, src/.style={draw, rounded corners=1pt, fill=blue!12, minimum width=1.7cm, minimum height=0.65cm, font=\ttfamily\scriptsize}, ok/.style={draw, rounded corners=1pt, fill=green!15, minimum width=1.7cm, minimum height=0.65cm, font=\ttfamily\scriptsize}, bad/.style={draw, thick, rounded corners=1pt, fill=red!15, minimum width=1.7cm, minimum height=0.65cm, font=\ttfamily\scriptsize}] \node[src] (mainc) at (0,0) {main.c}; \node[bad] (greeth) at (0,-1.4) {greet.h *}; \node[src] (greetc) at (0,-2.8) {greet.c}; \node[bad] (maino) at (3.6,-0.7) {main.o}; \node[bad] (greeto) at (3.6,-2.1) {greet.o}; \node[bad] (app) at (7.0,-1.4) {app}; \draw[->] (mainc) -- (maino); \draw[->, red!70!black, thick] (greeth) -- (maino); \draw[->, red!70!black, thick] (greeth) -- (greeto); \draw[->] (greetc) -- (greeto); \draw[->, red!70!black, thick] (maino) -- (app); \draw[->, red!70!black, thick] (greeto) -- (app); \node[font=\scriptsize, gray, align=left] at (3.6,-3.4) {* edited: dirtiness flows with the arrows}; \node[font=\scriptsize] at (0,0.75) {sources}; \node[font=\scriptsize] at (3.6,0.75) {objects}; \node[font=\scriptsize] at (7.0,0.75) {binary}; \end{tikzpicture} \end{document} </script> <figcaption>dirty-node propagation: editing greet.h dirties every target downstream of it (red); main.c and its untouched cone stay cached. the build re-runs exactly the red commands, in topological order.</figcaption> </figure> <h2 id="make-the-actual-semantics">make: the actual semantics<a href="#make-the-actual-semantics" class="post-heading__anchor" aria-hidden="true">#</a> </h2> <p>make&rsquo;s whole rebuild rule fits in one sentence: <strong>a target is rebuilt if it does not exist, or if any prerequisite&rsquo;s mtime is newer than the target&rsquo;s mtime.</strong> everything else is macro expansion.</p>