Android Soong构建系统（译）

Soong

Soong is one of the build systems used in Android. There are altogether three:

• The legacy Make-based build system that is controlled by files called Android.mk.
• Soong, which is controlled by files called Android.bp.
• The upcoming Bazel-based build system that is controlled by files called BUILD.bazel.
  【译】Soong是Android使用的构建系统之一。Android目前共有三个构建系统：
• 兼容的基于Make的构建系统，由名为Android.mk的文件控制。
• Soong构建系统，由名为Android.bp的文件控制。
• 即将推出的基于Bazel的构建系统，由名为BUILD.bazel的文件控制。

Android.bp file are JSON-like declarative descriptions of “modules” to build; a “module” is the basic unit of building that Soong understands, similarly to how “target” is the basic unit of building for Bazel (and Make, although the two kinds of “targets” are very different)
【译】Android.bp文件采用类似JSON的声明式语法描述待构建的“模块”。在Soong构建系统中，“模块”是最基础的构建单元，这与Bazel构建系统中的“目标”如何作为基本构建单元类似。

See Simple Build Configuration on source.android.com to read how Soong is configured for testing.
【译】请参阅source.android.com上的Simple Build Configuration，了解如何配置Soong以测试。

Android.bp file format //Androd.bp文件格式

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文件非常简单。没有条件或者控制流语句-任何复杂的逻辑都在Go编写的构建逻辑中处理。Android.bp文件中的语法和语义尽可能的和Bazel BUILD files相似。

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中是唯一的。

The list of valid module types and their properties can be generated by calling m soong_docs. It will be written to $OUT_DIR/soong/docs/soong_build.html. This list for the current version of Soong can be found here.
【译】有效模块类型及其属性的列表可以通过调用"m soong_docs"来生成。结果将写到$OUT_DIR/soong/docs/soong_build.html。Soong的当前版本列表在https://ci.android.com/builds/latest/branches/aosp-build-tools/targets/linux/view/soong_build.html

File lists

Properties that take a list of files can also take glob patterns and output path expansions.
【译】接受文件列表的属性也可以接受全局模式和输出路径展开。

• Glob patterns can contain the normal Unix wildcard *, for example "*.java". // Glob patterns(全局模式)，可以包含普通的Unix通配符*,例如"*.java"

  Glob patterns can also contain a single ** wildcard as a path element, which will match zero or more path elements. For example, java/**/*.java will match java/Main.java and java/com/android/Main.java.
  【译】Global patterns还可以包含单个’**'通配符作为路径元素，它将匹配零个或多个路径元素。例如java/**/*.java将匹配java/Main.java和java/com/android/Main.java。

• Output path expansions take the format :module or :module{.tag}, where module is the name of a module that produces output files, and it expands to a list of those output files. With the optional {.tag} suffix, the module may produce a different list of outputs according to tag.
  【译】 输出路径扩展采用:module或者:module{.tag}, 这里的name是产生输出文件的模块名，它展开为这些输出文件的列表。使用可选项{.tag}后缀，模块可以根据tag生成不同的输出列表。

  For example, a droiddoc module with the name “my-docs” would return its .stubs.srcjar output with ":my-docs", and its .doc.zip file with ":my-docs{.doc.zip}".
  【译】例如，一个名为"my-docs"的模块droiddoc将返回它的带有":my-docs"的.stubs.srcjar，带有:my-docs{.doc.zip}的.doc.zip的输出文件。

  This is commonly used to reference filegroup modules, whose output files consist of their srcs.
  【译】这通常用于引用filegroup模块，其输出文件由它们的srcs组成。

Variables

An Android.bp file may contain top-level variable assignments:
【译】Android.bp文件可以包含top-level变量赋值：

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 Android.bp files. Variables are immutable with one exception - they can be appended to with a += assignment, but only before they have been
referenced.
【译】变量的作用域是声明它们的文件的剩余部分，以及任何子Android.bp文件。变量是不可变的，但有一个例外–（只能）在它们被引用前，可以使用+=赋值对它们进行追加。

Comments

Android.bp files can contain C-style multiline /* */ and C++ style single-line // comments.
【译】Android.bp文件可以包含C-style /**/多行注释和C++ style //当行注释。

Types

Variables and properties are strongly typed. Variables are dynamically typed based on the first assignment, and properties are statically typed 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 contain values of any type, including nested maps. Lists and maps may
have trailing commas after the last value.
【译】Maps可以包含任何类型的值，包括嵌套映射 。Lists和Maps可以在最后一个值后面加逗号。

