# aosp-mirror/platform_build architecture

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

- Interactive diagram: https://gitdiagram.com/aosp-mirror/platform_build
- Repository: https://github.com/aosp-mirror/platform_build

## Overview

##### Project type and purpose
- This is neither a web app nor a library, but the Makefile-based portion of the Android platform build system—an open-source, large-scale build orchestrator.
- Its role is to read Android.mk (Makefile) and Android.bp (Blueprint) files, turn them into a unified Ninja build graph (via Kati and Soong), then drive actual compilation, packaging, and image generation for Android.

##### Top-level structural analysis
- “core/” and “common/”: dozens of `.mk`, Python, and shell scripts defining generic build rules, tool invocation, environment variables.
- “target/” and “target/product/”: per-board and per-product configuration (BoardConfig.mk, manifest files).
- “packaging/”: high-level packaging recipes.
- “tools/”: 100+ sub-tools (Go, Rust, Java, C++, Python) for code-generation, compliance checks, file utilities, backport fixes, storage APIs, etc.
- “ci/”: CI orchestration, test discovery, metrics, metadata.
- “tests/” and per-tool tests: validation of build logic and tool behavior.
- Scripts at the root—envsetup.sh, help.sh, banchanHelp.sh—set up user environment and wrap `m`, `make`, `soong_build`.

##### Key insights from README
- This Make-based system is being phased out in favor of Soong (Go), yet both co-exist: Makefiles are parsed by Kati (C++) into ninja files, and Soong (Go) also produces ninja files. Ninja then executes the unified graph.

##### Main architectural components
A. Environment & CLI layer
- envsetup.sh, lunch, `m` wrapper → initialize variables (TARGET_BOARD, PRODUCT), set PATH to toolchain.
B. Configuration layer
- Android.mk files (make syntax) and Android.bp files (Blueprint DSL) spread under `core/`, `target/`, `tools/…`, and packaging modules.
C. Build graph generators (parsers)
- Kati (C++): parses Makefiles → writes `.ninja` describing make-style build graph.
- Soong (Go): parses Blueprint files → writes `.ninja` describing Soong-style build graph.
D. Build executor
- Ninja: consumes merged `.ninja` → schedules tasks in parallel, respects dependencies.
E. Toolchain invocation
- gcc/clang (C/C++), javac/dx/d8 (Java/Android), aapt2, zipalign, rst, Rust compilers, custom codegen.
F. Packaging & image creation
- Packaging rules in `packaging/` and `target/` produce system.img, boot.img, OTA zips, APEX/APK packages.
G. CI & test harness
- `ci/` orchestrates device-and-host tests, buildbot integration.
- `tests/` and per-tool test directories validate parsing, codegen, and tool behavior.
H. Extensible tool/plugin ecosystem
- Each `tools/<toolname>/` is a standalone micro-service or CLI tool (written in Go, Rust, Java, Python, C++), with its own build manifest (`Android.bp`), source, and tests.

##### Component interactions and data flows
1. Developer runs `envsetup.sh && lunch <product>` → shell variables set.
2. Developer invokes `m` or `make` → calls Kati under the hood.
3. Kati scans all Android.mk → emits intermediate `.ninja` describing make-style targets.
4. Soong is invoked (via `soong_build`) to scan all Android.bp → emits a second `.ninja`.
5. Ninja merges graphs and schedules steps.
6. Ninja executes individual build actions—compilers, code-generators, packagers.
7. Packaging modules collect built artifacts and assemble final images (system, boot, vendor, OTA).
8. CI jobs in `ci/` trigger similar flows, then run tests (shell, Java, Python, C++).

