Ninja Build Graph

Why Make and Soong Don't Actually Compile Code

Building a massive project like Android using traditional Makefiles takes an agonizing amount of time. You might type a command and wait five minutes just for the system to calculate that nothing needs updating. This delay happens because older build systems mix planning with execution. They calculate dependencies, check file timestamps, and try to execute shell commands all at the same time. Google solved this by splitting the AOSP build process into two distinct phases.

Soong and Kati act strictly as the planners. They read your build files and calculate the structural loads of the dependency graph without compiling a single file. This makes them like architects drawing complex blueprints. The system hands those finished blueprints to a general contractor who blindly hammers the nails exactly where instructed. Once we understand that Soong and Kati only plan the build, we need to meet the tool designed solely to execute that plan with ruthless efficiency.

Ninja: Designed to be Dumb and Fast

Executing thousands of compiler commands requires a tool that does not waste cycles thinking. Google chose Ninja as the general contractor for AOSP because it avoids variables, conditional logic, and dynamic dependency resolution. Ninja expects a pre-calculated, explicitly defined list of exact shell commands. Kati translates legacy Makefiles into a Ninja file, while Soong translates modern Blueprint files into another file. A master file merges these outputs together.

Ninja reads this combined document and executes the commands instantly across all available CPU cores. This stateless approach provides maximum parallelization speed. You can see this transition in your terminal when you type a build command. The Soong bootstrap finishes, and the console instantly switches to the rapid Ninja execution output.

We will map out the flow of Soong and Kati generating their respective Ninja files. This visualization clarifies how the build planners feed the final executor.

Both planners act independently to parse their specific configuration files. Their separate outputs merge into one combined file that gives the Ninja executor its marching orders. To understand how Ninja achieves this speed, we need to peek inside the master file that Kati and Soong generate.

Anatomy of the Execution Graph: Rules and Build Statements

Debugging a crashed compilation requires seeing exactly what the build system requested from the machine. The massive file that Soong and Kati generate consists of rules and build statements. A rule defines a reusable command template, like invoking the C++ compiler. Each build statement acts like a function call that applies specific inputs to that rule template.

rule cc_compile
  command = prebuilts/clang/bin/clang++ -c $in -o $out

build out/main.o: cc_compile frameworks/base/main.cpp

The build statement binds the input source file to the compiler rule to produce the object output. This rigid binding creates a predictable edge in the dependency graph.

Warning: Never hand-edit .ninja files in AOSP. The planning phase completely overwrites these generated files on the next execution.

Now that we know how to read the raw instructions Ninja executes, we can use this knowledge for the most common AOSP developer task. Fixing broken builds requires extracting these exact commands.

Debugging AOSP with Raw Ninja Commands

Searching through thousands of lines of terminal output to find a compiler error often feels impossible. Ninja output contains the fully resolved command that crashed, giving you exactly what you need to troubleshoot. When a build fails, you scroll up to find the specific compiler invocation. You can copy the massive string of text, complete with every include flag, and paste it directly into your shell.

Tip: Paste massive Ninja commands into a text editor to inspect the include paths before running them in the shell.

Running the command manually lets you test fixes without re-invoking the entire AOSP build system. Bypassing the build planners saves massive amounts of time when resolving syntax errors.

Debugging Note: Use ninja -n -d explain to trace what Ninja would do without actually executing the compilation.

By isolating the exact command Ninja ran, you step outside the AOSP architecture and troubleshoot purely at the compiler level.

Ninja operates as the dumb, fast executor of the AOSP pipeline. It relies entirely on Soong and Kati to calculate the build graph before execution begins. The raw output from Ninja becomes your best tool when debugging compiler errors.

Now that the compiler has turned our code into raw object files and binaries, the build system must stitch them together. You cannot boot a device from loose object files scattered across a directory. The system must package everything into the precise image formats expected by the hardware.