Strings can contain double quotes using \", for example "cat \"a b\"".
【译】字符串可以使用\"包含双引号，例如"cat \"a b\""。

Operators

The + operator: //+ 操作

• Sums integers. //int类型求和
• Concatenates strings and lists. //连接字符串和列表
• Produces the union of maps. //生成映射的并集

Concatenating maps produces a map whose keys are the union of the given maps’
keys, and whose mapped values are the union of the given maps’ corresponding
mapped values.
【译】连接映射生成一个映射，其键是给定映射的键的并集，其映射值是给定映射的对应映射值的并集。

Defaults modules

A defaults module can be used to repeat the same properties in multiple
modules. For example:
【译】default模块可以用于在多个模块中重复相同的属性。例如：

cc_defaults {
    name: "gzip_defaults",
    shared_libs: ["libz"],
    stl: "none",
}

cc_binary {
    name: "gzip",
    defaults: ["gzip_defaults"],
    srcs: ["src/test/minigzip.c"],
}

Packages

The build is organized into packages where each package is a collection of related files and a specification of the dependencies among them in the form of modules.
【译】构建被组织成包，每个包中都是相关文件的集合，以及它们之间以模块形式存在的依赖说明。

A package is defined as a directory containing a file named Android.bp, residing beneath the top-level directory in the build and its name is its path relative to the top-level directory. A package includes all files in its directory, plus all subdirectories beneath it, except those which themselves contain an Android.bp file.
【译】包被定义为包含一个名为Android.bp文件的目录，位于构建中的顶级目录下，其名称是相对于顶层目录的路径。一个包包括其目录下的所有文件，以及它下面的所有子目录，除了那些本身包含Android.bp文件的。

The modules in a package’s Android.bp and included files are part of the module.
【译】包的Android.bp中声明的模块和包含的文件是模块的一部分。

For example, in the following directory tree (where .../android/ is the top-level Android directory) there are two packages, my/app, and the subpackage my/app/tests. Note that my/app/data is not a package, but a directory belonging to package my/app.
【译】例如，在下面的目录树中（.../android/是Android的顶层路径)有两个包my/app，和一个子包my/app/test。注意：my/app/data不是包，而是属于my/app包的目录。

.../android/my/app/Android.bp
.../android/my/app/app.cc
.../android/my/app/data/input.txt
.../android/my/app/tests/Android.bp
.../android/my/app/tests/test.cc

This is based on the Bazel package concept.
【译】这是基于Bazel package概念。

The package module type allows information to be specified about a package. Only a single package module can be specified per package and in the case where there are multiple .bp files in the same package directory it is highly recommended that the package module (if required) is specified in the Android.bp file.
【译】package模块类型允许指定有关包的信息。每个包只能指定一个package模块，在同一个包目录下有多个.bp文件的情况下，强烈建议在Android.bp文件中指定package模块（如果需要的话)。

Unlike most module type package does not have a name property. Instead the name is set to the name of the package, e.g. if the package is in top/intermediate/package then the package name is //top/intermediate/package.
【译】与大多数模块类型不同，package没有name属性。相反，name被设置为包的名称，例如，如果包位于top/intermediate/package中，则包名为//top/intermediate/package。

E.g. The following will set the default visibility for all the modules defined in the package and
any subpackages that do not set their own default visibility (irrespective of whether they are in
the same .bp file as the package module) to be visible to all the subpackages by default.
【译】如下将为包中定义的所有模块和任何没设置其默认可见性（不管它们在同一个.bp文件中是否作为package模块）的子包设置默认可见性为默认对所有子包可见。

package {
    default_visibility: [":__subpackages__"]
}

Referencing Modules

A module libfoo can be referenced by its name
【译】一个模块libfoo可以通过名字被引用:

cc_binary {
    name: "app",
    shared_libs: ["libfoo"],
}

Obviously, this works only if there is only one libfoo module in the source tree. Ensuring such name uniqueness for larger trees may become problematic. We might also want to use the same name in multiple mutually exclusive subtrees
(for example, implementing different devices) deliberately in order to describe a functionally equivalent module. Enter Soong namespaces.
【译】显然，这只在源码树种只有一个libfoo模块时才有效。对于大型树来确保名称的唯一性可能会成为问题。我们可能也希望在多个相互排斥的子树（例如，实现不同的设备）中有意使用相同的名称以描述功能等效的模块。

Namespaces

