1# Soong
2
3Soong is the replacement for the old Android make-based build system.  It
4replaces Android.mk files with Android.bp files, which are JSON-like simple
5declarative descriptions of modules to build.
6
7## Android.bp file format
8
9By design, Android.bp files are very simple.  There are no conditionals or
10control flow statements - any complexity is handled in build logic written in
11Go.  The syntax and semantics of Android.bp files are intentionally similar
12to [Bazel BUILD files](https://www.bazel.io/versions/master/docs/be/overview.html)
13when possible.
14
15### Modules
16
17A module in an Android.bp file starts with a module type, followed by a set of
18properties in `name: value,` format:
19
20```
21cc_binary {
22    name: "gzip",
23    srcs: ["src/test/minigzip.c"],
24    shared_libs: ["libz"],
25    stl: "none",
26}
27```
28
29Every module must have a `name` property, and the value must be unique across
30all Android.bp files.
31
32For a list of valid module types and their properties see
33[$OUT_DIR/soong/.bootstrap/docs/soong_build.html](https://go/Android.bp).
34
35### Variables
36
37An Android.bp file may contain top-level variable assignments:
38```
39gzip_srcs = ["src/test/minigzip.c"],
40
41cc_binary {
42    name: "gzip",
43    srcs: gzip_srcs,
44    shared_libs: ["libz"],
45    stl: "none",
46}
47```
48
49Variables are scoped to the remainder of the file they are declared in, as well
50as any child blueprint files.  Variables are immutable with one exception - they
51can be appended to with a += assignment, but only before they have been
52referenced.
53
54### Comments
55Android.bp files can contain C-style multiline `/* */` and C++ style single-line
56`//` comments.
57
58### Types
59
60Variables and properties are strongly typed, variables dynamically based on the
61first assignment, and properties statically by the module type.  The supported
62types are:
63* Bool (`true` or `false`)
64* Strings (`"string"`)
65* Lists of strings (`["string1", "string2"]`)
66* Maps (`{key1: "value1", key2: ["value2"]}`)
67
68Maps may values of any type, including nested maps.  Lists and maps may have
69trailing commas after the last value.
70
71### Operators
72
73Strings, lists of strings, and maps can be appended using the `+` operator.
74Appending a map produces the union of keys in both maps, appending the values
75of any keys that are present in both maps.
76
77### Defaults modules
78
79A defaults module can be used to repeat the same properties in multiple modules.
80For example:
81
82```
83cc_defaults {
84    name: "gzip_defaults",
85    shared_libs: ["libz"],
86    stl: "none",
87}
88
89cc_binary {
90    name: "gzip",
91    defaults: ["gzip_defaults"],
92    srcs: ["src/test/minigzip.c"],
93}
94```
95
96### Formatter
97
98Soong includes a canonical formatter for blueprint files, similar to
99[gofmt](https://golang.org/cmd/gofmt/).  To recursively reformat all Android.bp files
100in the current directory:
101```
102bpfmt -w .
103```
104
105The canonical format includes 4 space indents, newlines after every element of a
106multi-element list, and always includes a trailing comma in lists and maps.
107
108### Convert Android.mk files
109
110Soong includes a tool perform a first pass at converting Android.mk files
111to Android.bp files:
112
113```
114androidmk Android.mk > Android.bp
115```
116
117The tool converts variables, modules, comments, and some conditionals, but any
118custom Makefile rules, complex conditionals or extra includes must be converted
119by hand.
120
121#### Differences between Android.mk and Android.bp
122
123* Android.mk files often have multiple modules with the same name (for example
124for static and shared version of a library, or for host and device versions).
125Android.bp files require unique names for every module, but a single module can
126be built in multiple variants, for example by adding `host_supported: true`.
127The androidmk converter will produce multiple conflicting modules, which must
128be resolved by hand to a single module with any differences inside
129`target: { android: { }, host: { } }` blocks.
130
131## Build logic
132
133The build logic is written in Go using the
134[blueprint](http://godoc.org/github.com/google/blueprint) framework.  Build
135logic receives module definitions parsed into Go structures using reflection
136and produces build rules.  The build rules are collected by blueprint and
137written to a [ninja](http://ninja-build.org) build file.
138
139## FAQ
140
141### How do I write conditionals?
142
143Soong deliberately does not support conditionals in Android.bp files.
144Instead, complexity in build rules that would require conditionals are handled
145in Go, where high level language features can be used and implicit dependencies
146introduced by conditionals can be tracked.  Most conditionals are converted
147to a map property, where one of the values in the map will be selected and
148appended to the top level properties.
149
150For example, to support architecture specific files:
151```
152cc_library {
153    ...
154    srcs: ["generic.cpp"],
155    arch: {
156        arm: {
157            srcs: ["arm.cpp"],
158        },
159        x86: {
160            srcs: ["x86.cpp"],
161        },
162    },
163}
164```
165
166See [art/build/art.go](https://android.googlesource.com/platform/art/+/master/build/art.go)
167or [external/llvm/soong/llvm.go](https://android.googlesource.com/platform/external/llvm/+/master/soong/llvm.go)
168for examples of more complex conditionals on product variables or environment variables.
169
170## Contact
171
172Email android-building@googlegroups.com (external) for any questions, or see
173[go/soong](http://go/soong) (internal).
174