README.md
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
7See [Simple Build
8Configuration](https://source.android.com/compatibility/tests/development/blueprints)
9on source.android.com to read how Soong is configured for testing.
10
11## Android.bp file format
12
13By design, Android.bp files are very simple. There are no conditionals or
14control flow statements - any complexity is handled in build logic written in
15Go. The syntax and semantics of Android.bp files are intentionally similar
16to [Bazel BUILD files](https://www.bazel.io/versions/master/docs/be/overview.html)
17when possible.
18
19### Modules
20
21A module in an Android.bp file starts with a module type, followed by a set of
22properties in `name: value,` format:
23
24```
25cc_binary {
26 name: "gzip",
27 srcs: ["src/test/minigzip.c"],
28 shared_libs: ["libz"],
29 stl: "none",
30}
31```
32
33Every module must have a `name` property, and the value must be unique across
34all Android.bp files.
35
36For a list of valid module types and their properties see
37[$OUT_DIR/soong/docs/soong_build.html](https://ci.android.com/builds/latest/branches/aosp-build-tools/targets/linux/view/soong_build.html).
38
39### Globs
40
41Properties that take a list of files can also take glob patterns. Glob
42patterns can contain the normal Unix wildcard `*`, for example "*.java". Glob
43patterns can also contain a single `**` wildcard as a path element, which will
44match zero or more path elements. For example, `java/**/*.java` will match
45`java/Main.java` and `java/com/android/Main.java`.
46
47### Variables
48
49An Android.bp file may contain top-level variable assignments:
50```
51gzip_srcs = ["src/test/minigzip.c"],
52
53cc_binary {
54 name: "gzip",
55 srcs: gzip_srcs,
56 shared_libs: ["libz"],
57 stl: "none",
58}
59```
60
61Variables are scoped to the remainder of the file they are declared in, as well
62as any child blueprint files. Variables are immutable with one exception - they
63can be appended to with a += assignment, but only before they have been
64referenced.
65
66### Comments
67Android.bp files can contain C-style multiline `/* */` and C++ style single-line
68`//` comments.
69
70### Types
71
72Variables and properties are strongly typed, variables dynamically based on the
73first assignment, and properties statically by the module type. The supported
74types are:
75* Bool (`true` or `false`)
76* Integers (`int`)
77* Strings (`"string"`)
78* Lists of strings (`["string1", "string2"]`)
79* Maps (`{key1: "value1", key2: ["value2"]}`)
80
81Maps may values of any type, including nested maps. Lists and maps may have
82trailing commas after the last value.
83
84### Operators
85
86Strings, lists of strings, and maps can be appended using the `+` operator.
87Integers can be summed up using the `+` operator. Appending a map produces the
88union of keys in both maps, appending the values of any keys that are present
89in both maps.
90
91### Defaults modules
92
93A defaults module can be used to repeat the same properties in multiple modules.
94For example:
95
96```
97cc_defaults {
98 name: "gzip_defaults",
99 shared_libs: ["libz"],
100 stl: "none",
101}
102
103cc_binary {
104 name: "gzip",
105 defaults: ["gzip_defaults"],
106 srcs: ["src/test/minigzip.c"],
107}
108```
109
110### Name resolution
111
112Soong provides the ability for modules in different directories to specify
113the same name, as long as each module is declared within a separate namespace.
114A namespace can be declared like this:
115
116```
117soong_namespace {
118 imports: ["path/to/otherNamespace1", "path/to/otherNamespace2"],
119}
120```
121
122Each Soong module is assigned a namespace based on its location in the tree.
123Each Soong module is considered to be in the namespace defined by the
124soong_namespace found in an Android.bp in the current directory or closest
125ancestor directory, unless no such soong_namespace module is found, in which
126case the module is considered to be in the implicit root namespace.
127
128When Soong attempts to resolve dependency D declared my module M in namespace
129N which imports namespaces I1, I2, I3..., then if D is a fully-qualified name
130of the form "//namespace:module", only the specified namespace will be searched
131for the specified module name. Otherwise, Soong will first look for a module
132named D declared in namespace N. If that module does not exist, Soong will look
133for a module named D in namespaces I1, I2, I3... Lastly, Soong will look in the
134root namespace.
135
136Until we have fully converted from Make to Soong, it will be necessary for the
137Make product config to specify a value of PRODUCT_SOONG_NAMESPACES. Its value
138should be a space-separated list of namespaces that Soong export to Make to be
139built by the `m` command. After we have fully converted from Make to Soong, the
140details of enabling namespaces could potentially change.
141
142### Formatter
143
144Soong includes a canonical formatter for blueprint files, similar to
145[gofmt](https://golang.org/cmd/gofmt/). To recursively reformat all Android.bp files
146in the current directory:
147```
148bpfmt -w .
149```
150
151The canonical format includes 4 space indents, newlines after every element of a
152multi-element list, and always includes a trailing comma in lists and maps.
153
154### Convert Android.mk files
155
156Soong includes a tool perform a first pass at converting Android.mk files
157to Android.bp files:
158
159```
160androidmk Android.mk > Android.bp
161```
162
163The tool converts variables, modules, comments, and some conditionals, but any
164custom Makefile rules, complex conditionals or extra includes must be converted
165by hand.
166
167#### Differences between Android.mk and Android.bp
168
169* Android.mk files often have multiple modules with the same name (for example
170for static and shared version of a library, or for host and device versions).
171Android.bp files require unique names for every module, but a single module can
172be built in multiple variants, for example by adding `host_supported: true`.
173The androidmk converter will produce multiple conflicting modules, which must
174be resolved by hand to a single module with any differences inside
175`target: { android: { }, host: { } }` blocks.
176
177## Build logic
178
179The build logic is written in Go using the
180[blueprint](http://godoc.org/github.com/google/blueprint) framework. Build
181logic receives module definitions parsed into Go structures using reflection
182and produces build rules. The build rules are collected by blueprint and
183written to a [ninja](http://ninja-build.org) build file.
184
185## Other documentation
186
187* [Best Practices](docs/best_practices.md)
188* [Build Performance](docs/perf.md)
189* [Generating CLion Projects](docs/clion.md)
190* [Generating YouCompleteMe/VSCode compile\_commands.json file](docs/compdb.md)
191* Make-specific documentation: [build/make/README.md](https://android.googlesource.com/platform/build/+/master/README.md)
192
193## FAQ
194
195### How do I write conditionals?
196
197Soong deliberately does not support conditionals in Android.bp files.
198Instead, complexity in build rules that would require conditionals are handled
199in Go, where high level language features can be used and implicit dependencies
200introduced by conditionals can be tracked. Most conditionals are converted
201to a map property, where one of the values in the map will be selected and
202appended to the top level properties.
203
204For example, to support architecture specific files:
205```
206cc_library {
207 ...
208 srcs: ["generic.cpp"],
209 arch: {
210 arm: {
211 srcs: ["arm.cpp"],
212 },
213 x86: {
214 srcs: ["x86.cpp"],
215 },
216 },
217}
218```
219
220See [art/build/art.go](https://android.googlesource.com/platform/art/+/master/build/art.go)
221or [external/llvm/soong/llvm.go](https://android.googlesource.com/platform/external/llvm/+/master/soong/llvm.go)
222for examples of more complex conditionals on product variables or environment variables.
223
224## Developing for Soong
225
226To load Soong code in a Go-aware IDE, create a directory outside your android tree and then:
227```bash
228apt install bindfs
229export GOPATH=<path to the directory you created>
230build/soong/scripts/setup_go_workspace_for_soong.sh
231```
232
233This will bind mount the Soong source directories into the directory in the layout expected by
234the IDE.
235
236## Contact
237
238Email android-building@googlegroups.com (external) for any questions, or see
239[go/soong](http://go/soong) (internal).
240