ninjago

package module

v0.0.4-d-oss Latest Latest Go to latest Published: Oct 3, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/google/ninja-go

Links

Open Source Insights

README ¶

ninja-go

ninja-go is a reimplementation of the Ninja build system in Go. It reads standard build.ninja files, including the extensions used by Android's Ninja fork (phony and symlink outputs, validations, the Soong frontend status protocol, and so on). The binary is called ninjago.

Parsing, graph construction, scheduling and execution all call into pluggable backends. Because of this, the same engine can run with different policies for deciding when a step is up to date and how to run its command:

The classic backend (backends/classic) works like upstream Ninja. It uses .ninja_log and .ninja_deps and runs every command locally.
Another Build File Service (ABFS) has its own backend. It replaces timestamp checks with content hashes: for each step, it hashes the command, its inputs and the relevant environment, and looks the result up in a remote function cache. If there is a hit, ABFS materializes the cached outputs and skips the command. If there is a miss, ABFS runs the command, traces the files it reads and writes, and records the result for next time.

[!NOTE] This is not an officially supported Google product.

Building

You need Go 1.26 or later.

go build -o ninjago ./cmd

Usage

ninjago accepts the usual Ninja flags:

ninjago -C out -j 64 all

Tools are available through -t, as in Ninja. Run ninjago -t list to see them all. They include the familiar commands, inputs, path, query and graph, plus ninja-go extras such as dump, ninja_files and rule-query. On Linux, the --psi-cpu, --psi-io and --psi-mem flags pause scheduling of new jobs when pressure stall information (PSI) exceeds the given threshold.

Package layout

Package	Purpose
`ninja`	Data model for the Ninja language: rules, builds, pools, scopes and variable expansion.
`parse`	Parallel parser for Ninja files and depfiles.
`graph`	Builds the dependency graph from parsed files.
`build`	Scheduler and execution engine.
`backends`	Backend interfaces and the `classic` implementation.
`ninjafiles`	Readers and writers for `.ninja_log` and `.ninja_deps`.
`subcommands`	The `-t` tools.
`runtime`	Flags, logging, status line, and other shared runtime helpers.
`third_party/siso/frontend`	Writer for the Soong frontend status protocol, derived from Siso.

Testing

go test ./...

Contributing

See CONTRIBUTING.md.

Security

Eligibility for the Google Open Source Software Vulnerability Rewards Program is determined by the Google Open Source Software Vulnerability Reward Program Rules.

License

Apache 2.0; see LICENSE. Code under third_party/ comes from other projects and keeps its original license; see third_party/siso/frontend/README.md.

Documentation ¶

Overview ¶

Package ninjago is the top-level library entry point for the ninjago CLI: it parses flags, sets up signals and the runtime context, and dispatches the requested subcommand against the supplied backend.

Index ¶

func Main(backend backends.Backend) int

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func Main ¶

func Main(backend backends.Backend) int

Main is the entry point of the ninjago CLI. It parses command-line flags, installs signal handlers, and dispatches to the requested subcommand using the supplied backend.

Types ¶

This section is empty.

Source Files ¶

View all Source files

main.go

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
backends Package backends defines the umbrella Backend interface that ties together the per-stage backend interfaces (subcommands, parse, graph, build) into the single contract a ninjago binary must satisfy.	Package backends defines the umbrella Backend interface that ties together the per-stage backend interfaces (subcommands, parse, graph, build) into the single contract a ninjago binary must satisfy.
classic Package classic implements a ninjago backend that mirrors the on-disk semantics of the upstream ninja binary, including its .ninja_log and .ninja_deps files and local-only command execution.	Package classic implements a ninjago backend that mirrors the on-disk semantics of the upstream ninja binary, including its .ninja_log and .ninja_deps files and local-only command execution.
build Package build schedules and executes the build steps in a Ninja graph, tracking per-step state and delegating command execution and on-disk effects to a pluggable BuildBackend.	Package build schedules and executes the build steps in a Ninja graph, tracking per-step state and delegating command execution and on-disk effects to a pluggable BuildBackend.
cmd Command ninjago is the standalone ninjago CLI binary, wiring the classic backend into the shared ninjago.Main entry point.	Command ninjago is the standalone ninjago CLI binary, wiring the classic backend into the shared ninjago.Main entry point.
graph Package graph builds and represents the dependency graph derived from parsed ninja files, resolving targets, inputs, and discovered dependencies into the nodes the build engine schedules over.	Package graph builds and represents the dependency graph derived from parsed ninja files, resolving targets, inputs, and discovered dependencies into the nodes the build engine schedules over.
ninja Package ninja models the ninja build language: parsed files with their pools, rules, builds, defaults, and key/value bindings, along with the scopes used to expand variables.	Package ninja models the ninja build language: parsed files with their pools, rules, builds, defaults, and key/value bindings, along with the scopes used to expand variables.
ninjafiles
ninjadeps Package ninjadeps reads and writes the .ninja_deps log, the binary per-target dependency database that ninja uses to remember discovered header dependencies between builds.	Package ninjadeps reads and writes the .ninja_deps log, the binary per-target dependency database that ninja uses to remember discovered header dependencies between builds.
ninjalog Package ninjalog reads and writes the .ninja_log file that records the command hash and timing for each previously built target so ninja can detect dirty steps on the next build.	Package ninjalog reads and writes the .ninja_log file that records the command hash and timing for each previously built target so ninja can detect dirty steps on the next build.
parse Package parse parses ninja build files and depfiles into the data structures consumed by the rest of ninjago, and defines the ParseBackend hook used to source file contents and observe the parsed result.	Package parse parses ninja build files and depfiles into the data structures consumed by the rest of ninjago, and defines the ParseBackend hook used to source file contents and observe the parsed result.
runtime Package runtime provides the CLI-facing runtime support shared across ninjago commands: flag and argument parsing, logging, console and status rendering, memory-mapped file I/O, and the RunParameters bag that ties them together.	Package runtime provides the CLI-facing runtime support shared across ninjago commands: flag and argument parsing, logging, console and status rendering, memory-mapped file I/O, and the RunParameters bag that ties them together.
subcommands Package subcommands implements the ninjago subcommands invoked via -t (build, graph, list, path, query, and friends), along with the shared argument plumbing and CommandSpec registry that dispatches to them.	Package subcommands implements the ninjago subcommands invoked via -t (build, graph, list, path, query, and friends), along with the shared argument plumbing and CommandSpec registry that dispatches to them.
third_party
siso/frontend Package frontend serializes build status updates over the Android ninja frontend protocol so that Soong (or another consumer reading the frontend FIFO) can render its own UI.	Package frontend serializes build status updates over the Android ninja frontend protocol so that Soong (or another consumer reading the frontend FIFO) can render its own UI.
siso/frontend/proto Package proto provides protocol buffer message for soong integration.	Package proto provides protocol buffer message for soong integration.
xxmap Package xxmap provides a concurrent string-keyed map sharded by xxhash, trading a fixed amount of memory for reduced contention compared to a single sync.Map under highly parallel access.	Package xxmap provides a concurrent string-keyed map sharded by xxhash, trading a fixed amount of memory for reduced contention compared to a single sync.Map under highly parallel access.