Understanding Android Soong Build System and Android.bp File Format

Soong is a replacement for the original make‑based Android build system and uses Android.bp files, written in a JSON‑like syntax, to describe how modules should be built.

Android.bp file format

The design of Android.bp is intentionally simple, lacking conditional statements or control flow; its syntax and semantics are similar to Bazel BUILD files.

Modules

Each module in an Android.bp file starts with a module type followed by a set of name‑value pair attributes. The basic format is:

cc_binary {
    name: "gzip",
    srcs: ["src/test/minigzip.c"],
    shared_libs: ["libz"],
    stl: "none",
}

Every module must have a unique name attribute across all Android.bp files.

Variables

Android.bp files can declare top‑level variables and assign values, for example:

gzip_srcs = ["src/test/minigzip.c"],
cc_binary {
    name: "gzip",
    srcs: gzip_srcs,
    shared_libs: ["libz"],
    stl: "none",
}

Variable scope is limited to the remainder of the file where they are declared and any child blueprint files; they can only be appended with += and must be referenced after assignment.

Comments

C‑style block comments /* */ and C++‑style line comments // are supported.

Types

Variables and properties are strongly typed, inferred from the first assignment and constrained by the module type. Supported types include booleans, strings, string lists, and maps (which can be nested and may end with a trailing comma).

Operators

Strings, string lists, and maps can be concatenated with the + operator; map concatenation produces a union of keys and merges values for duplicate keys.

Default modules

Default modules allow shared attributes to be defined once and reused, e.g.:

cc_defaults {
    name: "gzip_defaults",
    shared_libs: ["libz"],
    stl: "none",
}
cc_binary {
    name: "gzip",
    defaults: ["gzip_defaults"],
    srcs: ["src/test/minigzip.c"],
}

Formatting tool

Soong includes a blueprint formatter similar to gofmt . Run $ bpfmt -w to recursively format all Android.bp files in the current directory, using a standard style of 4‑space indentation and commas after list and map entries.

Converting Android.mk files

The androidmk tool can translate an Android.mk file to an Android.bp file ( $ androidmk Android.mk > Android.bp ), handling variables, modules, comments, and some conditions, though custom Makefile rules and complex conditions must be converted manually.

Build logic

The build logic is written in Go using the Blueprint framework; it parses module definitions, reflects them into Go data structures, and generates Ninja build files.

Common questions

Soong deliberately does not support conditional statements in Android.bp . Complex conditions are handled in Go code, often represented as maps where a selected value is merged into top‑level properties. An example of architecture‑specific sources:

cc_library {
    ...
    srcs: ["generic.cpp"],
    arch: {
        arm: {
            srcs: ["arm.cpp"],
        },
        x86: {
            srcs: ["x86.cpp"],
        },
    },
}

For further assistance, email [email protected] or refer to the internal go/soong documentation.