sigistry Build System Decode
Purpose
A repeatable way to understand and drive an unfamiliar build, so you can answer "what can I run, what does it do, and how do I build/test just my package?" without holding the whole dependency graph in your head. Detect the tool from its manifest, use the tool's own introspection instead of hand-parsing config, and always find the narrowest command that gets your package green.
Detection: manifest → build system
| Manifest file(s) | Build system | Introspection command |
|---|---|---|
Makefile |
Make | make help, make -qp, grep .PHONY |
BUILD(.bazel), WORKSPACE, MODULE.bazel |
Bazel | bazel query //... |
build.gradle(.kts), settings.gradle |
Gradle | ./gradlew tasks --all |
pom.xml |
Maven | mvn help:describe, <modules> |
package.json scripts + lockfile |
npm/pnpm/yarn | read scripts, <pm> run |
nx.json, project.json |
Nx | nx graph, nx show projects |
turbo.json |
Turborepo | turbo run build --dry |
CMakeLists.txt |
CMake | cmake --build . --target help |
Cargo.toml ([workspace]) |
cargo | cargo metadata, --workspace |
go.mod, go.work |
go build | go list ./... |
A repo often has two layers: a top-level orchestrator (Make, Nx, Turbo, Bazel) driving per-language builds underneath. Identify both.
The three questions to answer
- What targets exist? Use the tool's list/query command, never invent a target. Distinguish real build/test/lint targets from convenience aliases.
- What depends on what? Get the graph from the tool (
bazel query 'deps(...)',gradle :p:dependencies,nx graph,cargo metadata). Find the difference between "build the world" and "build my package + only its deps." - How do I build/test one package? Every ecosystem has a scoping flag, the single most useful thing to a newcomer. Make it the headline (see
build-systems.md).
Decision checklist
- Detect the tool(s) from the manifest table above; cite the file.
- Run the introspection command to enumerate real targets.
- Pull the dependency graph from the tool, not by eye.
- Identify the single-package build/test command and the affected/changed command.
- Note required bootstrap (toolchain fetch,
bazel sync, lockfile verification) before the first build works.
Additional Resources
Reference Files
references/build-systems.md: per build tool (Make, Bazel, Gradle, Maven, npm/pnpm/yarn, Nx, Turborepo, CMake, cargo, go): how to list targets, read the dependency graph, and build/test exactly one package, with the concrete commands.references/monorepo-patterns.md: workspaces, project graphs, affected/changed detection, task pipelines/caching, and how tasks are wired across packages in each major monorepo toolchain.