原文：https://android.googlesource.com/platform/build/soong/+/master/README.md
Soong
Soong是以前Android基于make的編譯系統(tǒng)的替代品瓷产。它以Android.bp文件替代Android.mk，Android.bp文件用類似JSON的簡(jiǎn)潔聲明來描述需要構(gòu)建的模塊锯岖。
Android.bp文件格式
Android.bp文件設(shè)計(jì)得非常簡(jiǎn)潔钝凶。沒有條件或控制流語言（任何復(fù)雜性都在用Go編寫的構(gòu)建邏輯中被處理）仪芒。Android.bp文件的語法和語義在可能的情況下有意類似于 Bazel構(gòu)建文件。
模塊
Android.bp文件中的模塊以模塊類型開頭耕陷，后跟一組name: value格式的屬性：
cc_binary {
name: "gzip",
srcs: ["src/test/minigzip.c"],
shared_libs: ["libz"],
stl: "none",
}
每個(gè)模塊必須有name屬性掂名，且其值在所有Android.bp文件中必須是唯一的。
關(guān)于可用模塊類型及其屬性列表哟沫，參見$OUT_DIR/soong/.bootstrap/docs/soong_build.html.
Glob模式
獲取文件列表的屬性可以采用glob模式饺蔑。Glob模式可以包含普通的Unix通配符*，如"*.java"嗜诀。Glob模式還可以包含單個(gè)**通配符作為路徑元素猾警，它將匹配零個(gè)或多個(gè)路徑元素。如 java/**/*.java 將匹配
java/Main.java 和 java/com/android/Main.java隆敢。
變量
Android.bp文件可包含頂級(jí)變量賦值：
gzip_srcs = ["src/test/minigzip.c"],
cc_binary {
name: "gzip",
srcs: gzip_srcs,
shared_libs: ["libz"],
stl: "none",
}
變量范圍限定為聲明它們的文件的其余部分发皿，以及任何子藍(lán)圖文件。變量是不可變的拂蝎，但有一個(gè)例外 —— 它們可以附上+= 賦值穴墅，但僅在變量被引用之前。
注釋
Android.bp文件可以包含C風(fēng)格多行 /* */ 注釋和C++風(fēng)格的單行 // 注釋。
類型
變量和屬性是強(qiáng)類型的玄货，變量動(dòng)態(tài)地基于首次賦值皇钞，屬性靜態(tài)地由模塊類型。支持的類型是：
- Bool (
trueorfalse) - Integers (
int) - Strings (
"string") - Lists of strings (
["string1", "string2"]) - Maps (
{key1: "value1", key2: ["value2"]})
Map可以是任何類型的值誉结，包括嵌套Map鹅士。List和Map在最后一個(gè)值后可能有逗號(hào)。
操作符
字符串（String）惩坑，字符串列表和映射（Map）可以使用 + 操作符追加字符串掉盅。整形（Integers ）可以使用 + 操作符來求和。追加Map映射會(huì)產(chǎn)生兩個(gè)Map中鍵（Key）的并集以舒，并追加上兩個(gè)Map中所有鍵的值（Value）趾痘。
默認(rèn)模塊
默認(rèn)模塊可用于在多個(gè)模塊中重復(fù)相同的屬性。例如：
cc_defaults {
name: "gzip_defaults",
shared_libs: ["libz"],
stl: "none",
}
cc_binary {
name: "gzip",
defaults: ["gzip_defaults"],
srcs: ["src/test/minigzip.c"],
}
名稱解析
Soong提供為不同目錄中的模塊指定相同名稱的能力蔓钟，只要每個(gè)模塊在單獨(dú)的命名空間中聲明即可永票。命名空間可以像這樣聲明：
soong_namespace {
imports: ["path/to/otherNamespace1", "path/to/otherNamespace2"],
}
每個(gè)Soong模塊都根據(jù)其在樹中的位置分配命名空間。每個(gè)Soong模塊都被認(rèn)為是在當(dāng)前目錄或最近祖先目錄中的Android.bp中找到的soong_namespace定義的命名空間中滥沫，除非找不到這樣的soong_namespace模塊侣集，在這種情況下，模塊被認(rèn)為是在隱式root命名空間中兰绣。
當(dāng)Soong嘗試解析依賴關(guān)系D聲明的我的模塊M時(shí)（M在導(dǎo)入命名空間I1世分，I2，I3 ......的命名空間N中）缀辩，如果D是一個(gè)形如“// namespace:module”的完全限定名稱臭埋，則只有特定的命名空間才會(huì)被搜索指定的模塊名稱。否則臀玄，Soong將首先查找在命名空間N中聲明的名為D的模塊瓢阴。如果該模塊不存在，Soong將在命名空間I1健无，I2荣恐，I3中尋找名為D的模塊......最后，Soong將查找根命名空間累贤。
在我們完全從Make轉(zhuǎn)換為Soong之前募胃，Make product配置必須指定PRODUCT_SOONG_NAMESPACES的值。它的值應(yīng)該是一個(gè)空格分隔的命名空間列表畦浓，Soong導(dǎo)出到Make由m命令構(gòu)建 。在我們完全從Make轉(zhuǎn)換為Soong之后检疫，啟用命名空間的細(xì)節(jié)可能會(huì)發(fā)生變化讶请。
格式化
Soong包含一個(gè)藍(lán)圖文件的規(guī)范的格式化程序，類似于gofmt。以遞歸重新格式化當(dāng)前目錄中的所有Android.bp文件：
bpfmt -w .
規(guī)范的格式包括4個(gè)空格縮進(jìn)夺溢，在多元素列表的每個(gè)元素之后的換行论巍，并且在列表和映射中始終包含尾隨的逗號(hào)。
轉(zhuǎn)換Android.mk文件
Soong包含一個(gè)工具风响，在將Android.mk文件轉(zhuǎn)換為Android.bp文件時(shí)執(zhí)行第一遍：
androidmk Android.mk > Android.bp
該工具轉(zhuǎn)換變量嘉汰，模塊，注釋和一些條件状勤，但必須手動(dòng)轉(zhuǎn)換任何自定義Makefile規(guī)則鞋怀，復(fù)雜條件或額外包含。
Android.mk和Android.bp之間的差異
- Android.mk文件通常具有多個(gè)具有相同名稱的模塊（如：庫的靜態(tài)和共享版本持搜，或主機(jī)和設(shè)備版本）密似。Android.bp文件需要每個(gè)模塊有唯一的名稱，但是可以在多個(gè)變體中構(gòu)建單個(gè)模塊葫盼，如通過添加
host_supported: true残腌。androidmk轉(zhuǎn)換器會(huì)生成多個(gè)沖突的模塊，必須通過處理單個(gè)模塊的target: { android: { }, host: { } }塊里的差異來手動(dòng)解決贫导。
構(gòu)建邏輯
使用blueprint 框架在Go中編寫構(gòu)建邏輯抛猫。構(gòu)建邏輯接收使用反射解析為Go結(jié)構(gòu)的模塊定義并生成構(gòu)建規(guī)則。構(gòu)建規(guī)則由blueprint收集并寫入ninja構(gòu)建文件孩灯。
其他文檔
- 最佳實(shí)踐
- 構(gòu)建性能
- 生成CLion項(xiàng)目
- 生成YouCompleteMe/VSCode compile_commands.json文件
- Make定義文檔: build/make/README.md
常問問題
如何編輯條件?
Soong特意在Android.bp文件中不支持條件闺金。相反，需要條件的構(gòu)建規(guī)則的復(fù)雜性在Go中處理钱反，其中可以使用高級(jí)語言特性并且可以跟蹤條件引入的隱式依賴性掖看。大多數(shù)條件被轉(zhuǎn)換為map屬性，其中將選擇映射中的一個(gè)值并將其附加到頂級(jí)屬性面哥。
例如哎壳，要支持特定體系結(jié)構(gòu)的文件：
cc_library {
...
srcs: ["generic.cpp"],
arch: {
arm: {
srcs: ["arm.cpp"],
},
x86: {
srcs: ["x86.cpp"],
},
},
}
有關(guān)產(chǎn)品變量或環(huán)境變量的更復(fù)雜條件的示例，請(qǐng)參閱 art/build/art.go
或external/llvm/soong/llvm.go尚卫。
Soong開發(fā)
要在Go-aware IDE中加載Soong代碼归榕，請(qǐng)?jiān)赼ndroid樹之外創(chuàng)建一個(gè)目錄，然后：
apt install bindfs
export GOPATH=<path to the directory you created>
build/soong/scripts/setup_go_workspace_for_soong.sh
以上將把Soong源目錄掛載到IDE所期望的布局目錄中吱涉。
聯(lián)系方式
任何疑問請(qǐng)發(fā)電子郵件至android-building@googlegroups.com (外部)或參閱go/soong (內(nèi)部)刹泄。
