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.

Soong是google用來替代過去的Android構(gòu)建系統(tǒng)的新一代構(gòu)建系統(tǒng)，用JSON風格的Android.bp取代Android.mk。

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.

Android.bp文件設(shè)計上非常簡潔锣吼，它不包含條件控制辞做，將構(gòu)建過程中所有復雜性都寫在了Go中厌小。bp文件的語法和語義被有意設(shè)計的和Bazel一致简肴。

Modules

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

Android.bp文件由一個模塊類別起頭贮缅，模塊類別下定義了一系列由name：value表示的屬性：

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.

每個模塊都有一個name屬性榨咐，該屬性必需在所有Android.bp文件中是唯一的。

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

要了解所有可用的模塊類別及支持的屬性谴供，可以構(gòu)建AOSP块茁，然后查詢相關(guān)文檔， $OUT_DIR/soong/.bootstrap/docs/soong_build.html.桂肌。

Variables

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

bp文件可以包含全局變量：

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.

變量在聲明后数焊，直到當前文件結(jié)束前都是有效的，包括子文件內(nèi)也有效崎场。變量在被使用前佩耳，可以使用 += 符號追加內(nèi)容，一旦被引用過谭跨，變量就不可改變干厚。

Comments

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

.bp文件中可以包含C風格的注釋。

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.

Map的value可以是任意類型（注意到List似乎只能是String類型）污呼，也就是說value可以是嵌套的List或者Map。map和list的最后一個元素后面可以有一個額外的逗號包竹。

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.

String燕酷、List和Map可以使用 + 運算符將內(nèi)容合并到一起。整數(shù)可以用 + 運算符相加周瞎。對Map進行合并會對兩個Map的key集合取并集苗缩，每個key對應的value是兩個map中對應value的集合（這段不是很理解，待驗證）声诸。

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"],

}

Name resolution

Soong provides the ability for modules in different directories to specify the same name, as long as each module is declared within a separate namespace. A namespace can be declared like this:

Soong可以讓不同目錄中的模塊具有相同的名字泻肯，只要同名模塊不在同一個namespace中渊迁。一個namespace的聲明如下：

soong_namespace {

imports: ["path/to/otherNamespace1", "path/to/otherNamespace2"],

}

Each Soong module is assigned a namespace based on its location in the tree. Each Soong module is considered to be in the namespace defined by the soong_namespace found in an Android.bp in the current directory or closest ancestor directory, unless no such soong_namespace module is found, in which case the module is considered to be in the implicit root namespace.

每個Soong的模塊都根據(jù)它所屬的目錄位置而被歸為某一個namespace下。每個Soong的模塊都屬于距離所屬目錄層級最近的父目錄所屬的namespace灶挟，如果某個Soong模塊無法被歸為任何一個namespace琉朽，那它就被歸于默認的root namespace。

When Soong attempts to resolve dependency D declared my module M in namespace N which imports namespaces I1, I2, I3..., then if D is a fully-qualified name of the form “//namespace:module”, only the specified namespace will be searched for the specified module name. Otherwise, Soong will first look for a module named D declared in namespace N. If that module does not exist, Soong will look for a module named D in namespaces I1, I2, I3... Lastly, Soong will look in the root namespace.

在Soong試圖根據(jù)name找到某個module時稚铣，首先Soong會查看name是否已經(jīng)指定了一個namespace箱叁，即name是否是”namespace:module”這樣的形式，如果是惕医，那么Soong就直接去指定的namespace尋找module耕漱；否則，Soong會挨個從當前文件引用的namespace查找module抬伺，最后再去root namespace查螟够。

Until we have fully converted from Make to Soong, it will be necessary for the Make product config to specify a value of PRODUCT_SOONG_NAMESPACES. Its value should be a space-separated list of namespaces that Soong export to Make to be built by the m command. After we have fully converted from Make to Soong, the details of enabling namespaces could potentially change.

由于歷史原因，現(xiàn)在AOSP還沒有完全將構(gòu)建系統(tǒng)從Make轉(zhuǎn)換到Soong沛简，因此在構(gòu)建時必須要指定PRODUCT_SOONG_NAMESPACES環(huán)境變量齐鲤，告訴Soong一個namespace列表。未來等AOSP完全遷移到Soong椒楣，可能會使用其他方式來指定namespace给郊。

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:

Soong提供了將Android.mk轉(zhuǎn)換成Android.bp的工具：

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.

這個工具僅能轉(zhuǎn)換簡單的Android.mk，如果Android.mk中包含條件控制等復雜成分捧灰，這個工具將無法轉(zhuǎn)換淆九。

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 ninjabuild file.

Other documentation

• Best Practices
• Build Performance
• Generating CLion Projects
• Make-specific documentation: build/make/README.md

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).