# ninja-build/ninja architecture

> Architecture diagram of the GitHub repository ninja-build/ninja, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ninja-build/ninja
- Repository: https://github.com/ninja-build/ninja

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Bootstrapping & Configuration"
        Boot_Configure["Configure Script"]:::python
        Boot_CMake["CMake Configuration"]:::cmake
    end

    subgraph "CLI & Utilities"
        CLI_Parser["CLI Parser"]:::cli
        CLI_Debug["Debug Flags"]:::cli
    end

    Ninja["ninja binary"]:::core

    subgraph "Build Engine Core"
        Core_Parsing["Parsing Modules"]:::cpp
        Core_DepGraph["Dependency Graph Manager"]:::cpp
        Core_Exec["Execution Module"]:::cpp
        Core_Log["Logging & Status"]:::cpp
    end

    subgraph "Testing & Documentation"
        Test["Testing & Benchmarks"]:::test
        Doc["Documentation"]:::doc
        Aux["Miscellaneous Aux"]:::doc
    end

    subgraph "Platform Specific"
        Plat["Platform-Specific"]:::platform
    end

    %% Connections from Bootstrapping and CLI to ninja binary
    Boot_Configure --> Ninja
    Boot_CMake --> Ninja
    CLI_Parser --> Ninja
    CLI_Debug --> Ninja

    %% Main Build Engine Core flow
    Ninja --> Core_Parsing
    Core_Parsing --> Core_DepGraph
    Core_DepGraph --> Core_Exec
    Core_Exec --> Core_Log

    %% Platform specific integration into execution
    Plat -->|"integrates"| Core_Exec

    %% Additional flows for testing and documentation
    Ninja -->|"triggers"| Test
    Ninja -->|"generates"| Doc
    Doc --> Aux

    %% Click Events
    click Boot_Configure "https://github.com/ninja-build/ninja/blob/master/configure.py"
    click Boot_CMake "https://github.com/ninja-build/ninja/blob/master/CMakeLists.txt"
    click CLI_Parser "https://github.com/ninja-build/ninja/blob/master/src/clparser.cc"
    click CLI_Debug "https://github.com/ninja-build/ninja/blob/master/src/debug_flags.cc"
    click Ninja "https://github.com/ninja-build/ninja/tree/master/src/"
    click Core_Parsing "https://github.com/ninja-build/ninja/blob/master/src/lexer.cc"
    click Core_DepGraph "https://github.com/ninja-build/ninja/blob/master/src/graph.cc"
    click Core_Exec "https://github.com/ninja-build/ninja/blob/master/src/real_command_runner.cc"
    click Core_Log "https://github.com/ninja-build/ninja/blob/master/src/build_log.cc"
    click Test "https://github.com/ninja-build/ninja/blob/master/misc/ninja_syntax_test.py"
    click Doc "https://github.com/ninja-build/ninja/blob/master/doc/manual.asciidoc"
    click Aux "https://github.com/ninja-build/ninja/tree/master/misc/"
    click Plat "https://github.com/ninja-build/ninja/blob/master/src/msvc_helper-win32.cc"

    %% Styles
    classDef python fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef cmake fill:#f5cba7,stroke:#e67e22,stroke-width:2px;
    classDef cli fill:#d6eaf8,stroke:#3498db,stroke-width:2px;
    classDef cpp fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef core fill:#fadbd8,stroke:#e74c3c,stroke-width:2px;
    classDef test fill:#ead7f2,stroke:#8e44ad,stroke-width:2px;
    classDef doc fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef platform fill:#f2d7d5,stroke:#c0392b,stroke-width:2px;
```
