Mastering Soong: The Modern Build System Behind Android

1. Background and Evolution

In early Android versions, builds relied on Makefile tools such as Android.mk. As the codebase grew, the Makefile approach showed performance bottlenecks and complex configuration management. Google introduced Soong to replace Make, offering a declarative configuration model and better scalability.

Soong uses a declarative syntax that differs significantly from Android.mk. It supports more efficient incremental builds, parallel execution, and clearer dependency management, addressing many pain points of the legacy system.

2. Soong Architecture and Core Components

2.1 Dependency Management

Soong builds based on declared module dependencies. Each module (library, app, tool, etc.) lists the modules it depends on, forming a dependency graph that drives build order and enables incremental builds—only changed modules are rebuilt.

Dependencies are declared in .bp files using a JSON‑like format, which is more structured than the Makefile syntax and easier to parse.

2.2 Blueprint

The core configuration language of Soong is called Blueprint. Blueprint files declare module properties such as type, dependencies, and compiler options. These files are parsed into internal data structures (e.g., Module) used by the build system.

Example of a library module defined in a .bp file:

cc_library {
    name: "libexample",
    srcs: ["example.c"],
    shared_libs: ["libc"],
    static_libs: ["libstatic"],
}

2.3 Relationship with Make

Although Soong is a separate build system, it retains compatibility with Make. It can handle tasks traditionally performed by Makefiles and integrate them into the Soong workflow, allowing a gradual migration without extensive project changes.

3. How Soong Works

3.1 Parsing Blueprint Files

When a build is invoked, Soong scans the source tree for all .bp files, parses them into internal module representations, and extracts dependencies and build rules.

3.2 Generating the Build Graph

After parsing, Soong constructs a directed build graph where each node represents a module and edges represent dependencies. The graph determines the order in which modules are built.

3.3 Executing Build Actions

Based on the graph, Soong executes build actions for each module type (static library, shared library, app, etc.). It supports parallel execution, allowing multiple modules to be built simultaneously for faster overall build times.

3.4 Incremental Builds

Soong only rebuilds modules whose inputs (source files, dependencies, etc.) have changed, dramatically reducing build time for large projects.

4. Using Soong to Build an Android System

4.1 Setting Up the Environment

First, configure the Android build environment, typically by sourcing the setup script:

source build/envsetup.sh

4.2 Writing .bp Files

Each module needs a corresponding .bp file that declares its build rules. To add a new library, create a file such as:

cc_library {
    name: "libmynewlib",
    srcs: ["mynewlib.c"],
    include_dirs: ["include"],
}

4.3 Running the Build Command

After configuring Blueprint files, invoke the Soong build with the m command. To build the entire system: m Or to build a specific module:

m libmynewlib

4.4 Inspecting Build Outputs

Upon completion, Soong places build artifacts (APKs, libraries, etc.) in designated output directories, where developers can verify successful compilation.

5. Comparison with Other Build Tools

Performance : Incremental and parallel builds make Soong faster for large codebases.

Dependency Management : Automatic handling of module dependencies eliminates manual ordering.

Extensibility : The flexible framework allows custom rules and adaptation to various needs.

However, Soong has a learning curve; developers must become familiar with the .bp syntax and module definitions.

6. Conclusion

Soong is a crucial component of the Android build system, delivering efficient incremental builds and robust dependency management that overcome the limitations of earlier tools. Its Blueprint configuration and modular design provide a powerful, extensible platform, and mastering Soong is essential for improving build speed and project maintainability in Android development.