The presence of the soong_namespace {..} in an Android.bp file defines a
namespace. For instance, having
【译】Android.bp文件中soong_namespace {..}出现的地方定义了一个命名空间。例如:

soong_namespace {
    ...
}
...

in device/google/bonito/Android.bp informs Soong that within the device/google/bonito package the module names are unique, that is, all the modules defined in the Android.bp files in the device/google/bonito/ tree have unique names. However, there may be modules with the same names outside device/google/bonito tree. Indeed, there is a module "pixelstats-vendor"
both in device/google/bonito/pixelstats and in device/google/coral/pixelstats.
【译】在device/googloe/bonito/Android.bp告诉Soong在device/google/bonito包中模块名时唯一的，也就是说Android.bp文件中定义的模块在device/google/bonito/这棵树中有唯一的名称。然而，在device/google/bonito树之外可能有相同名称的模块。事实上，在device/google/bonito/pixelstats和device/google/coral/pixelstats都有一个模块"pixelstats-vendor"。

The name of a namespace is the path of its directory. The name of the namespace in the example above is thus device/google/bonito.
【译】命名空间的名称是其所在目录的路径。在上面的例子中命名空间的名称是device/google/bonito。

An implicit global namespace corresponds to the source tree as a whole. It has empty name.
【译】隐式的全局命名空间对应于整个源代码树。它的名字是空的。

A module name’s scope is the smallest namespace containing it. Suppose a source tree has device/my and device/my/display namespaces. If libfoo module is defined in device/my/display/lib/Android.bp, its namespace is device/my/display.
【译】模块名的**作用域(scope)**是包含它的最小命名空间。假设一个源码树有device/my和device/my/display命名空间，如果libfoo模块定义于device/my/display/lib/Android.bp，它的命名空间是device/my/display。

The name uniqueness thus means that module’s name is unique within its scope. In other words, “//scope:name” is globally unique module reference, e.g, "//device/google/bonito:pixelstats-vendor". Note that the name of the namespace for a module may be different from module’s package name: libfoo belongs to device/my/display namespace but is contained in device/my/display/lib package.
【译】因此，名称唯一性意味着模块的名称在其作用域中是唯一的。换句话说，"//scope:name"是全局唯一的模块引用，例如"//device/google/bonito:pixelstats-vendor". _注意：_一个模块的命名空间名字可能与模块的包名不同：libfoo属于device/my/display命名空间，但是在device/my/display/lib包中。

Name Resolution

The form of a module reference determines how Soong locates the module.
【译】模块引用的形式决定了Soong如何定位模块。

For a global reference of the “//scope:name” form, Soong verifies there is a namespace called “scope”, then verifies it contains a “name” module and uses it. Soong verifies there is only one “name” in “scope” at the beginning when it parses Android.bp files.
【译】对于"//scope:name"形式的全局引用，Soong确认存在一个名为"scope"的命名空间，然后确认其包含一个"name"模块并使用它。当Soong解析Android.bp文件时，确认"scope"里只有一个"name"。

A local reference has “name” form, and resolving it involves looking for a module “name” in one or more namespaces. By default only the global namespace is searched for “name” (in other words, only the modules not belonging to an explicitly defined scope are considered). The imports attribute of the soong_namespaces allows to specify where to look for modules . For instance, with device/google/bonito/Android.bp containing
【译】本地引用具有"name"形式，对其进行解析需要在一个或多个命名空间中查找模块"name"。默认情况下，只在全局命名空间搜索"name"(换句话说，只考虑不属于显示定义范围的模块)。soong_namespaces的imports属性允许指定在哪里查找模块。例如，device/google/bonito/Android.bp包含如下：

soong_namespace {
    imports: [
        "hardware/google/interfaces",
        "hardware/google/pixel",
        "hardware/qcom/bootctrl",
    ],
}

a reference to "libpixelstats" will resolve to the module defined in hardware/google/pixel/pixelstats/Android.bp because this module is in hardware/google/pixel namespace.
【译】引用"libpixelstats"将解析为hardware/google/pixel/pixelstats/Android.bp中定义的这个模块，因为这个模块在hardware/google/pixel命令空间。

TODO: Conventionally, languages with similar concepts provide separate constructs for namespace definition and name resolution (namespace and using in C++, for instance). Should Soong do that, too?
【译】TODO: 通常，具有类似概念的语言为namespace定义和名称提供单独的结构（例如，C++中的namespace和using)。Soong也应该这么做吗？

Referencing modules in makefiles