##### Architectural patterns & design principles
- Pipeline architecture: clearly separated parsing (Kati/Soong) → graph generation → execution (Ninja).
- Plugin/extension pattern: every tool under `tools/` is self-contained with its own manifest and tests.
- Convention-over-configuration: directory layout (core, target, product) drives module discovery.
- Language-agnostic toolchain: supports C/C++, Java, Kotlin, Rust, Go, Python.
- Incremental transition: dual build graphs (Make via Kati, Blueprint via Soong) coexist.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Layer 1: CLI & Environment"
        ES1["envsetup.sh"]:::cli
        ES2["help.sh"]:::cli
        ES3["banchanHelp.sh"]:::cli
        ES4["tapasHelp.sh"]:::cli
        ES5["rbesetup.sh"]:::cli
        ES6["shell_utils.sh"]:::cli
    end

    subgraph "Layer 2: Configuration Sources"
        CFG1["core/"]:::config
        CFG2["target/"]:::config
        CFG3["packaging/"]:::config
        CFG4["Android.bp"]:::config
    end

    subgraph "Layer 3: Build Graph Generators"
        KATI["Kati (C++)"]:::parser
        SOONG["Soong (Go)"]:::parser
    end

    subgraph "Layer 4: Executor"
        NINJA["Ninja"]:::executor
    end

    subgraph "Layer 5: Toolchain Invocation"
        TC1["core/clang/"]:::toolchain
        TC2["core/java.mk"]:::toolchain
        TC3["core/aapt2.mk"]:::toolchain
        TC4["core/proguard*.flags"]:::toolchain
    end

    subgraph "Layer 6: Packaging & Image Assembly"
        PKG1["packaging/"]:::packaging
        PKG2["core/packaging/"]:::packaging
        PKG3["target/product/"]:::packaging
        PKG4["tools/releasetools/"]:::packaging
    end

    subgraph "Side Services"
        CI["CI & Test Harness"]:::ci
        TOOLS["tools/ plugin ecosystem"]:::plugins
    end

    ES1 --> KATI
    ES1 --> SOONG
    CFG1 --> KATI
    CFG2 --> KATI
    CFG3 --> KATI
    CFG4 --> SOONG

    KATI --> NINJA
    SOONG --> NINJA

    NINJA --> TC1
    NINJA --> TC2
    NINJA --> TC3
    NINJA --> TC4

    TC1 --> PKG1
    TC2 --> PKG1
    TC3 --> PKG1
    TC4 --> PKG1

    CI --> ES1
    CI --> NINJA
    CI --> TOOLS

    TOOLS --> NINJA

    click ES1 "https://github.com/aosp-mirror/platform_build/blob/main/envsetup.sh"
    click ES2 "https://github.com/aosp-mirror/platform_build/blob/main/help.sh"
    click ES3 "https://github.com/aosp-mirror/platform_build/blob/main/banchanHelp.sh"
    click ES4 "https://github.com/aosp-mirror/platform_build/blob/main/tapasHelp.sh"
    click ES5 "https://github.com/aosp-mirror/platform_build/blob/main/rbesetup.sh"
    click ES6 "https://github.com/aosp-mirror/platform_build/blob/main/shell_utils.sh"
    click CFG1 "https://github.com/aosp-mirror/platform_build/tree/main/core/"
    click CFG2 "https://github.com/aosp-mirror/platform_build/tree/main/target/"
    click CFG3 "https://github.com/aosp-mirror/platform_build/tree/main/packaging/"
    click CFG4 "https://github.com/aosp-mirror/platform_build/blob/main/Android.bp"
    click KATI "https://github.com/aosp-mirror/platform_build/tree/main/tools/product_config/src/com/android/build/config/"
    click CI "https://github.com/aosp-mirror/platform_build/tree/main/ci/"
    click TOOLS "https://github.com/aosp-mirror/platform_build/tree/main/tools/"

    classDef cli fill:#fdfd96,stroke:#333,stroke-width:1px
    classDef config fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef parser fill:#add8e6,stroke:#333,stroke-width:1px
    classDef executor fill:#90ee90,stroke:#333,stroke-width:1px
    classDef toolchain fill:#ffa500,stroke:#333,stroke-width:1px
    classDef packaging fill:#dda0dd,stroke:#333,stroke-width:1px
    classDef ci fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef plugins fill:#ffeb99,stroke:#333,stroke-width:1px
```
