No Description

Colin Cross 393667285e Replace root.bp with a comment 6 years ago
android 6dfde48ba1 Merge changes from topics "soong_logtags", "droiddoc_srcjars" 6 years ago
androidmk d00350c61b Add license headers to all go and shell files 6 years ago
bpfix 3a7822c571 Have bpfix not remove empty lists 6 years ago
cc d00350c61b Add license headers to all go and shell files 6 years ago
cmd b61e3f79ec multiproduct_kati support for a custom list of products 6 years ago
docs 52d7a66671 Add Documentation for clion project generator 7 years ago
env 68f55102da Support dependencies on environment variables 9 years ago
finder 821271b3b8 Fix the Finder's ability to ignore permission errors 6 years ago
fs b629e184dd Fail the Finder in case of unexpected fs error 6 years ago
genrule 35143d0466 Fix genrules depending on Go tools 6 years ago
jar bddcf13555 Change default jar time to match ziptime 6 years ago
java b1bd1aabca Use logtags without merged file 6 years ago
phony 0f86d186b1 Allow AndroidMkData.Custom handlers to extend normal values 6 years ago
python ea568a4a24 Change bool, and string properties to *bool, and *string for java, 6 years ago
scripts d00350c61b Add license headers to all go and shell files 6 years ago
shared efc1b412f1 Have Soong try to enforce that genrules declare all their outputs. 7 years ago
third_party 10e8e93710 Strip extended-timestap extra block in zip2zip. 6 years ago
ui a7cdd156a6 Support EXPERIMENTAL_USE_OPENJDK9=false. 6 years ago
zip f83c150269 Add --write_if_changed argument to soong_zip 6 years ago
Android.bp f18e11074d Fix using aidl files from filegroups 6 years ago
OWNERS 81a6cb3295 Add OWNERS in build/soong 7 years ago
PREUPLOAD.cfg 78ffeea24e Fix gofmt problems and add gofmt to preupload checks 7 years ago
README.md 61eaedbddf Support Javac sharding in Soong. 6 years ago
bootstrap.bash d00350c61b Add license headers to all go and shell files 6 years ago
build_test.bash 89479facb9 Get some more debugging for ckati crashes 6 years ago
doc.go 3f40fa460d Add soong_build primary builder 9 years ago
root.bp 393667285e Replace root.bp with a comment 6 years ago
soong.bash d00350c61b Add license headers to all go and shell files 6 years ago
soong.bootstrap.in 87b17d1ff4 Use SRCDIR as a working directory 8 years ago
soong_ui.bash 91f9b54767 Switch to blueprint's microfactory 6 years ago

README.md

Soong

Soong is the replacement for the old Android make-based build system. It replaces Android.mk files with Android.bp files, which are JSON-like simple declarative descriptions of modules to build.

Android.bp file format

By design, Android.bp files are very simple. There are no conditionals or control flow statements - any complexity is handled in build logic written in Go. The syntax and semantics of Android.bp files are intentionally similar to Bazel BUILD files when possible.

Modules

A module in an Android.bp file starts with a module type, followed by a set of properties in name: value, format:

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

Every module must have a name property, and the value must be unique across all Android.bp files.

For a list of valid module types and their properties see $OUT_DIR/soong/.bootstrap/docs/soong_build.html.

Variables

An Android.bp file may contain top-level variable assignments:

gzip_srcs = ["src/test/minigzip.c"],

cc_binary {
    name: "gzip",
    srcs: gzip_srcs,
    shared_libs: ["libz"],
    stl: "none",
}

Variables are scoped to the remainder of the file they are declared in, as well as any child blueprint files. Variables are immutable with one exception - they can be appended to with a += assignment, but only before they have been referenced.

Comments

Android.bp files can contain C-style multiline /* */ and C++ style single-line // comments.

Types

Variables and properties are strongly typed, variables dynamically based on the first assignment, and properties statically by the module type. The supported types are:

  • Bool (true or false)
  • Integers (int)
  • Strings ("string")
  • Lists of strings (["string1", "string2"])
  • Maps ({key1: "value1", key2: ["value2"]})

Maps may values of any type, including nested maps. Lists and maps may have trailing commas after the last value.

Operators

Strings, lists of strings, and maps can be appended using the + operator. Integers can be summed up using the + operator. Appending a map produces the union of keys in both maps, appending the values of any keys that are present in both maps.

Defaults modules

A defaults module can be used to repeat the same properties in multiple modules. For example:

cc_defaults {
    name: "gzip_defaults",
    shared_libs: ["libz"],
    stl: "none",
}

cc_binary {
    name: "gzip",
    defaults: ["gzip_defaults"],
    srcs: ["src/test/minigzip.c"],
}

Formatter

Soong includes a canonical formatter for blueprint files, similar to gofmt. To recursively reformat all Android.bp files in the current directory:

bpfmt -w .

The canonical format includes 4 space indents, newlines after every element of a multi-element list, and always includes a trailing comma in lists and maps.

Convert Android.mk files

Soong includes a tool perform a first pass at converting Android.mk files to Android.bp files:

androidmk Android.mk > Android.bp

The tool converts variables, modules, comments, and some conditionals, but any custom Makefile rules, complex conditionals or extra includes must be converted by hand.

Differences between Android.mk and Android.bp

  • Android.mk files often have multiple modules with the same name (for example for static and shared version of a library, or for host and device versions). Android.bp files require unique names for every module, but a single module can be built in multiple variants, for example by adding host_supported: true. The androidmk converter will produce multiple conflicting modules, which must be resolved by hand to a single module with any differences inside target: { android: { }, host: { } } blocks.

Build logic

The build logic is written in Go using the blueprint framework. Build logic receives module definitions parsed into Go structures using reflection and produces build rules. The build rules are collected by blueprint and written to a ninja build file.

FAQ

How do I write conditionals?

Soong deliberately does not support conditionals in Android.bp files. Instead, complexity in build rules that would require conditionals are handled in Go, where high level language features can be used and implicit dependencies introduced by conditionals can be tracked. Most conditionals are converted to a map property, where one of the values in the map will be selected and appended to the top level properties.

For example, to support architecture specific files:

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

See art/build/art.go or external/llvm/soong/llvm.go for examples of more complex conditionals on product variables or environment variables.

Contact

Email android-building@googlegroups.com (external) for any questions, or see go/soong (internal).