While we are gradually converting makefiles to Android.bp files, Android build is described by a mixture of Android.bp and Android.mk files, and a module defined in an Android.mk file can reference a module defined in Android.bp file. For instance, a binary still defined in an Android.mk file may have a library defined in already converted Android.bp as a dependency.
【译】虽然我们正在逐步将makefiles转换为Android.bp文件，但Android构建是由Android.bp和Android.mk文件混合描述的，并且Android.mk文件中定义的模块可以引用Android.bp文件中定义的模块。例如，一个binary依旧在Android.mk文件中定义，可能有一个依赖的库定义于Android.bp。

A module defined in an Android.bp file and belonging to the global namespace can be referenced from a makefile without additional effort. If a module belongs to an explicit namespace, it can be referenced from a makefile only after after the
name of the namespace has been added to the value of PRODUCT_SOONG_NAMESPACES variable.
【译】定义于Android.bp中的模块，属于全局命名空间，可以从makefile中引用而不需要额外处理。如果模块属于明确的命名空间，它只有在其命名空间已经添加到PRODUCT_SOONG_NAMESPACE环境变量了，才能从makefile中引用。

Note that makefiles have no notion of namespaces and exposing namespaces with the same modules via PRODUCT_SOONG_NAMESPACES may cause Make failure. For instance, exposing both device/google/bonito and device/google/coral namespaces will cause Make failure because it will see two targets for the pixelstats-vendor module.
【译】注意：makefile没有命名空间的概念，通过PRODUCT_SOONG_NAMESPACES暴露相同模块的命名空间可能会导致Make失败。例如，暴露device/google/bonito和’device/google/coral命名空间将导致Make失败，因为对于pixelstats-vendor`模块来说将看到两个目标。

Visibility

The visibility property on a module controls whether the module can be used by other packages. Modules are always visible to other modules declared in the same package. This is based on the Bazel visibility mechanism.
【译】模块的visibility属性(property)控制着这个模块(module)是否能被其他包(package)使用。基于Bazel可见性机制，模块对于同一个包中声明的其他模块总是可见的。

If specified the visibility property must contain at least one rule.
【译】如果指定了visibility属性，它必须包含至少一条规则(rule)。

Each rule in the property must be in one of the following forms:
【译】每条属性规则必须是如下形式中的一种：

• ["//visibility:public"]: Anyone can use this module. //任何人可以使用该模块
• ["//visibility:private"]: Only rules in the module’s package (not its subpackages) can use this module. //只有该module’s package(not its subpackages)里的rules可以使用这个模块。
• ["//visibility:override"]: Discards any rules inherited from defaults or a creating module. Can only be used at the beginning of a list of visibility rules. //丢弃从defaults继承的任何规则或者创建一个新模块。只能用于列表的开头的可见性规则。
• ["//visibility:any_partition"]: Any modules of type android_filesystem or android_system_image can use this module. Intended for modules that no one should link against, but should still be included in soong-built partitions. //任何android_filesystem或者android_system_image类型的模块都可以使用该模块。用于没有被链接的模块，但仍然应该包含在soong-built分区中。
• ["//some/package:__pkg__", "//other/package:__pkg__"]: Only modules in some/package and other/package (defined in some/package/.bpandother/package/.bp) have access to this module. Note that sub-packages do not have access to the rule; for example, //some/package/foo:baror//other/package/testing:blawouldn't have access.pkg is a special module and must be used verbatim. It represents all of the modules in the package. //只有some/packageandother/package (some/package/.bpandother/package/.bp中定义的)中的模块可以访问该模块。注意：sub-packages不能访问这个rule；例如，//some/package/foo:bar 或//other/package/testing:bla 没有访问权限。pkg` 是一个特殊的module, 必须be used verbatim。它代表package中的所有modules。
• ["//project:__subpackages__", "//other:__subpackages__"]: Only modules in packages project or other or in one of their sub-packages have access to this module. For example, //project:rule, //project/library:lib or //other/testing/internal:munge are allowed to depend on this rule (but not //independent:evil) //只有 project 或 other或它们的sub-packages中的模块可以访问这个module。例如，//project:rule, //project/library:lib或//other/testing/internal:munge允许依赖这个rule（但不是//independent:evil）。
• ["//project"]: This is shorthand for ["//project:__pkg__"] //这是 ["//project:__pkg__"]的简写形式。
• [":__subpackages__"]: This is shorthand for ["//project:__subpackages__"] where //project is the module’s package, e.g. using [":__subpackages__"] in packages/apps/Settings/Android.bp is equivalent to //packages/apps/Settings:__subpackages__. //这是 ["//project:__subpackages__"]的简写形式。这里//project是module’s package, 例如，packages/apps/Settings/Android.bp 中使用[":__subpackages__"]和使用//packages/apps/Settings:__subpackages__是等价的。
• ["//visibility:legacy_public"]: The default visibility, behaves as //visibility:public for now. It is an error if it is used in a module. //是默认的可见性，目前表现为//visibility:public。如果在module中使用是错误的。

