settings.gradle 文件详解

此文件用于声明需要参与Build的项目。

Declares the configuration required to instantiate and configure the hierarchy of {@link org.gradle.api.Project} instances which are to participate in a build.

每个Settings对象和settings文件是一一对应的，Gradle在编译前会将Settings对象实例化并解析对应的setting文件。

There is a one-to-one correspondence between a Settings instance and a {@value #DEFAULT_SETTINGS_FILE} settings file. Before Gradle assembles the projects for a build, it creates a Settings instance and executes the settings file against it.

settings文件（原注释中为Settings对象）的一个作用是用来声明你需要build的项目。开发者可通过include(String… args)的方法将需要Build的项目添加至编译项目中。在编译过程中有个默认的根项目会自动添加至编译目录中，根项目是指包含了settings文件的项目，根项目的名称默认使用包含了settings文件所在目录的名称。

One of the purposes of the Settings object is to allow you to declare the projects which are to be included in the build. You add projects to the build using the {@link #include(String...)} method. There is always a root project included in a build. It is added automatically when the Settings object is created. The root project's name defaults to the name of the directory containing the settings file. The root project's project directory defaults to the directory containing the settings file.

在settings.gradle文件中我们常用的方法有
include(String… projectPaths)
includeFlat(String… projectNames)
project(String path)

（1）include(String… projectPaths)方法

此方法用于将项目添加至编译项目中。此方法为可变参方法，故可一次配置多个项目，参数中的项目都将被编译。此处参数格式用于说明参数项目在项目层级（有的文章中翻译为项目树，我感觉这个翻译比较贴切）中的位置，每个项目的参数不是文件路径格式的。参数的形式也比较容易记忆，我们只需将项目相对路径中“/”或“\”替换为“:”即可，此相对路径一般为根项目的相对路径。路径分隔符“:”由Project接口定义
/**
* The hierarchy separator for project and task path names.
*/
String PATH_SEPARATOR = “:”;

Adds the given projects to the build. Each path in the supplied list is treated as the path of a project to add to the build. Note that these path are not file paths, but instead specify the location of the new project in the project hierarchy. As such, the supplied paths must use the ':' character as separator (and NOT '/').

每个参数中最后一个“:”后的字符串将被当做项目的名称。在编译过程中查找项目文件会将参数路径转化为项目根目录的相对路径，如inculde("：a:b")这样配置，build时会把路径rootDir/a/b当作项目的路径。项目的文件路径是可以改变的，我们可以通过projectDir属性去改变一个项目的文件路径。例如
include ‘:baz’
project(’:baz’).projectDir = file(‘foo/baz’)
此例中将baz项目的文件路径设置为$rootDir/foo/baz,若不进行配置则使用默认路径$rootDir/baz。
由上例我们也能看出为什么在参数中不使用文件分隔符而使用":"作为路径分隔符的原因。如果我们include方法的参数中使用文件分隔符时当我们修改项目文件则会导致语义上的分歧。
（2）includeFlat(String… projectNames)

此方法与上一个方法类似，只不过不使用根项目路径作为项目文件路径的起点，而是使用根项目目录的上级目录作为项目文件路径的起点。
如根项目路径为E:/projects/demo1,在E:/projects/下包含项目demo2，demo3,则可以通过
includeFlat(’:demo2’)
includeFlat(’:demo3’)
将demo2及demo3加入至项目的Build中。在编译期间demo2及demo3的文件路径将被识别为
E:/projects/demo2及E:/projects/demo3。
若使用
include(’:demo2’)
include(’:demo3’)
在编译时将在E:/projects/demo1/demo2及E:/projects/demo1/demo3中查找这两个项目。
(3)project(String path)

此方法用于获取项目路径对应的ProjectDescriptor对象，ProjectDescriptor类用于配置项目，在上例中我们看到了使用projectDir属性配置项目的文件路径。除此外还可以配置项目名称（默认为最后一个冒号后的字符串）、build文件名称。除设置外还有一些项目的只读属性可通过此类获取，如项目path（include时传入的参数值）、项目父级项目、项目子级项目列表。

settings.gradle文件用于配置参与编译的项目树，在编译期间会对每个settings.gradle文件生成一个Settings对象。所有配置在此文件中的项目将参与项目的Build（被Build但不一定会被打包至输出文件中如APK）。直接使用include或includeFlat方法包含项目时将使用默认的规则查找项目文件，可通过ProjectDescriptor对象的projectDir属性配置项目文件的路径。在Android Studio中我们创建一个module时会自动将该module在settings.gradle文件中include进去。如果使用已存在的module我们需手动在settings.gradle文件中配置该项目。