ninja -t: Subtools for Debugging Builds
ninja -t <tool> runs a Ninja subtool to clean, inspect, or export data about the build graph.
Beyond building, ninja ships diagnostic subtools. The most useful in CI are compdb (compile database), clean, and targets for discovering what is buildable.
What it does
ninja -t selects a subtool instead of building. clean removes built files, compdb prints a JSON compile database, deps shows recorded header dependencies, and targets lists available targets. Run ninja -t list to see them all.
Common usage
ninja -C build -t compdb > compile_commands.json
ninja -C build -t clean
ninja -C build -t targets all
ninja -C build -t graph | dot -Tpng -o graph.pngOptions
| Subtool | What it does |
|---|---|
| -t clean | Remove built files (like make clean) |
| -t compdb | Print a compile_commands.json compile database |
| -t targets | List targets that can be built |
| -t deps | Show the dependency records Ninja stored |
| -t graph | Emit the build graph in Graphviz dot format |
| -t list | List all available subtools |
In CI
Prefer ninja -t compdb over Bear when Ninja already generated the build, since it reads the graph directly and needs no compiler interception. Use -t clean for a targeted clean without deleting the whole configured build directory.
Common errors in CI
"ninja: error: unknown tool" means a typo in the subtool name; run ninja -t list. An empty compile_commands.json usually means the build was configured without CMAKE_EXPORT_COMPILE_COMMANDS and no rules carry command info, or -C points at an unconfigured dir. Older Ninja versions lack some subtools; upgrade if -t list does not show it.