The visibility rules of //visibility:public and //visibility:private cannot be combined with any other visibility specifications, except //visibility:public is allowed to override visibility specifications imported through the defaults property.
【译】//visibility:public和//visibility:private 的可见性规则不能与任何其他可见性规则结合使用，除非//visibility:public可以覆盖通过defaults属性导入的可见性规则。

Packages outside vendor/ cannot make themselves visible to specific packages in vendor/, e.g. a module in libcore cannot declare that it is visible to say vendor/google, instead it must make itself visible to all packages within vendor/ using //vendor:__subpackages__.
【译】vendor/之外的包不能让自己对vendor/中指定的包可见，例如， libcore中的module不能声明其可见性为 vendor/google，相反，它必须用//vendor:__subpackages__使自己对vendor/中的all packages可见，

If a module does not specify the visibility property then it uses the default_visibility property of the package module in the module’s package.
【译】如果模块没有明确指定visibility属性那么它将使用该模块包中package 模块的default_visibility属性。

If the default_visibility property is not set for the module’s package then it will use the default_visibility of its closest ancestor package for which a default_visibility property is specified.
【译】如果没有为模块的包设置default_visibility属性，那么它将使用其最近的指定了 default_visibility属性的祖先包的 default_visibility属性。

If no default_visibility property can be found then the module uses the global default of //visibility:legacy_public.
【译】如果找不到 default_visibility属性，那么模块将使用全局默认的//visibility:legacy_public.

The visibility property has no effect on a defaults module although it does apply to any non-defaults module that uses it. To set the visibility of a defaults module, use the defaults_visibility property on the defaults module; not to be confused with the default_visibility property on the package module.
【译】 visibility属性对default module没有影响，尽管它适用于任何使用它的non-defaults module；不要和包模块上的 default_visibility 混淆。

Once the build has been completely switched over to soong it is possible that a global refactoring will be done to change this to //visibility:private at which point all packages that do not currently specify a default_visibility property will be updated to have default_visibility = [//visibility:legacy_public] added. It will then be the owner’s responsibility to replace that with a more appropriate visibility.
【译】一旦构建完全切换到soong，可能会全局重构，将其更改为 //visibility:private ，此时所有当前未指定default_visibility属性的包将被更新添加default_visibility = [//visibility:legacy_public]。然后，所有者有责任用更合适的可见性来取代它。

Formatter //格式化程序

Soong includes a canonical formatter for Android.bp files, similar to gofmt. To recursively reformat all Android.bp files in the current directory:
【译】Soong包含一个用于Android.bp文件规范格式化程序，类似于gofmt。若要递归地重新格式化当前目录中所有Android.bp文件：

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.
【译】规范格式包括4个空格缩进，多元素列表的每个元素后面都有换行符，以及在列表和映射中总是保留尾部的逗号。

Convert Android.mk files //转换Android.mk文件

Soong includes a tool perform a first pass at converting Android.mk files
to Android.bp files:
【译】Soong包含一个工具，可初步将Android.mk文件转成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.
【译】该工具可转换变量、模块、注释及部分条件语句，但任何自定义的Makefile规则、复杂的条件语句或额外包含文件必须手动转换。

Differences between Android.mk and Android.bp //Android.mk和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.
  【译】* Android.mk文件中经常出现多个同名模块（例如库的静态版本和共享版本，或者主机和设备版本）。而Android.bp文件要求每个模块必须具有唯一的名称，但单个模块可以通过多种变体进行构建，例如添加 host_supported: true属性。androidmk转换工具会生成多个冲突的模块，此时需要手动通过target: { android: { }, host: { } }代码块来区分不同构建目标的差异，将它们整合为单一模块。

Conditionals //条件语句

Soong deliberately does not support most conditionals in Android.bp files. We suggest removing most conditionals from the build. See Best Practices for some examples on how to remove conditionals.

Most conditionals supported natively by Soong are converted to a map property. When building the module one of the properties in the map will be selected, and its values appended to the property with the same name at the top level of the module.

