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