How ninja-build/ninja works
Main Components
• Build Engine Core (src/): This is the heart of Ninja. It includes modules for parsing build files (e.g., lexer, parser, manifest_parser, depfile_parser), constructing and managing dependency graphs (e.g., graph.*, state.*), command execution (e.g., subprocess, real_command_runner), build logging, and status reporting.
• Command-Line Interface & Utilities: Modules such as clparser and debug_flags manage command-line arguments and options, while helper components (e.g., msvc_helper-win32.cc) manage platform-specific tasks.
• Bootstrapping & Configuration Scripts: The Python script (configure.py) and CMakeLists.txt support multiple build methods (Python bootstrapping vs. CMake-based builds).
• Testing and Performance Benchmarks: Numerous test files (with suffixes like _test.cc, _perftest.cc) validate components; separate test executables (e.g., ninja_test) help verify correctness.
• Documentation and Auxiliary Files: The doc directory with manuals (manual.asciidoc, doxygen.config, dblatex.xsl) and various misc/ subdirectories (e.g., for Bash/Zsh completions, fuzz tokens, packaging scripts) provide extended functionality and integration support.
• Platform-Specific and Compatibility Code: Files targeting Windows (minidump-win32.cc, msvc_helper-win32.cc) indicate cross-platform design considerations.
• Input: Build definitions (the generated build.ninja file and possibly additional configuration from the Python bootstrap process).
• Execution Engine: The dependency graph then leads to the execution subsystem (subprocess handling for launching build commands, real_command_runner).
• Logging and Status: Throughout the build process, data flows into components dedicated to logging (build_log.cc) and status reporting (status_printer.cc).
• CLI utilities are layered at the very start for input validation (e.g., clparser) and help manage user interactions.
• External dependencies like GoogleTest (for testing) and doxygen/asciidoc for documentation generation can be included as separate nodes that interact with corresponding build targets.
• The Python-based configuration (configure.py) and CMake build scripts should be visualized as “setup” components that translate into the final ninja binary.
Architectural Patterns
• Modular Design: Each major functionality is isolated in a set of source files (for example, distinct files handle parsing, execution, logging, etc.).
• Separation of Concerns: The design abstracts the bootstrapping (via Python/CMake) from the built core (the C++ code-base) and further separates out testing and documentation.
• Cross-platform Support: The presence of platform-specific source files (e.g., files ending with -win32) shows that some modules use conditional handling depending on the OS.
Key Technologies and Frameworks
• C++: The primary implementation language for performance.
• Python: Used for configuration/bootstrapping (via configure.py).
• CMake: An alternative build system option.
• GoogleTest: For running unit tests (as mentioned in the README).
• Doxygen and Asciidoc: For generating documentation.
Final Recommendations for Clarity
• That the dynamic data flows (e.g., build file → parse → execute) are visually distinguishable from static relationships (e.g., configuration dependencies).