For example, to support architecture specific files:
【译】Soong在设计上有意不支持在Android.bp文件中有大多数条件语句。我们建议从构建系统中移除绝大多数条件逻辑。关于如何移除条件语句的示例，请参阅Best Practices。
Soong原生支持的大多数条件语句会被转换为映射属性。在构建模块时，系统将选择其中的某个属性，并将其值追加到模块顶层同名属性中。
例如，为实现架构特定文件的配置：

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

When building the module for arm the generic.cpp and arm.cpp sources will
be built. When building for x86 the generic.cpp and ‘x86.cpp’ sources will
be built.

【译】在构建针对ARM架构的模块时，将编译generic.cpp和 arm.cpp源代码文件；在为x86架构构建时，则会编译generic.cpp和’x86.cpp’ 源代码文件。

Soong Config Variables //Soong配置变量

When converting vendor modules that contain conditionals, simple conditionals can be supported through Soong config variables using soong_config_* modules that describe the module types, variables and possible values:
【译】在转换包含条件语句的供应商模块时，可通过Soong配置变量支持简单条件语句。这需要借助描述模块类型、变量及可能值的 soong_config_*模块来实现：

soong_config_module_type {
    name: "acme_cc_defaults",
    module_type: "cc_defaults",
    config_namespace: "acme",
    variables: ["board"],
    bool_variables: ["feature"],
    list_variables: ["impl"],
    value_variables: ["width"],
    properties: ["cflags", "srcs"],
}

soong_config_string_variable {
    name: "board",
    values: ["soc_a", "soc_b", "soc_c"],
}

This example describes a new acme_cc_defaults module type that extends the cc_defaults module type, with four additional conditionals based on variables board, feature, impl and width which can affect properties cflags and srcs. The four types of soong variables control properties in the following ways.

• bool variable (e.g. feature): Properties are applied if set to true.
• list variable (e.g. impl): (lists of strings properties only) Properties are
  applied for each value in the list, using %s substitution. For example, if
  the property is ["%s.cpp", "%s.h"] and the list value is foo bar,
  the result is ["foo.cpp", "foo.h", "bar.cpp", "bar.h"].
• value variable (e.g. width): (strings or lists of strings) The value are
  directly substituted into properties using %s.
• string variable (e.g. board): Properties are applied only if they match the
  variable’s value.
  【译】该示例描述了一种新的模块类型acme_cc_defaults，它扩展了cc_defaults模块类型，新增了基于变量board, feature, impl 和width的四类条件逻辑。这些变量通过以下方式影响属性cflags 和 srcs：
• 布尔变量（如feature)：设置为true时，属性将被应用。
• 列表变量（如impl)：（仅作用于字符串列表属性）这些属性会应用到列表中的每个值上，通过%s占位符进行替换。例如，若属性为["%s.cpp", "%s.h"] 且列表值为foo bar则生成结果为["foo.cpp", "foo.h", "bar.cpp", "bar.h"]。
• 值变量（如width)：（作用域字符串或字符串列表)该值会直接通过%s替换到属性中。
• 字符串变量（如board)：仅当属性值与变量值匹配时，才会应用这些属性。

Additionally, each conditional containing a conditions_default property can
affect cflags and srcs in the following conditions:

• bool variable (e.g. feature): the variable is unspecified or not set to true
• list variable (e.g. impl): the variable is unspecified
• value variable (e.g. width): the variable is unspecified
• string variable (e.g. board): the variable is unspecified or the variable is set to a string unused in the given module. For example, with board, if the board conditional contains the properties soc_a and conditions_default, when board is soc_b, the cflags and srcs values under conditions_default is used. To specify that no properties should be amended for soc_b, you can set soc_b: {},.
  【译】此外，每个包含conditions_default属性的条件语句可通过以下情况影响cflags 和 srcs :
• 布尔变量(如feature)：该变量未指定或未设为true时
• 列表变量（如impl)：该变量未指定时
• 值变量（如width)：该变量未指定时
• 字符串变量（如board）：该变量未指定，或变量被设置为当前模块未使用的字符串时。例如，对于board变量，如果 board 条件包含soc_a 和 conditions_default属性，当 board值为soc_b时，将使用conditions_default下面的cflags 和 srcs 值。如需明确不对soc_b添加属性，可设置soc_b: {},

The values of the variables can be set from a product’s BoardConfig.mk file:
【译】各变量的值可通过产品的BoardConfig.mk文件进行设置：

