Android的Soong介绍

原文:https://android.googlesource.com/platform/build/soong/+/master/README.md

Soong

Soong是以前Android基于make的编译系统的替代品。它以Android.bp文件替代Android.mk,Android.bp文件用类似JSON的简洁声明来描述需要构建的模块。

Android.bp文件格式

Android.bp文件设计得非常简洁。没有条件或控制流语言(任何复杂性都在用Go编写的构建逻辑中被处理)。Android.bp文件的语法和语义在可能的情况下有意类似于 Bazel构建文件

模块

Android.bp文件中的模块以模块类型开头,后跟一组name: value格式的属性:

cc_binary {
    name: "gzip",
    srcs: ["src/test/minigzip.c"],
    shared_libs: ["libz"],
    stl: "none",
}

每个模块必须有name属性,且其值在所有Android.bp文件中必须是唯一的。
关于可用模块类型及其属性列表,参见$OUT_DIR/soong/.bootstrap/docs/soong_build.html.

Glob模式

获取文件列表的属性可以采用glob模式。Glob模式可以包含普通的Unix通配符*,如"*.java"。Glob模式还可以包含单个**通配符作为路径元素,它将匹配零个或多个路径元素。如 java/**/*.java 将匹配
java/Main.javajava/com/android/Main.java

变量

Android.bp文件可包含顶级变量赋值:

gzip_srcs = ["src/test/minigzip.c"],
cc_binary {
    name: "gzip",
    srcs: gzip_srcs,
    shared_libs: ["libz"],
    stl: "none",
}

变量范围限定为声明它们的文件的其余部分,以及任何子蓝图文件。变量是不可变的,但有一个例外 —— 它们可以附上+= 赋值,但仅在变量被引用之前。

注释

Android.bp文件可以包含C风格多行 /* */ 注释和C++风格的单行 // 注释。

类型

变量和属性是强类型的,变量动态地基于首次赋值,属性静态地由模块类型。支持的类型是:

  • Bool (true or false)
  • Integers (int)
  • Strings ("string")
  • Lists of strings (["string1", "string2"])
  • Maps ({key1: "value1", key2: ["value2"]})

Map可以是任何类型的值,包括嵌套Map。List和Map在最后一个值后可能有逗号。

操作符

字符串(String),字符串列表和映射(Map)可以使用 + 操作符追加字符串。整形(Integers )可以使用 + 操作符来求和。追加Map映射会产生两个Map中键(Key)的并集,并追加上两个Map中所有键的值(Value)。

默认模块

默认模块可用于在多个模块中重复相同的属性。例如:

cc_defaults {
    name: "gzip_defaults",
    shared_libs: ["libz"],
    stl: "none",
}
cc_binary {
    name: "gzip",
    defaults: ["gzip_defaults"],
    srcs: ["src/test/minigzip.c"],
}

名称解析

Soong提供为不同目录中的模块指定相同名称的能力,只要每个模块在单独的命名空间中声明即可。命名空间可以像这样声明:

soong_namespace {
    imports: ["path/to/otherNamespace1", "path/to/otherNamespace2"],
}

每个Soong模块都根据其在树中的位置分配命名空间。每个Soong模块都被认为是在当前目录或最近祖先目录中的Android.bp中找到的soong_namespace定义的命名空间中,除非找不到这样的soong_namespace模块,在这种情况下,模块被认为是在隐式root命名空间中。

当Soong尝试解析依赖关系D声明的我的模块M时(M在导入命名空间I1,I2,I3 ......的命名空间N中),如果D是一个形如“// namespace:module”的完全限定名称,则只有特定的命名空间才会被搜索指定的模块名称。否则,Soong将首先查找在命名空间N中声明的名为D的模块。如果该模块不存在,Soong将在命名空间I1,I2,I3中寻找名为D的模块......最后,Soong将查找根命名空间。

在我们完全从Make转换为Soong之前,Make product配置必须指定PRODUCT_SOONG_NAMESPACES的值。它的值应该是一个空格分隔的命名空间列表,Soong导出到Make由m命令构建 。在我们完全从Make转换为Soong之后,启用命名空间的细节可能会发生变化。

格式化

Soong包含一个蓝图文件的规范的格式化程序,类似于gofmt。以递归重新格式化当前目录中的所有Android.bp文件:

bpfmt -w .

规范的格式包括4个空格缩进,在多元素列表的每个元素之后的换行,并且在列表和映射中始终包含尾随的逗号。

转换Android.mk文件

Soong包含一个工具,在将Android.mk文件转换为Android.bp文件时执行第一遍:

androidmk Android.mk > Android.bp

该工具转换变量,模块,注释和一些条件,但必须手动转换任何自定义Makefile规则,复杂条件或额外包含。

Android.mk和Android.bp之间的差异

  • Android.mk文件通常具有多个具有相同名称的模块(如:库的静态和共享版本,或主机和设备版本)。Android.bp文件需要每个模块有唯一的名称,但是可以在多个变体中构建单个模块,如通过添加host_supported: true。androidmk转换器会生成多个冲突的模块,必须通过处理单个模块的target: { android: { }, host: { } }块里的差异来手动解决。

构建逻辑

使用blueprint 框架在Go中编写构建逻辑。构建逻辑接收使用反射解析为Go结构的模块定义并生成构建规则。构建规则由blueprint收集并写入ninja构建文件。

其他文档

常问问题

如何编辑条件?

Soong特意在Android.bp文件中不支持条件。相反,需要条件的构建规则的复杂性在Go中处理,其中可以使用高级语言特性并且可以跟踪条件引入的隐式依赖性。大多数条件被转换为map属性,其中将选择映射中的一个值并将其附加到顶级属性。

例如,要支持特定体系结构的文件:

cc_library {
    ...
    srcs: ["generic.cpp"],
    arch: {
        arm: {
            srcs: ["arm.cpp"],
        },
        x86: {
            srcs: ["x86.cpp"],
        },
    },
}

有关产品变量或环境变量的更复杂条件的示例,请参阅 art/build/art.go
external/llvm/soong/llvm.go

Soong开发

要在Go-aware IDE中加载Soong代码,请在android树之外创建一个目录,然后:

apt install bindfs
export GOPATH=<path to the directory you created>
build/soong/scripts/setup_go_workspace_for_soong.sh

以上将把Soong源目录挂载到IDE所期望的布局目录中。

联系方式

任何疑问请发电子邮件至android-building@googlegroups.com (外部)或参阅go/soong (内部)。

推荐阅读更多精彩内容