$(call soong_config_set,acme,board,soc_a)
$(call soong_config_set,acme,feature,true)
$(call soong_config_set,acme,impl,foo.cpp bar.cpp)
$(call soong_config_set,acme,width,200)

The acme_cc_defaults module type can be used anywhere after the definition in the file where it is defined, or can be imported into another file with:
【译】acme_cc_defaults模块类型可在其定义文件中的定义之后的任何位置使用，也可以通过以下方式导入其他文件中使用：

soong_config_module_type_import {
	from: "device/acme/Android.bp",
	module_types: ["acme_cc_defaults"],
}

It can used like any other module type:
【译】它可以像其他任何模块类型一样使用：

acme_cc_defaults {
    name: "acme_defaults",
    cflags: ["-DGENERIC"],
    soong_config_variables: {
        board: {
            soc_a: {
                cflags: ["-DSOC_A"],
            },
            soc_b: {
                cflags: ["-DSOC_B"],
            },
            conditions_default: {
                cflags: ["-DSOC_DEFAULT"],
            },
        },
        feature: {
            cflags: ["-DFEATURE"],
            conditions_default: {
                cflags: ["-DFEATURE_DEFAULT"],
            },
        },
        width: {
            cflags: ["-DWIDTH=%s"],
            conditions_default: {
                cflags: ["-DWIDTH=DEFAULT"],
            },
        },
        impl: {
            srcs: ["impl/%s"],
            conditions_default: {
                srcs: ["impl/default.cpp"],
            },
        },
    },
}

cc_library {
    name: "libacme_foo",
    defaults: ["acme_defaults"],
    srcs: ["*.cpp"],
}

With the BoardConfig.mk snippet above, libacme_foo would build with cflags: "-DGENERIC -DSOC_A -DFEATURE -DWIDTH=200" and srcs: ["*.cpp", "impl/foo.cpp", "impl/bar.cpp"].

Alternatively, with DefaultBoardConfig.mk:
【译】基于上述BoardConfig.mk配置片段，libacme_foo模块将使用cflags: "-DGENERIC -DSOC_A -DFEATURE -DWIDTH=200"和srcs: ["*.cpp", "impl/foo.cpp", "impl/bar.cpp"]编译构建。

或者，使用DefaultBoardConfig.mk:

SOONG_CONFIG_NAMESPACES += acme
SOONG_CONFIG_acme += \
    board \
    feature \
    impl \
    width \

SOONG_CONFIG_acme_feature := false

Alternatively, with DefaultBoardConfig.mk:

SOONG_CONFIG_NAMESPACES += acme
SOONG_CONFIG_acme += \
    board \
    feature \
    impl \
    width \

SOONG_CONFIG_acme_feature := false

then libacme_foo would build with cflags: "-DGENERIC -DSOC_DEFAULT -DFEATURE_DEFAULT -DSIZE=DEFAULT" and srcs: ["*.cpp", "impl/default.cpp"].

Alternatively, with DefaultBoardConfig.mk:
【译】然后 libacme_foo将使用cflags: "-DGENERIC -DSOC_DEFAULT - DFEATURE_DEFAULT -DSIZE=DEFAULT"和srcs: ["*.cpp", "impl/default.cpp"]构建参数进行构建。
或者，使用DefaultBoardConfig.mk:

SOONG_CONFIG_NAMESPACES += acme
SOONG_CONFIG_acme += \
    board \
    feature \
    impl \
    width \

SOONG_CONFIG_acme_board := soc_c
SOONG_CONFIG_acme_impl := baz

then libacme_foo would build with cflags: "-DGENERIC -DSOC_DEFAULT - DFEATURE_DEFAULT -DSIZE=DEFAULT" and srcs: ["*.cpp", "impl/default.cpp"].

Alternatively, with DefaultBoardConfig.mk:
【译】然后libacme_foo 将使用cflags: "-DGENERIC -DSOC_DEFAULT -DFEATURE_DEFAULT -DSIZE=DEFAULT" 和 srcs: ["*.cpp", "impl/baz.cpp"]构建参数进行构建。

SOONG_CONFIG_NAMESPACES += acme
SOONG_CONFIG_acme += \
    board \
    feature \
    impl \
    width \

SOONG_CONFIG_acme_board := soc_c
SOONG_CONFIG_acme_impl := baz

soong_config_module_type modules will work best when used to wrap defaults modules (cc_defaults, java_defaults, etc.), which can then be referenced by all of the vendor’s other modules using the normal namespace and visibility rules.
【译】soong_config_module_type模块在用于封装默认模块（如cc_defaults, java_defaults等）时，效果最佳。随后，供应商的所有其他模块都可以使用标准的命名空间和可见性规则来引用这些封装后的默认模块。
soong_config_module_type modules will work best when used to wrap defaults modules (cc_defaults, java_defaults, etc.), which can then be referenced by all of the vendor’s other modules using the normal namespace and visibility rules.

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 ninja build file.
【译】该构建逻辑使用blueprint框架以Go语言编写。构建逻辑接收通过反射机制解析到Go结构体中的模块定义，并生成构建规则。这些构建规则由blueprint框架收集，并写入ninja 构建文件。

Environment Variables Config File //环境变量配置文件

Soong can optionally load environment variables from a pre-specified configuration file during startup. These environment variables can be used to control the behavior of the build. For example, these variables can determine whether remote-execution should be used for the build or not.
【译】Soong在启动时可以从预设配置文件中加载环境变量。这些环境变量可用于控制构建行为。例如，这些环境变量决定是否在构建中使用远程执行。

The ANDROID_BUILD_ENVIRONMENT_CONFIG_DIR environment variable specifies the directory in which the config file should be searched for. The
ANDROID_BUILD_ENVIRONMENT_CONFIG variable determines the name of the config file to be searched for within the config directory. For example, the following
build comand will load ENV_VAR_1 and ENV_VAR_2 environment variables from
the example_config.json file inside the build/soong directory.
【译】ANDROID_BUILD_ENVIRONMENT_CONFIG_DIR这个环境变量用于指定配置文件的搜索路径。ANDROID_BUILD_ENVIRONMENT_CONFIG环境变量则决定在该配置目录中要查找的配置文件名。例如，以下构建命令将从build/soong目录下的example_config.json文件中加载ENV_VAR_1 和 ENV_VAR_2环境变量：

ANDROID_BUILD_ENVIRONMENT_CONFIG_DIR=build/soong \
  ANDROID_BUILD_ENVIRONMENT_CONFIG=example_config \
  build/soong/soong_ui.bash

Other documentation //其他文档

• Best Practices
• Build Performance
• Generating CLion Projects
• Generating YouCompleteMe/VSCode compile_commands.json file
• Make-specific documentation: build/make/README.md

Developing for Soong //为Soong，开发中

To load the code of Soong in IntelliJ:

• File -> Open, open the build/soong directory. It will be opened as a new
  project.
• File -> Settings, then Languages & Frameworks -> Go -> GOROOT, then set it to
  prebuilts/go/linux-x86
• File -> Project Structure, then, Project Settings -> Modules, then Add
  Content Root, then add the build/blueprint directory.
• Optional: also add the external/golang-protobuf directory. In practice,
  IntelliJ seems to work well enough without this, too.

Running Soong in a debugger //在调试器中运行Soong

Both the Android build driver (soong_ui) and Soong proper (soong_build) are
Go applications and can be debugged with the help of the standard Go debugger
called Delve. A client (e.g., IntelliJ IDEA) communicates with Delve via IP port that Delve listens to (the port number is passed to it on invocation).
【译】Android build driver(soong_ui)和Soong核心组件 (soong_build) 均为Go语言应用程序，可通过标准的Go调试器Delve进行调试。客户端(例如, IntelliJ IDEA) 通过Delve监听的IP端口与Delve通信（该端口号在启动Delve时作为参数传入）。

Debugging Android Build Driver #### //调试Android Build Driver

To make soong_ui wait for a debugger connection, use the SOONG_UI_DELVE
variable:

SOONG_UI_DELVE=5006 m nothing

Debugging Soong Proper

To make soong_build wait for a debugger connection, install dlv and then
start the build with SOONG_DELVE= in the environment.
For example:

SOONG_DELVE=5006 m nothing

Android build driver invokes soong_build multiple times, and by default each
invocation is run in the debugger. Setting SOONG_DELVE_STEPS controls which
invocations are run in the debugger, e.g., running

SOONG_DELVE=2345 SOONG_DELVE_STEPS='build,modulegraph' m

results in only build (main build step) and modulegraph being run in the debugger.
The allowed step names are bp2build_files, bp2build_workspace, build,
modulegraph, queryview, soong_docs.

Note setting or unsetting SOONG_DELVE causes a recompilation of soong_build. This
is because in order to debug the binary, it needs to be built with debug
symbols.