本文介绍了 Android Gradle 的进阶知识。

笔者耗时 8 个月学习、写作，五万字长文总结，带你了解 Gradle 提供的功能。

阅前提示

阅读本文前需知晓的几个点：

• 本文档不是面向小白的文档，而是适用于有过一定 Gradle 使用经验的开发者阅读。关于 Gradle 的基础知识点的讲解文档，可以自行上网搜索。

• 本文并不会讲解 Gradle 的所有知识点，会跳过很多知识点。

• 文本并不是 Gradle API 说明文档，只是一篇功能说明文档。主要目的是阐述 Gradle 具有哪些功能，方便我们编写代码时，可以快速判断适不适合用 Gradle；或者看到一些 Gradle 方法、术语时，不用再十分茫然，发出这是啥的疑问。至于具体的功能怎么实现的，具体的代码该怎么写，本文可能不会详细阐述。

• 本文基本不会涉及 AGP(Android Gradle Plugin) 的内容，基本只会讲 Gradle 的知识点

• 本文的示例代码，存在 Groovy 和 kts 混用的情况，主要是为了凸显出差异。推荐优先使用 kts 开发，方便代码更易于阅读、理解以及调试

• 不同版本的 Gradle，差异很大。基本可以看作是破坏式更新。本文主要以 Gradle 7.3.3 版本为基础，对 Gradle 的知识点进行讲解，低版本的功能可能和当前版本存在较大差异。请大家谨慎阅读

概述

Android 项目使用 Gradle 构建、管理项目。Gradle 是一个基于 JVM 的构建工具。对于使用者而言，其主要有以下两个方面的特点：

1. 可以看作是一个工具。因为我们主要执行是使用 Gradle 进行编译。

2. 可以看作是基于 java、groovy、kotlin 等语言的一个三方库或者一个框架。因为在日常使用中，我们主要是编写 gradle 脚本，gradle 脚本又主要是定义任务(Task)、实现插件(Plugin)、编写 build 配置(Configuration)。

Gradle 的两个特点其实并不冲突。相反，是有紧密联系的。首先 Gradle 可以看作工具，是因为 Gradle 提供了对应的能力；而 Gradle 具有的能力，是我们通过任务、插件实现的。所以学习 Gradle，本质上是要学习 Gradle 提供的能力，以及如何自定义能力。

本文便从将 Gradle 视为三方库的角度，对 Gradle 的相关知识进行介绍。文章主要涉及到 Project、Gradle、Settings、Task、Configuratin、Plugin 等几个类的讲解。其中 Project 类贯穿全文。

Gradle 项目结构

Gradle 的常见的项目结构如下：

针对图片中的内容，做以下几点说明：

• 在 gradle 中，一个具有 build.gradle 文件的目录，可以看作是一个项目目录，gradle 会为其生成一个 project 对象。即一个 project 对象对应一个 build.gradle 文件

• 一个项目可以有上级项目与子项目，如上图，module A 文件夹具有上级目录"项目目录"，“项目目录"也有子目录"module A 文件夹”，而"项目目录"本身代表的是根项目。反应到 Gradle 中的定义就是，“项目目录"代表 root project，也代表 module A 的 parent project，而 module A 则是 “项目目录” 的 child project

• 每个 Gradle 项目都有一个 gradle 文件夹，里面是 wrapper 目录，wrapper 目录里有 gradle-wrapper.jar 文件和 gradle-wrapper.properties 文件。我们需要重点关注 gradle-wrapper.properties 文件，gradle-wrapper.jar 文件我们可以不用太关注。针对 gradle-wrapper.properties 文件，作两点说明：

  1. 文件中可以设置一个 distributionUrl 属性。该属性决定了当前项目导入的 Gradle 的版本。以 distributionUrl=https://services.gradle.org/distributions/gradle-7.3.3-all.zip 为例。通常我们只需要关注标黄的部分即可

     • 7.3.3 代表了当前项目我们使用的 Gradle 的版本。注意此版本应该和 Android Gradle Plugin 的版本匹配。具体可见官方说明：Android Gradle 插件版本说明

     • all 代表了我们引入的是有源码的版本的。此处通常可选两个值：bin/all。bin代表引入的是编译后的 Gradle 版本，此版本仅有 Gradle 被编译成二进制代码后的 class 文件，反编译后，是看不到类的注释的，也无法执行类的跳转。而 all 版本除了导入 class 文件外，还导入了 Gradle 工具的 java 源码，我们可以查看对应的类的注释，以及执行类之间的跳转

     • 有时设置 all 版本之后，也看不到源码。此时可能是因为选择的项目管理工具是 IDEA，而不是 Gradle。此问题在新建项目时需确定好

  2. 文件中可以设置的属性中，有一个 GRADLE_USER_HOME 的变量，代表 gradle 所在的目录。该目录可以在 iead 中设置：

     

• 每一个 Gradle 项目，都会有一个 settings.gradle 文件，该文件全局唯一，对应一个 Settings 对象，用于指定相关信息，包括根项目、参与编译的项目(include build)等。该文件里的内容是 Gradle 项目编译时，最先执行的内容

  

• 在 Gradle 的根项目下，有 gradlew 和 gradlew.bat 两个文件，这是系统脚本文本，用于启动 Gradle 编译，分别对应 Linux 和 Windows 系统的脚本

• Gradle 中可以使用 buildSrc 做一些编译时的操作，该目录会被视作一个 include build，但是却并不需要在 settings.gradle 文件中导入(有该目录，gradle 就默认导入)

• Gradle 中，一个接口的实现类，默认以 Default 开头，比如 Gradle 的实现类 DefaultGradle，Settings 的实现类 DefaultSettings

Project 类功能

我们在使用 gradle 的过程中，最核心的一个类就是 Project，它提供了 Gradle 各个能力的入口，每个 build.gradle 文件都会生成一个 project 对象。project 类提供的能力如下。后面我们会逐个分析这些能力：

Gradle 文件操作

注：官方讲解地址： Working With Files

每个 gradle 构建(build)都或多或少会与文件操作打交道。Gradle 提供了一个全面的 API，帮助我们轻松执行所需的文件操作。这些 API 主要分为以下两大部分：

• 指定要处理的文件和目录(Working With Files (gradle.org)深入讲解了此内容)

• 指定需要使用这些文件和目录做什么事(Working With Files (gradle.org)深入讲解此内容)

本文要讲解的 Gradle 的文件操作的知识点如下：

复制文件

Gradle 内置了复制文件的能力，为其配置文件的来源以及目的地，以复制文件。

• 参数的类型可以参考 Project.file 或者 Project.files 支持的参数形式

• Copy.from(java.lang.Object…​) 指定需要复制哪个文件

  1. from 支持声明多个文件参数(即支持多文件复制)，见 copyReportsForArchiving 任务

  2. from 方法可以调用多次，用于指定多个文件。Copy 类有个列表，存储待执行的复制操作，每调用一次 from，就会向List 增加一次数据

• Copy.into(java.lang.Object) 指定复制到哪里

• include 用于指定需要被包含的文件，见 copyPdfReportsForArchiving/copyReportsDirForArchiving2 任务

  • 在 from，into 闭包内使用时，仅对当前闭包生效

  • 参数支持模版指定，具体的可以参阅 PatternFilterable 类

• exclude 用于指定需要被排除的文件

  • 在 from，into 闭包内使用时，仅对当前闭包生效

  • 参数支持模版指定，具体的可以参阅 PatternFilterable 类

• filters 指定过滤文件

• rename 重命名文件

• Gradle 内置的 copy 任务默认会一起复制文件的目录结构

要使用这种能力，一般有两种方式：

• 可以自定义任务，实现 Copy 类。

• 使用 Project.copy(Action) 方法。此方法默认不是增量的(增量编译相关，后面讲解)

tasks.register('copyReport', Copy) {
    from layout.buildDirectory.file("reports/my-report.pdf")
    into layout.buildDirectory.dir("toArchive")
}

tasks.register('copyReport2', Copy) {
    from "$buildDir/reports/my-report.pdf"
    into "$buildDir/toArchive"
}

tasks.register('copyReportsForArchiving', Copy) {
    from layout.buildDirectory.file("rAndroid Plugin DSL Reference
y) {
    from layout.buildDirectory.dir("reports")
    // 此 include 对 task 生效
    include "*.pdf"
    into layout.buildDirectory.dir("toArchive")
}

tasks.register('copyReportsDirForArchiving2', Copy) {
    from(layout.buildDirectory) {
        // 此 include 仅对 from 生效
        include "reports/**"
    }
    into layout.buildDirectory.dir("toArchive")
}

使用 CopySpec 类

CopySpec 可以翻译为复制规范。该规范决定将什么复制到何处，以及在复制过程中文件会发生什么。上面有许多复制和归档任务配置形式的示例。但是 CopySpec 有两个属性值得更详细地介绍。

• CopySpec 可独立于 task。这允许我们在构建中共享 CopySpec

• CopySpec 是有层次的。这允许我们提供更细粒度的控制

共享 CopySpec

假设一个场景：需要将一个包含多个资源的静态网站添加到压缩包中。此时有多个任务用于完成这件事。一项任务可能会将资源复制到本地 HTTP 服务器的文件夹中，而另一项任务可能会将它们打包到发布包中。

我们可以在需要时每次手动指定文件位置和文件包含的内容，但人为设置可能存在潜在风险，从而导致任务之间的不一致。Gradle 提供了一种这个问题的解决方案：Project.copySpec(org.gradle.api.Action) 方法。该方法允许我们在任务配置块之外创建 CopySpec，然后使用 CopySpec.with(org.gradle.api.file.CopySpec…​) 方法将其附加到适当的任务。

以下示例演示了上面的说明：

// 定义在多个 task 中使用的共享 CopySpec
CopySpec webAssetsSpec = copySpec {
    from 'src/main/webapp'
    include '**/*.html', '**/*.png', '**/*.jpg'
    rename '(.+)-staging(.+)', '$1$2'
}

tasks.register('copyAssets', Copy) {
    into layout.buildDirectory.dir("inPlaceApp")
    with webAssetsSpec
}

tasks.register('distApp', Zip) {
    archiveFileName = 'my-app-dist.zip'
    destinationDirectory = layout.buildDirectory.dir('dists')

    from appClasses
    with webAssetsSpec
}

// 定义共享闭包
def webAssetPatterns = {
    include '**/*.html', '**/*.png', '**/*.jpg'
}

tasks.register('copyAppAssets', Copy) {
    into layout.buildDirectory.dir("inPlaceApp")
    from 'src/main/webapp', webAssetPatterns
}

tasks.register('archiveDistAssets', Zip) {
    archiveFileName = 'distribution-assets.zip'
    destinationDirectory = layout.buildDirectory.dir('dists')

    from 'distResources', webAssetPatterns
}

使用子规范

子规范(可以视作补充约束)是在 from() 块或者 into() 块中指定的内容。有几个注意事项：

• root into() 中的内容应指定好，以代表所有复制内容默认的取值。

• 子 CopySpec 会从父级继承目标路径、包含模式、排除模式、复制操作、名称映射和过滤器。配置时需谨慎

tasks.register('nestedSpecs', Copy) {
    into layout.buildDirectory.dir("explodedWar")
    exclude '**/*staging*'
    from('src/dist') {
        include '**/*.html', '**/*.png', '**/*.jpg'
    }
    from(sourceSets.main.output) {
        // WEB-INF/classes 是相对于 explodedWar 的目录
        into 'WEB-INF/classes'
    }
    into('WEB-INF/lib') {
        from configurations.runtimeClasspath
    }
}

在任务中复制文件

在上面的讲解中，复制文件的操作，我们都是定义任务单独进行的。但是存在将复制文件作为任务动作一部分的场景。例如编译任务的众多中间文件。此时我们可以使用 Project.copy(org.gradle.api.Action) 方法进行复制。但是该方法默认不能用于增量编译。

下面的代码描述如何让 Project 的 copy 方法具有增量编译的能力。copyMethodIO 是增量的，其输入来自于 copyTask，输出为 some-dir。虽然方法 copyMethodIO 任务并没有直接改动这些任务，但是 copy 方法使输出发生了改变(copyMethodIO 定义输入输出，copy 使用了输入输出。inputs 和 outputs 可以改变，一改变就能检测到)。此时增量编译检查也能生效。

tasks.register('copyMethodIO') {
    // inputs 的 up-to-date check 增加 copyTask
    // 返回的是 TaskInputFilePropertyBuilder，
    // 属性名为：inputs(第二行代码)
    inputs.files(copyTask)
        .withPropertyName("inputs")
        .withPathSensitivity(PathSensitivity.RELATIVE)
    // outputs 的 up-to-date check 增加 some-dir
    // 返回的是 TaskOutputFilePropertyBuilder
    // 属性名为：outputDir(第二行代码)
    outputs.dir('some-dir')
        .withPropertyName("outputDir")
    doLast{
        copy {
            // 复制 copyTask 的 ouput 到 some-dir
            from copyTask
            into 'some-dir'
        }
    }
}

同步操作

Sync 任务扩展了 Copy 任务。它将源文件复制到目标目录中，然后从目标目录中删除它没有复制的所有文件。换句话说，它将目标目录的内容与其源同步。这对于安装 app、创建解压包或维护项目依赖等操作很有帮助。此外还可以使用 Project.sync(org.gradle.api.Action) 方法在自己的任务中执行相同的功能。

tasks.register('libs', Sync) {
    from configurations.runtime
    into layout.buildDirectory.dir('libs')
}

不记录任务状态

1. 将文件部署到服务器

我们可以使用 Copy 任务部署应用程序归档包(例如 WAR 文件)到服务器。

Copy 单个文件时需要指定 Copy 动作的目标目录，但该目录有时包含不可读的文件，例如命名管道(pipe line)等。当目录包含不可读的文件时，Gradle 在进行 up-to-date 检查(增量编译检查)时可能会遇到问题。为了解决这个问题。我们可以使用 Task.doNotTrackState() 方法不记录任务的状态。换句话说，使用 Task.doNotTrackState() 就抛弃了增量编译的能力，每次任务都会执行。

plugins { id 'war' }

tasks.register("deployToTomcat", Copy) {
    from war
    into layout.projectDirectory.dir('tomcat/webapps')
    doNotTrackState("Deployment directory contains unreadable files")
}

2. 安装可执行文件

构建了一个独立的可执行文件后，我们可以在系统上安装这个文件。安装后它最终会出现在系统对应的路径中(如 Linux系统的 /usr/local/bin 目录)。我们可以使用 Copy 任务将可执行文件复制到对应目录中。但是安装目录中可能包含其他可执行文件，其中一些 Gradle 可能无法读取。为了避免因文件不可读导致的耗时检查(增量编译检查)，我们可以使用 Task.doNotTrackState() 方法。

tasks.register("installExecutable", Copy) {
    from "build/my-binary"
    into "/usr/local/bin"
    doNotTrackState("Installation directory contains unrelated files")
}

删除文件

可以使用 Delete 任务或 Project.delete(org.gradle.api.Action) 方法轻松的删除文件和目录。在这两种情况下，参数与 Project.files(java.lang.Object…​) 方法支持的参数形式相同。

更精细化的删除控制，不是由与 Copy 类似的 include 和 exclude 控制，而是需要使用 FileCollection 和 FileTree 内置的过滤机制。

tasks.register('myClean', Delete) {
    delete buildDir
}
// 删除 src 目录下的 temp 文件
tasks.register('cleanTempFiles', Delete) {
    delete fileTree("src").matching {
        include "**/*.tmp"
    }
}

移动文件

移动目录和文件不是一个常见的要求，应该谨慎使用，因为会丢失信息并且很容易破坏构建。通常最好是复制目录和文件。

Gradle 没有用于移动文件和目录的 API，可以先复制，后删除，达到相同效果。

使用文件

Project.file(java.lang.Object) 方法解析文件。相对路径是相对于项目目录解析的，而绝对路径保持不变。并且无论项目路径如何，该方法都不会返回空文件。注意永远不要使用 new File(relative path) 获取文件，因为这会创建一个相对于当前工作目录 (current working directory，CWD) 的路径。 Gradle 不能保证 CWD 的位置。这意味着依赖于 CWD 的构建(build)随时都有可能中断。方法参数取值如下：

• 一个 CharSequence，包括 String 或 groovy.lang.GString。被视作相对于项目目录的相对路径。以 file: 开头的字符串被视为文件 URL

• 一份文件。如果文件是绝对路径文件，则原样返回。否则被视作相对于项目目录的相对路径

• 一个 java.nio.file.Path 对象，该路径必须与默认 provider 相关联，并以与 File 实例相同的方式处理

• URI 或 java.net.URL。 URL 的路径被解释为文件路径。仅支持 file: 开头的 URL

• org.gradle.api.file.Directory 或 org.gradle.api.file.RegularFile

• 此处任何受支持类型的 Provider。Provider 的值被递归解析

• 一个 org.gradle.api.resources.TextResource 对象

• 返回此处任何支持的类型的 Callable。 call() 方法的返回值被递归解析

• 返回此处任何支持的类型的 Groovy 闭包(Closure)或 Kotlin 函数(Function)。闭包的返回值被递归解析

// 相对路径：字符串和 File 对象
File configFile = file('src/config.xml')
configFile = file(new File('src/config.xml'))
// 使用 java.nio.file.Path 和相对路径
configFile = file(Paths.get('src', 'config.xml'))
// 绝对路径
configFile = file(configFile.absolutePath)
// 使用 java.nio.file.Path 和绝对路径
configFile = file(
    Paths.get(System.getProperty('user.home')
).resolve('global-config.xml')

// 多项目工程中，使用 rootDir 获取绝对路径
configFile = file("$rootDir/shared/config.xml")

创建目录

使用 Project.mkdir(java.lang.Object) 方法创建目录。如果目录已存在，mkdir 不会做任何操作。

tasks.register('ensureDirectory') {
    doLast {
        mkdir "images"
    }
}

重命名文件

Gradle 允许使用 rename() 方法在 Copy 文件时进行重命名。可以使用正则或者闭包匹配。如果想要改名，则返回一个新的文件名，如果不想改变名字，则返回 null。注意在重命名的闭包中，避免耗时操作，因为每个文件复制时都会执行该闭包。以下示例代码为从它的文件名中删除“OEM_BLUE”标记：

// 如 'style_OEM_BLUE_.css' 文件将被重命名为 'style.css'
tasks.register('copyFromStaging', Copy) {
    from "src/main/webapp"
    into layout.buildDirectory.dir('explodedWar')
    // 使用正则表达式匹配名称
    rename '(.*)_OEM_BLUE_(.*)', '$1$2'
}

tasks.register('copyWithTruncate', Copy) {
    from layout.buildDirectory.dir("reports")
    // 使用闭包匹配名称
    rename { String filename ->
        if (filename.size() > 10) {
            return filename[0..7] + "~" + filename.size()
        }
        else return filename
    }
    into layout.buildDirectory.dir("toArchive")
}

文件集合

文件和目录的包装，主要是指文件集合(FileCollection)和文件树(FileTree)。它们的实现主要分为两种：可修改类和不可修改类。可修改类是可读可写的，而不可修改类是只读的。如下表：ConfigurableFileCollection 和 ConfigurableFileTree 等以 Configurable 开头命名的类是可读写的，类似于 kotlin 中的 MutableList。

文件集合

文件集合是由 FileCollection 接口表示的一组文件路径。FileCollection 中的文件不必位于同一目录中，甚至不必具有共享的父目录，可以彼此不相关。

获取文件集合推荐使用 ProjectLayout.files(java.lang.Object…) 方法，该方法返回一个 FileCollection 实例。此方法非常灵活，允许您传递不同参数。如果任务已定义输出(outputs，这部分内容涉及增量编译，后面讲解)，您甚至可以将任务作为参数传递。所有参数类型同 Project.files(Object) 方法。如下：

• 一个 CharSequence，包括 String 或 groovy.lang.GString。被视作相对于项目目录的相对路径。以 file: 开头的字符串被视为文件 URL

• 一份文件。file(Object) 得到的文件被视作相对于项目目录的相对路径。

• 一个 java.nio.file.Path 对象

• URI 或 java.net.URL。 URL 的路径被解释为文件路径。仅支持 file: 开头的 URL

• org.gradle.api.file.Directory 或 org.gradle.api.file.RegularFile。

• Collection、Iterable 或包含此处任何受支持类型的对象的数组。集合的元素被递归解析

• 一个 org.gradle.api.file.FileCollection，参数的所有元素加入到返回的对象中

• FileTree 或 org.gradle.api.file.DirectoryTree，参数的所有元素加入到返回的对象中

• 此处任何受支持类型的 Provider。Provider 的值被递归解析。如果 Provider 的值表示某个任务的输出，则在文件集合作为另一个任务的输入时执行该任务。

• 返回任何支持的类型的 Callable。 call() 方法的返回值被递归解析。 null 返回值被视为空集合。

• 返回此处列出的任何类型的 Groovy 闭包(Closure)或 Kotlin 函数(Function)。闭包的返回值被递归解析。 null 返回值被视为空集合。

• 一个任务(task)。将任务的输出文件转成 FileCollection。此 FileCollection 用作另一个任务的输入时，执行该任务。

• 一个 org.gradle.api.tasks.TaskOutputs。解释同 task

• 除了上述类型，其他任何内容都被视为错误。

文件集合在 Gradle 中有一些重要的特征：

• 可延迟创建(懒加载)：延迟创建的关键是将闭包(在 Groovy 中)或 Provider(在 Kotlin 中)传递给 files() 方法。您的闭包/Provider只需要返回 files() 接受的类型的值即可，例如 List、String、FileCollection 等

  tasks.register('list') {
      doLast {
          File srcDir
  
         // 使用 closure 包创建 FileCollection 
          collection = layout.files { srcDir.listFiles() }
  
          srcDir = file('src')
          println "Contents of $srcDir.name"
          // collect 相当于 kotlin 中的 map 操作
          // 对每个元素进行转换
          collection.collect { relativePath(it) }
              .sort().each { println it }
  
          srcDir = file('src2')
          println "Contents of $srcDir.name"
          collection.collect { relativePath(it) }
              .sort().each { println it }
      }
  }
  
  // gradle -q list 的执行结果：
  // > gradle -q list
  // Contents of src
  // src/dir1
  // src/file1.txt
  // Contents of src2
  // src2/dir1
  // src2/dir2
  

• 可遍历。FileCollection 继承了 Iterable，可在 Groovy 中使用 each() 方法，或者在 Kotlin 中使用 forEach 方法，或者单纯的使用 for 循环

• 可结合：可以使用 +、- 对集合进行操作

  collection.each { File file ->
      println file.name
  }
  // 转为其他集合类型
  Set set = collection.files
  Set set2 = collection as Set
  List list = collection as List
  String path = collection.asPath
  File file = collection.singleFile
  // 集合操作
  def union = collection + layout.files('src/file2.txt')
  def difference = collection - layout.files('src/file2.txt')
  

• 可过滤：使用 FileCollection.filter(Spec) 方法确定需要保留的元素，返回一个新的集合

  FileCollection textFiles = collection.filter { File f ->
      f.name.endsWith(".txt")
  }
  

文件树

文件树(file tree)是一个文件集合，具有 FileTree 类型。它保留了它所包含的文件的目录结构，这意味着文件树中的所有路径都必须有一个共享的父目录。要将文件树转换为平面集合，可以使用 FileTree.getFiles() 方法。下图说明了在复制文件的常见情况下文件树和文件集合之间的区别:

创建文件树最简单的方法是将文件或目录传递给 Project.fileTree(java.lang.Object) 方法。这将创建该目录中所有文件和目录的树(但不是基本目录本身)。以下示例演示了如何使用，此外，还演示了如何使用 Ant 样式模式过滤文件和目录：

// 基本使用
ConfigurableFileTree tree = fileTree(dir: 'src/main')

// 使用模版语法
tree.include '**/*.java'
tree.exclude '**/Abstract*'

// 使用闭包
tree = fileTree('src') {
    include '**/*.java'
}

// 使用 Map，Map 的定义语法非标准 groovy 语法，由 gradle 扩展实现
tree = fileTree(dir: 'src', include: '**/*.java')
tree = fileTree(dir: 'src', includes: ['**/*.java', '**/*.xml'])
tree = fileTree(dir: 'src', include: '**/*.java', exclude: '**/*test*/**')

在 settings.gradle 中，可以设置默认的排除选项，一般不需要我们设置。

// 在 settings.gradle 文件中
import org.apache.tools.ant.DirectoryScanner

DirectoryScanner.removeDefaultExclude('**/.git')
DirectoryScanner.removeDefaultExclude('**/.git/**')

FileTree 继承自 FileCollection，具备和 FileCollection 类似的操作：

// 遍历文件
tree.each {File file ->
    println file
}
// 过滤
FileTree filtered = tree.matching {
    include 'org/gradle/api/**'
}
// 集合操作
FileTree sum = tree + fileTree(dir: 'src/test')
// 深度优先访问元素。element 类型是 FileVisitDetails
tree.visit {element ->
    println "$element.relativePath => $element.file"
}

压缩包的文件树

使用 Project.zipTree(java.lang.Object) 和 Project.tarTree(java.lang.Object) 方法解析相应类型的压缩文件文件为文件树结构(请注意，JAR、WAR 和 EAR 文件都是 ZIP 类型的)。这两个方法返回的都是 FileTree。

文件集合的隐式转换

文件集合的隐式转换是特定 task 的功能。Gradle 中的许多对象都具有接受一组输入文件的属性。隐式转换不会发生在任何具有 FileCollection 或 FileTree 属性的任务上(此时显式指定了类型)。如果我们想知道在特定情况下是否发生隐式转换，那么我们需要阅读相关文档(如相应任务的 API 文档)。或者，我们可以通过在构建中明确使用 ProjectLayout.files(java.lang.Object…) 来消除所有歧义。例如，JavaCompile 任务具有 source 属性，该属性定义要编译的源文件。我们可以使用 files() 方法支持的任何类型设置 source 属性的值。

像 source 这样的属性在核心 Gradle 任务中具有相应的方法。这些方法遵循设置值时是新增到集合中，而不是替换集合中的值(是 += 的关系，不是 = 的关系)。这个原则在自定义插件/任务中十分重要。这样可以避免将其他插件/任务的配置覆盖掉。比如 A 插件设置了 javaCompileOptions 的内容，我们的自定义插件 B 也设置了 javaCompileOptions。+= 的模式可以避免我们把 A 插件的配置覆盖掉，导致编译出错。

tasks.register('compile', JavaCompile) {
    // 属性的使用方式
    // 会转换成 += 的调用
    // 使用 File 对象指定源码目录
    source = file('src/main/java')
    // 使用字符串指定
    source = 'src/main/java'
    // 使用数组
    source = ['src/main/java', '../shared/java']
    // 使用 FileCollection
    source = fileTree(dir: 'src/main/java').matching { 
       include 'org/gradle/api/**' 
    }
    // 使用闭包
    source = {
        // 使用 src 目录中每个 zip 文件的内容
        file('src').listFiles().findAll {
           it.name.endsWith('.zip')
        }.collect { zipTree(it) }
    }
}

compile {
    // 方法的使用方式
    // 列表
    source 'src/main/java', 'src/main/groovy'
    // 文件对象
    source file('../shared/java')
    // 文件数组
    source { file('src/test/').listFiles() }
}

Gradle 文件类

Gradle 定义了更强类型的类来表示文件系统的元素：Directory 和 RegularFile。这些类型不应与标准 Java 文件类型(File)混淆，因为它们用于告诉 Gradle 和其他人，我们期望更具体的值，例如目录或非目录的文件(如设备)。

• Directory 和 RegularFile 不建议继承实现。Gradle 提供了两个专门的 Property 子类型来处理：RegularFileProperty 和 DirectoryProperty。 ObjectFactory 具有创建这些属性的方法：ObjectFactory.fileProperty() 和 ObjectFactory.directoryProperty()。

• Directory 和 RegularFile 实例还可以使用 ProjectLayout 提供的方法获取。比如 getProjectDirectory()。而 RegularFile 实例还可以通过 Directory.file 获取

abstract class GenerateSource extends DefaultTask {
    // inputs 是个 file
    @InputFile
    abstract RegularFileProperty getConfigFile()

    // outputs 是个 dir
    @OutputDirectory
    abstract DirectoryProperty getOutputDir()

    @TaskAction
    def compile() {
        // 类型 RegularFile
        def inFile = configFile.get().asFile
        logger.quiet("configuration file = $inFile")
        // 类型 Directory
        def dir = outputDir.get().asFile
        logger.quiet("output dir = $dir")
        def className = inFile.text.trim()
        def srcFile = new File(dir, "${className}.java")
        srcFile.text = "public class ${className} { ... }"
    }
}

// 注册任务
tasks.register('generate', GenerateSource) {
    configFile = layout.projectDirectory.file('src/config.txt')
    outputDir = layout.buildDirectory.dir('generated-source')
}

layout.buildDirectory = layout.projectDirectory.dir('output')

压缩包操作

压缩包文件可以看作一个特殊的文件系统(区别于操作系统的文件系统)。

压缩文件

从 Gradle 的角度来看，将文件压缩实际上更像是一个复制操作，只是目标目录是压缩文件(zip，tar等)而不是系统中的目录(dir)。所以 Gradle 中压缩框架的设计，能够看见 Copy 操作的影子。下图为压缩相关任务的一个继承图：

使用压缩任务时，我们需要指定存档的目标目录(destinationDirectory)和名称(archiveFileName)，注意不是使用 into() 方法指定了，这两个都是必需的(示例见 packageDistribution 任务)。但是通常在自定义任务中，我们不会看到它们的显式设置，这是因为大多数项目都应用了 Base Plugin(The Base Plugin (gradle.org))。该 Plugin 为这些属性提供了一些默认值。下面一个示例演示了这一点。

下面示例假设了一个常见的场景：将文件复制到压缩包的指定子目录中。例如，假设我们要将所有的 PDF 打包到压缩包根目录中的 docs 目录中，但压缩包中不存在此 docs 目录，因此我们必须将其创建成为压缩包的一部分。要达成此效果，我们需要为 PDF 添加一个 into() 声明：

plugins { id 'base' }

version = "1.0.0"

tasks.register('packageDistribution', Zip) {
    // archiveFileName = "my-distribution.zip"
    // destinationDirectory = layout.buildDirectory.dir('dist')
    from(layout.buildDirectory.dir("toArchive")) {
        exclude "**/*.pdf"
    }

    from(layout.buildDirectory.dir("toArchive")) {
        include "**/*.pdf"
        // copy 到压缩包的 docs 子目录，目录不存在时，会创建目录
        into "docs"
    }
}

解压文件

解压压缩包是将文件从压缩包中复制到系统目录中，或者复制到另一个压缩包中。 Gradle 通过提供一些包装函数来实现这一点，这些函数使压缩包可以被视作文件树：

• Project.zipTree(java.lang.Object)

• Project.tarTree(java.lang.Object)

与普通 Copy 任务一样，可以通过 filters 控制哪些文件被解压缩，可以在文件解压缩时重命名文件，可以通过 eachFile() 遍历压缩包中的每个文件。

• 注意：解压时，可以忽略掉空目录；不忽略空目录时，即使可以包含空目录，空目录的目标路径也不能改变(历史遗留问题，见 Issue 2940 )

tasks.register('unpackLibsDirectory', Copy) {
    // zipTree() 同样适用于 jar、war 等文件
    from(zipTree("src/resources/thirdPartyResources.zip")) {
        include "libs/**"  // 仅解压压缩包中 libs 目录下的文件
        eachFile { fcd ->
            fcd.relativePath = new RelativePath(
                true, 
                fcd.relativePath.segments.drop(1)
            )  // 文件路径中删除 libs 段，将文件路径重新映射到目标目录
        }
        includeEmptyDirs = false  // 解压时，忽略掉空目录
    }
    into layout.buildDirectory.dir("resources")
}

压缩包名称

Gradle 支持创建 ZIP 和 TAR 文件，并且进一步扩展实现了 Java 的 JAR、WAR 和 EAR 格式——Java 的产物格式其实都是 ZIP。每一种格式都有相应的任务类型来创建它们：Zip、Tar、Jar、War 和 Ear。这些格式都以相同的方式工作并且都基于 CopySpec，就像复制任务一样。

了解了基于规范的存档名称，可以使我们免于一直配置目标目录(destinationDirectory)和存档名称(archiveFileName)。

AbstractArchiveTask.getArchiveFileName() 提供了默认存档名称模式：[archiveBaseName]-[archiveAppendix]-[archiveVersion]-[archiveClassifier].[archiveExtension]。可以在任务中分别设置这些属性中的每一个。我们可以在 AbstractArchiveTask 的 API 文档中找到所有任务属性。

Base Plugin 提供了部分默认值：

• 为 archiveBaseName 设置了项目名称

• 为 archiveVersion 设置了项目版本

• 为 archiveExtension 设置压缩包类型

• 其他属性的值没有提供

// 任务输出结果：customName-1.0.zip
tasks.register('myCustomZip', Zip) {
    // 覆盖了 archiveBaseName 的值
    archiveBaseName = 'customName'
    from 'somedir'

    doLast {
        println archiveFileName.get()
    }
}

plugins {
    id 'base'
}

version = 1.0
// tag::base-plugin-config[]
base {
    // 为所有任务指定 archivesName
    archivesName = "gradle"
    distsDirectory = layout.buildDirectory.dir('custom-dist')
    libsDirectory = layout.buildDirectory.dir('custom-libs')
}
// end::base-plugin-config[]

tasks.register('myZip', Zip) {
    from 'somedir'
}

tasks.register('myOtherZip', Zip) {
    archiveAppendix = 'wrapper'
    archiveClassifier = 'src'
    from 'somedir'
}

tasks.register('echoNames') {
    doLast {
        println "Project name: ${project.name}"
        println myZip.archiveFileName.get()
        println myOtherZip.archiveFileName.get()
    }
}
// 任务输出结果：
// Project name: archives-changed-base-name
// gradle-1.0.zip
// gradle-wrapper-1.0-src.zip

可重复的构建

我们有时需要在不同的机器上逐字节地重新创建完全相同的压缩包。我们希望源代码相同时，构建结果无论何时何地都会产生相同的结果。

要达到这种效果，有一定的挑战性，因为压缩包中文件的顺序受底层文件系统的影响。每次从源代码构建 ZIP、TAR、JAR、WAR 或 EAR 时，压缩包中文件的顺序可能都会发生变化。具有不同时间戳的文件也可能会导致归档在构建之间存在差异。

但是好在 Gradle 内置的所有 AbstractArchiveTask（例如 Jar、Zip）任务都支持生成可重现的压缩。例如，要使 Zip 任务可重现，您需要将 Zip.isReproducibleFileOrder() 设置为 true，并将 Zip.isPreserveFileTimestamps() 设置为 false。为了使构建中的所有存档任务可重现，需要将以下配置添加到构建文件(build.gradle)中：

tasks.withType(AbstractArchiveTask).configureEach {
    preserveFileTimestamps = false // 不保存时间戳
    reproducibleFileOrder = true
}

Gradle properties 说明

属性分类

注：官方文档地址： Build Environment (gradle.org)

gradle 中，property(属性)主要是用于定义传递值(比如统一管理版本号)。

Gradle 支持 4 种 Properties, 这三种 Properties 的作用域和初始化阶段都不一样：

System Properties

1. System Properties 也叫 Root Project Properties，可以看作根项目属性。可通过 根项目/gradle.properties 文件、环境变量 或 命令行 -D 参数 设置

2. 可在 setting.gradle 或 build.gradle 中动态修改，在 setting.gradle 中的修改对 buildscript 配置块可见

3. System Properties 对所有工程可见，不建议在 build.gradle 中修改

4. 多子工程项目中，子工程的 gradle.properties 会被忽略掉，只有 root 工程的 gradle.properties 有效

示例代码：

# 注释省略，想看注释，请新建项目查看
org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
--warning-mode=all
android.useAndroidX=true
kotlin.code.style=official
android.nonTransitiveRClass=true
org.gradle.daemon=true

Project Properties

1. Project Properties 也可理解成 Child Project Properties，子工程属性。可通过 根项目/模块工程/gradle.properties 文件，环境变量 或 命令行 -P 参数 设置

2. 可在 build.gradle 中动态修改，但引用不存在的 project properties 会立即抛错

3. 动态修改过的 project properties 对 buildscript 配置块中不可见

示例代码：

# 定义编译后的 aar 的 maven pom 信息
GROUP=com.well.android.test
ARTIFACT=test-ui
VERSION=1.0.0

Project ext properties

1. 项目扩展属性，可在项目的 build.gradle 中声明和使用，本工程和子工程可见。

2. 不能在 setting.gradle 中访问

3. ext 的 DSL 由接口类 ExtraPropertiesExtension 定义。

4. 通常，我们是定义根项目的 ext 属性。在根项目的 build.gradle 文件的 buildscript 中定义。

// 根项目的 build.gradle 文件
buildscript {
    // 方式 1：
    ext {
        COMPILE_SDK_VERSION = 30
        BUILD_TOOL_VERSION = '30.0.2'
        MIN_SDK_VERSION = 21
        TARGET_SDK_VERSION = 30
        println("MIN_SDK_VERSION:${MIN_SDK_VERSION}")
    }
}
// 方式 2：
// properties 的使用在下面说明
ext.enableLocalDev = properties.get("localDev") == "true"

Custom properties

Custom properties，即自定义 properties。我们可以自定义一个 properties 文件，然后手动读取里面的属性并赋值。

以 local.properties 文件为例。每个 Android 项目中都会有一个 local.properties 文件，但是该文件并不会纳入到 git 管理中，因为这是 Android Studio(IDEA) 动态生成的文件。如果我们不做改动，那么里面默认定义了 sdk.dir 属性，该属性表示 Android SDK 的目录。

我们可以在 local.properties 中额外定义属性，然后手动读取它。如果我们希望部分项目中定义的变量不放入到 git 仓库中(比如 release 包签名路径，比如私有 maven 仓库账号密码)，那么就可以放入到 local.properties 文件中定义(gradle.properties 文件会跟随 git 管理)。

比如我们在 local.properties 文件中定义个 isAPK 变量：

定义了属性后，我们就可以在项目根目录的 build.gradle 文件中读取值：

// 文件：Root Project 的 build.gradle 文件
buildscript {
    Properties properties = new Properties()
    // 加载 local.properties 文件
    properties.load(project.rootProject.file('local.properties').newDataInputStream())
    // 读取 isAPK 属性，ext 为 Root Project 的 ext
    ext.isAPK = properties.get("isAPK") == "true"
}

对面代码，需要解释以下几个点：

1. buildscript 优先于 build.gradle 中的其他内容执行，注意变量的使用范围

2. properties 文件，properties 文件可以是任意名称，并且不关心是否受 git 管理。可以跟 git，也可以被 git 忽略

3. properties 文件中定义的键值对的值，默认是 String 类型的，无需再单独加引号

Custom properties 可以读取后，再赋值给 Project ext properties。这样可以避免每次使用时都去读取 properties 文件。

懒加载

Gradle 提供了惰性属性(Lazy properties)(属性的懒加载)，该属性会先声明而不运算值，直到真正使用属性时才去运算确定值。这样做为 build script 和 plugin developer 提供了三个主要好处：

• 开发者可以将 Gradle Model 类写在一起，而不需要管属性的值什么时候确定。例如，我们想要根据一个扩展属性(extension property)的源目录属性设置任务的输入源文件，但在构建脚本或其他插件配置它之前，此扩展属性值是未知的。此时使用惰性属性，就可以在需要的时候拿到值而不出现问题

• 开发者可以将任务的输出属性(outputs)连接为其他任务的输入属性(inputs)，Gradle 会根据此连接自动确定任务的依赖关系。属性实例会携带有哪个任务(如果有)赋予它们值的信息。开发者不需要处理同步任务依赖和配置更改之间的同步

• 构建作者可以避免在配置阶段(configuration 阶段)进行资源密集型工作，这会对构建性能产生很大影响。例如，当 value 需要通过解析文件来获取，但仅在运行阶段使用时，使用惰性属性可以仅在运行阶段才解析文件，而不是在配置阶段。这意味着配置阶段执行效率的提高，时间的缩短。

Gradle 的懒加载相关类如下：

基础说明

Gradle 使用以下两种接口来表示属性的懒加载：

• Provider 代表一个只读的值

• Provider.get() 获取当前的值

• 可以使用 Provider.map(Transformer) 从另一个 Provider 创建新 Provider

• Provider 有很多实现类、扩展类，可以在任何需要使用 Provider 的地方使用

Property 代表了可读写的值

• Property 继承了 Provider 接口

• Property.set(T) 为属性设置值

• Property.set(Provider) 指定属性的值来自于另一个 Provider。这可以将 Provider 和 Property 两个实例连接在一起

• ObjectFactory.property(Class) 可以创建一个 Property

• Gradle 会为任务实现中的每个 Property 类型的属性生成 setter 方法。这些 setter 方法允许使用赋值 (=) 运算符来配置属性，以方便使用

// extension 的说明会在自定义 Plugin 中讲解
interface MessageExtension {
    Property<String> getGreeting()
}

abstract class Greeting extends DefaultTask {
    @Input
    abstract Property<String> getGreeting()
    // greeting 的值会传递给 message
    @Internal
    final Provider<String> message = greeting.map { 
        it + ' from Gradle' 
    }
    @TaskAction
    void printMessage() {
        logger.quiet(message.get())
    }
}

// 创建 extension
project.extensions.create('messages', MessageExtension)

// 创建任务
tasks.register("greeting", Greeting) {
    // 关联 extension 和 task 中的 property
    // extension 值的更改，会传递给 task
    greeting = messages.greeting
}

messages {
    // 配置 extension
    greeting = 'Hi'
}

注：请不要自定义实现 Provider 及其所有子类，应使用 Gradle 框架提供的工厂类获取 Provider 及其子类。具体的 api 可以看这里： Lazy Configuration (gradle.org)

• Project.getObjects() »> ObjectFactory.property(Class)

• ProviderFactory.provider(Callable)(不推荐，建议使用 map 方法)

• Provider.map(Transformer)

abstract class GenerateSource extends DefaultTask {
    // inputs 是个 file
    @InputFile
    abstract RegularFileProperty getConfigFile()

    // outputs 是个 dir
    @OutputDirectory
    abstract DirectoryProperty getOutputDir()

    @TaskAction
    def compile() {
        def inFile = configFile.get().asFile
        logger.quiet("configuration file = $inFile")
        def dir = outputDir.get().asFile
        logger.quiet("output dir = $dir")
        def className = inFile.text.trim()
        def srcFile = new File(dir, "${className}.java")
        srcFile.text = "public class ${className} { ... }"
    }
}

// 注册任务
tasks.register('generate', GenerateSource) {
    configFile = layout.projectDirectory.file('src/config.txt')
    outputDir = layout.buildDirectory.dir('generated-source')
}

layout.buildDirectory = layout.projectDirectory.dir('output')

说明：

• 此示例通过 Project.getLayout()、 ProjectLayout.getBuildDirectory()、 ProjectLayout.getProjectDirectory() 创建表示项目位置和构建目录的 provider

• 使用 DirectoryProperty.getAsFileTree() 或 Directory.getAsFileTree() 可以将 DirectoryProperty 或 Directory 转换为 FileTree，

• 可以使用 DirectoryProperty.files(Object…) 或 Directory.files(Object…) 创建包含目录中的一组文件的 FileCollection 实例

集合懒加载

Gradle 提供了两种惰性属性(lazy property)类型来帮助配置 Collection 属性。它们的工作方式与任何其他 Provider 完全一样，并且就像文件提供程序一样，它们有额外的 model 类：

• 对于 List，该接口称为 ListProperty。可以使用 ObjectFactory.listProperty(Class) 创建新的 ListProperty 并指定元素类型

• 对于 Set，该接口称为 SetProperty。可以使用 ObjectFactory.setProperty(Class) 创建新的 SetProperty 并指定元素类型

Collection 类型的属性允许覆盖整个集合值：

• HasMultipleValues.set(Iterable)

• HasMultipleValues.set(Provider)

或者通过各种 add 方法添加新元素：

• HasMultipleValues.add(T)

• HasMultipleValues.add(Provider)

• HasMultipleValues.addAll(Provider)：添加 Provider 的所有值到集合中

映射懒加载

Gradle 提供了一个惰性 MapProperty 类型来允许配置 Map 值。可以使用 ObjectFactory.mapProperty(Class, Class) 创建 MapProperty 实例

与其他属性类型类似，MapProperty 有一个 set() 方法，可以使用该方法指定属性的值，这些值可以是惰性值

abstract class Generator extends DefaultTask {
    @Input
    abstract MapProperty<String, Integer> getProperties()

    @TaskAction
    void generate() {
        properties.get().each { key, value ->
            logger.quiet("${key} = ${value}")
        }
    }
}

def b = 0
def c = 0

tasks.register('generate', Generator) {
    properties.put("a", 1)
    properties.put("b", providers.provider { b })
    properties.putAll(providers.provider { [c: c, d: c + 1] })
}

// 输出的最终结果为2、3
// b = 2
// c = 3

属性默认值

当没有为属性设置值时，我们可能希望对要使用的属性指定一些规范(convention)或默认值。此时可以使用 convention() 方法达到这个目的。此方法接受一个值或 Provider，这个值将默认被使用，直到配置了其他值

def property = objects.property(String)

// Set a convention
property.convention("convention 1")
println("value = " + property.get())

// Can replace the convention
property.convention("convention 2")
println("value = " + property.get())

property.set("value")
// 一旦设置了值，convention 就被忽略了
property.convention("ignored convention")
println("value = " + property.get())

final 属性

任务(task)或项目(project)的大多数属性(properties)由插件或构建脚本配置，然后将结果值用于完成一些事情。例如，由插件指定的编译任务的输出目录，可在构建脚本中修改，然后在任务运行时使用这个值。此时我们希望一旦任务开始运行，值就不可以再被修改。增加这种限制，我们可以避免不同使用者使用不同的属性值，进而导致错误。这些使用者可以是如任务操作、Gradle 的最新检查(up-to-date)、构建缓存操作或其他任务。

惰性属性(Lazy properties)提供了几种方法，可以使我们在使用这些方法配置属性值后，禁止属性值再被更改

• finalizeValue() 方法计算属性的 final 值并防止对属性进行进一步更改。当属性的值来自 Provider 时，会向此 Provider 查询其当前值，结果将成为该属性的最终值，并且属性不再跟踪该 Provider 的值。调用此方法还会使属性实例不可修改，当任务开始执行时，Gradle 会自动使任务的属性成为 final，任何进一步更改属性值的尝试都将失败

• finalizeValueOnRead() 方法作用类似，只是在查询属性值之前不计算属性的 final 值。换句话说，该方法根据需要延迟计算最终值，而 finalizeValue() 则立即计算最终值。当该值的计算成本可能很高或可能尚未配置时，我们希望确保该属性的所有使用者在查询该值时得到相同的值，可以使用此方法

File 属性

FileCollection、FileTree、RegularFileProperty、DirectoryProperty、ConfigurableFileCollection、ConfigurableFileTree、SourceDirectorySet 等文件相关类，都是懒加载属性。

Gradle 提供了两个专门的 Property 子类型来处理这些类型的值：RegularFileProperty 和 DirectoryProperty。 ObjectFactory 定义了创建这些属性的方法：ObjectFactory.fileProperty() 和 ObjectFactory.directoryProperty()。

DirectoryProperty 还可用于分别通过 DirectoryProperty.dir(String) 和 DirectoryProperty.file(String) 为 Directory 和 RegularFile 创建一个惰性的 Provider。这些方法创建 Provider，其值是相对于创建它们的 DirectoryProperty 的位置计算的。DirectoryProperty 的值发生更改，这些被创建的 Provider 的值会同步更改。

示例可见上文 GenerateSource 任务类的使用

Gradle 类功能

每个 Gradle 项目都有一个全局唯一的 gradle 对象，该 gradle 对象是 org.gradle.api.invocation.Gradle 的一个实例。我们可以通过 Gradle 接口类的定义，了解 Gradle 的一些知识点。

如图是 Gradle 提供的能力，主要是 gradle 描述相关、项目相关、构建流程相关三块。我们最主要关心的就是和构建流程相关的知识

Gradle 构建流程

根据官方说明，Gradle 的构建流程主要分为三个阶段：

• Initialization：初始化阶段。此阶段主要是解析执行 settings.gradle 文件，生成 project 对象。具体内容下面讲解

• Configuration：配置阶段。配置阶段主要是与 build.gradle 和 task 有关。此阶段主要是将上个阶段确定的各个 project 对象对应的 build.gradle 文件从上往下执行、解析，确定各个 project 的任务子集、配置 task、以及生成任务图 task graph(或者可以叫做有向无环图(Directed Acyclic Graph (DAG)))。

• Execution：执行阶段。此阶段主要 根据 DAG 执行所有任务的 actions。此时是编译的真正运行时刻，如生成 .class 文件，上传编译结果到 maven 等等。

具体的执行流程如下图：

我们可以通过 Gradle 提供的构建流程相关方法，hook gradle 构建流程的关键节点。其中 addListener 方法中可以添加的 Listener 类型为：

• BuildListener

• org.gradle.api.execution.TaskExecutionGraphListener

• ProjectEvaluationListener

• org.gradle.api.execution.TaskExecutionListener

• org.gradle.api.execution.TaskActionListener

• org.gradle.api.logging.StandardOutputListener

• org.gradle.api.tasks.testing.TestListener

• org.gradle.api.tasks.testing.TestOutputListener

• org.gradle.api.artifacts.DependencyResolutionListener

需要注意的一点是，我们可以通过打印 gradle 构建流程的详细日志，辅助梳理整个流程：gradle -i :app:assemble。

Gradle 任务执行方式为：

Settings 类功能

因为 Gradle 的初始化阶段和 settings.gradle 文件息息相关，而 settings.gradle 文件又和 Settings 对象一一对应。所以在介绍 Gradle 的初始化流程前，我们需要看下 Settings 类，Settings 接口类的定义如下：

注：在 project、settings、gradle 中查询某个项目实例时，应注意带上冒号( : )。在 gradle 中，冒号即文件路径分隔符，对应 Linux 下的 /。

依赖说明

在一个典型的 Gradle 项目中，依赖管理是重要关注的存在。

• 项目导入第三方依赖通常分为两步：

  • 指定依赖所在仓库，仓库是存放大量依赖的地方

  • 导入目标版本的依赖，依赖可以具有多个不同的版本，我们应选择合适的版本

• 导入的依赖使用涉及两个方面：

  • Gradle 自身所用依赖

  • 目标产物所用的依赖

指定依赖所在仓库，使用的是 repositories 方法；导入目标版本的依赖，使用的是 dependencies 方法。

Gradle 自身使用的依赖，通常是在 .gradle 文件中写 java/groovy/kotlin 代码时用到。依赖信息在 buildScript 中配置，调用 ScriptHandler.repositories() 方法配置仓库信息，调用 ScriptHandler.dependencies() 方法导入相关依赖

在 Android 中，目标产物通常是指 app 或者 aar。因为项目可以模块化，所以目标产物所用的依赖，依赖一般是在模块级别的 build.gradle 中引入的，单仓库信息可以在根项目的 build.gradle 中声明。调用 Project.repositories() 方法配置仓库信息，调用 Project.dependencies() 方法导入模块使用的相关依赖

上述说明可用下面的图片阐述：

一段依赖配置的典型代码如下：

// rootProject 的 build.gradle 文件
buildscript {
    repositories {
        google() // google 中央仓库
        jcenter() // 已废弃，不再使用
        mavenCentral()
        // 阿里云的中央仓库，国外的仓库访问不上时，可使用国内的
        maven{ url 'https://maven.aliyun.com/repository/central'}
        maven{ url'https://maven.aliyun.com/repository/public'}
        maven{ url "https://maven.aliyun.com/repository/google"}
    }

    dependencies {
        // 导入 gradle 需要使用的 android 和 kotlin 插件
        classpath "com.android.tools.build:gradle:7.2.0"
        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:1.6.10'
    }
}

allprojects {
    // 配置 app 所使用的仓库
    repositories {
        google()
        jcenter()
        mavenCentral()
        maven{ url 'https://maven.aliyun.com/repository/central'}
        maven{ url'https://maven.aliyun.com/repository/public'}
        maven{ url "https://maven.aliyun.com/repository/google"}
    }
}

// app 的 build.gradle 文件
plugins {
    // 应用 android 插件和 kotlin 插件
    id "com.android.application"
    id "org.jetbrains.kotlin.android"
}
dependencies {
    // Kotlin 的相关依赖
    implementation "androidx.core:core-ktx:1.7.0"
    implementation "org.jetbrains.kotlin:kotlin-stdlib:1.5.30"
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.5.2"
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.5.2"
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.5.2"

    // Android 的相关依赖
    implementation "androidx.appcompat:appcompat:1.4.1"
    implementation "com.google.android.material:material:1.6.0"
    implementation "androidx.constraintlayout:constraintlayout:2.1.4"
    implementation "androidx.activity:activity:1.4.0"
    implementation "androidx.fragment:fragment:1.4.1"
    implementation "androidx.fragment:fragment-ktx:1.4.1"
    implementation "androidx.legacy:legacy-support-v4:1.0.0"
}

getBuildscript

settings.gradle 文件解析是在初始化阶段就执行的，而项目的 build.gradle 文件在配置阶段执行的。所以根项目中配置的 buildscript 内容，是无法在 settings.gradle 生效的。但是当我们在 settings.gradle 中写 java/groovy/kotlin 代码时，如果想要使用第三方库该怎么办？此时就可以在 settings.gradle 文件中使用 buildscript{} 块，配置仓库和导入对应依赖

pluginManagement

gradle 最初是没有一个统一的插件存放仓库的，大多数人可能会把插件放到 github 上。而后来官方弄了一个插件仓库，用户可以从该仓库下载插件、或者上传插件到仓库。可以使用 pluginManagement 在 settings.gradle 中配置插件管理，该 block 配合 plugins block 使用。请注意，有 pluginManagement block 时，该 block 必须是 settings.gradle 中的第一个 block。一个常见的使用方式如下：

// settings.gradle 文件中
pluginManagement {
    // 此处不指定 plugins，后续引入时需要指定版本号，可选
    plugins {
        // 引入插件
        id 'com.android.application'
        id 'org.jetbrains.kotlin.android' version '1.6.10'
        id 'com.android.library' version '7.2.0' apply false
    }
    // 指定插件解析策略, 可选
    resolutionStrategy {
        eachPlugin {
            if (requested.id.namespace == "com.example") {
                useModule("com.example:sample-plugins:1.0.0")
            }
        }
    }
    repositories {
        maven {url "custom-plugin-repo-url"} // 自定义插件仓库
        gradlePluginPortal() // gradle 官方插件仓库
    }
}

应用 plugins block 使用插件：

// 使用插件，app 的 build.gradle 文件首行
plugins {
    id 'com.android.application' version '7.2.0'
    id 'org.jetbrains.kotlin.android'
}

针对 pluginManagement 和 plugins DSL(Domain Specific Language)的一些说明：

• pluginManagement 的 DSL 由接口类 PluginManagementSpec 定义，plugins 的 DSL 由接口类 PluginDependenciesSpec 定义

• pluginManagement »> plugins block 为可选项

• 在 pluginManagement »> plugins block 中，id 是必须声明的，version 和 apply 是可选项。如果在引入插件时没有指定 version，以及设置了插件不生效(apply 值为 false)。则在使用插件时必须设置 version 和 apply

• 在 pluginManagement »> plugins block 中声明插件后，查看会被默认应用上(apply 值为 true)

依赖导入说明

注：关于如何处理大型项目的依赖，可以参考这个指引： 依赖处理

在 gradle 中，我们可以使用以下方式导入远程或者本地依赖。其具体方式如图：

allprojects & dependencyResolutionManagement

在 gradle 项目中，当我们导入依赖时，需要先声明依赖所在仓库。在低版本 gradle 项目中，我们通常在 rootProject 的 build.gradle 文件中，使用 allprojects.repositories 块设置仓库：

allprojects {
    repositories {
        google()
        mavenLocal()
        maven { url 'https://jitpack.io' }
    }
}

但是 gradle 官方建议将仓库的声明统一管理，这样方便本地仓库和远程仓库切换(这在多工程，大型项目中通常很有用)。于是在 6.8 中加入了 dependencyResolutionManagement 语句块，用于在 settings.gradle 中声明依赖仓库。在新版 Android Studio 中，新建项目，默认都是采用这种方式声明仓库。

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

声明了依赖仓库后，我们就可以使用 dependencies 导入编译好的二进制依赖了。注意：使用 dependencyResolutionManagement 声明了仓库后，就可以不用写 allprojects.repositories 块了。

sourceControl

sourceControl 示例见： sourceControl 的使用

• 在 Gradle 中，我们除了可以导入远程的二进制依赖，还可以导入远程 module 源码，在本地编译应用时，编译出一个远程 module。同导入二进制依赖类似，sourceControl 可以声明仓库和指定依赖。sourceControl 块中，使用 gitRepository 方法指定 git 仓库，该 git 仓库可以视作依赖仓库。gitRepository 方法返回的是 VersionControlRepository 接口类。使用该类定义的 producesModule 方法可以指定导入的 module 依赖(字符串形式：“group:moduleName”)。使用 setRootDir 方法可以指定 module 在 git 仓库中的相对位置。故 sourceControl 的一个常见用法为：

  // rootProject/settings.gradle 文件
  sourceControl {
     gitRepository("https://github.com/google-ar/arcore-android-sdk.git") {
         producesModule("com.google.ar.core.examples:app")
         rootDir = "samples/hello_ar_java"
     }
  }
  

  其中 https://github.com/google-ar/arcore-android-sdk.git 是一个远程 git 仓库，我们需要导入该仓库下的 app 模块，该模块在 rootDir/samples/hello_ar_java 目录下。

• sourceControl 可等价于导入远程依赖，如下，dependencies 导入远程二进制依赖，可与 sourceControl 导入远程源码依赖等价：

// 代码 1
sourceControl {
   gitRepository("https://github.com/gradle/native-samples-cpp-library.git") {
       producesModule("org.gradle.cpp-samples:utilities")
   }
}

// 上面 1 的代码，等价于下面的代码
dependencies {
   implementation 'org.gradle.cpp-samples:utilities:1.0'
}

include & includeBuild

gradle 支持多 module(或者叫 child project) 工程构建，include 和 includeBuild 方法都是在多 module 工程构建中使用。其说明如下：

• include 在单工程中使用，该工程可以包含多个 module，每个需要加入构建的 module 都需要在 settings.gradle 中使用 include 声明，表明该 module 需要加入到构建中：

// rootProject 的 settings.gradle 文件中
// app 模块和 libTest 模块加入到构建中
rootProject.name = "TestApp"
include ':app'
include ':libTest'

• includeBuild 在跨工程(官方的名称翻译为"复合构建”)中使用。例如本地 app 工程 依赖本地 lib 工程下的 log、net 模块。这两个 module 会被编成 maven 依赖包，app 以远程依赖的形式导入。但是如果 log、net 模块出了 bug，此刻想要修复，每次都得编包、同步、编译，相当麻烦(如果遇到 app 工程存在缓存冲突，则每次还得清缓存，会花费相当多的时间)。此刻我们可以考虑使用 includeBuild，将 lib 工程导入 app 工程中，再使用具体的依赖替换规则，将 log、net 的远程依赖替换为 lib 工程下的 module(即使用本地 module，不使用远程依赖)，这样我们可以保证编译速度，提高效率，大大节省了时间

  includeBuild 方法使用时，可以传入一个 ConfigurableIncludedBuild 的闭包，该闭包包含一个 dependencySubstitution 的方法，该方法又可以传入一个 DependencySubstitutions 的闭包，用于编写依赖替换规则

  具体使用说明如下：

  1. 定义数据结构。此处以在 local.properties 文件中定义为例(可以是其他任意文件，只要保证能正常读取即可)。

     1. INCLUDE_BUILD 是个 json 数组，代表着需要被导入的其他工程的信息，每个被导入的工程都是个 json 对象

     2. enabled 表示对于该工程，includeBuild 是否生效

     3. rootPath 表示被导入的工程的根目录

     4. modules 表示需要被替换的 module 的信息，name 表示 lib 工程中对应的 module 名，maven 表示 app 模块中需要被替换掉的远程依赖

     # file name: local.properties
     INCLUDE_BUILDS=[\
       {\
          "enabled":true,\
          "modules": [\
              {\
                  "name": "log",\
                  "maven":"com.test.android:log"\
              },\
              {\
                  "name": "net",\
                  "maven":"com.test.android:net"\
              }\
          ],\
          "rootPath":"../lib"\
       }\
     ]
     

  2. 在定义了数据结构后，我们可以在 settings.gradle 中进行实现。

  // settings.gradle 文件中
  dealIncludeBuild()
  
  import groovy.json.JsonSlurper
  void dealIncludeBuild() {
      // 1. 加载 local.properties 文件
      File propertyFile = new File(rootDir.getAbsolutePath() + "/local.properties")
      properties.load(propertyFile.newDataInputStream())
      // 2. 加载我们定义的数据
      def includeBuilds = properties.getProperty('INCLUDE_BUILDS')
      if (includeBuilds == null || includeBuilds == "") {
          return
      }
      def jsonSlurper = new JsonSlurper()
      def localProjects = jsonSlurper.parseText(includeBuilds)
      // 遍历需要被 includeBuild 的项目
      for (localProject in localProjects) {
          if (localProject.enabled != true) {
              continue
          }
          includeBuild(localProject.rootPath) {
              // 替换对应的依赖
              dependencySubstitution {
                  localProject.modules.each { itt ->
                      substitute module(itt.maven) with project(":${itt.name}")
                  }
              }
          }
      }
  }
  

  3. 在定义了上述逻辑之后，我们就可以自由控制 includeBuild 是否生效了。如果 local.properties 文件中没有定义 INCLUDE_BUILDS 结构，或者 enable 为 false，那么 app 会使用 log、net 的远程 maven 依赖，否则使用 lib 工程下的本地 module

• 对于 include 和 includeBuild，还有几点说明如下：

  • 虽然 include 导入的是本工程的 child project，includeBuild 导入的是跨工程的 project，但这并不是绝对的。对于一个 project 导入时应使用 include 还是 includeBuild，最本质的特点是看该 project 是否具有 settings.gradle 文件。如果工程具有 settings.gradle 文件，则其他工程在导入它时，就应该使用 includeBuild，否则应使用 include。

  • includeBuild 并不会导入 module 的配置信息。比如 lib 工程下 net 模块如果以远程依赖的方式依赖了 okhttp，那么在 includeBuild 到 app 工程时，okhttp 的依赖信息并不会传入 app 工程，需要 app 工程在 dependencies 中再导入一次。

总结

1. include、includeBuild、sourceControl 和 dependencies 有极大的相似性

   • nclude 是以本地单工程源码的形式导入 module

   • includeBuild 是以本地跨工程源码的形式导入 module

   • sourceControl 是以远程仓库源码的形式导入 module

   • dependencies 是以远程二进制依赖的形式导入 module

2. includeBuild、sourceControl 导入的内容，都应视作仓库，而非某个具体的依赖，具体生效的依赖需要根据相应的依赖替换规则确定。而 dependencies 中导入的内容，可以看作是某个具体的依赖。

Task 类功能

Gradle Task 功能众多，本文将按照以下要点进行讲解。

task 含义

Task 可以翻译为任务，是我们使用 gradle 的过程中的一个核心类。Task 代表构建的单个原子工作(原子性意味着不可再分割)，如编译 classes 或生成 javadoc。

每个 task 都属于一个 project。可以使用 org.gradle.api.tasks.TaskContainer 类的各种方法来创建和查找 task 实例(可以是 Gradle 内置类的实例，也可以是我们自定义 task 类的实例)。例如，使用 org.gradle.api.tasks.TaskContainer.create(String) 方法创建一个具有给定名称的空 task。当然，也可以在 build.gradle 文件中使用 task 关键字创建任务。如下面的代码：

// 创建的 task 的名称为 myTask
task myTask
// 创建 myTask，创建时，configuration 阶段使用闭包中的代码配置 task
task myTask { configure closure }
// 创建的 myTask，实例类型为 someType(如 DefaultTask)
// 不推荐这种语法
task myTask(type: SomeType)
task myTask(type: SomeType) { configure closure }

每个 task 都有一个 name，在其所属的 project 中唯一，并且每个 task 都有一个完全限定的路径(绝对路径)，该路径在所有 project 中的所有 task 中唯一。路径是所属 project 的路径和 task 名称的拼接。路径元素使用“:”字符分隔。

语法解释

gradle 生成的代码中，clean 代码的语法简直是四不像，理解起来很困难。 Gradle 创建 Task 的写法不是 Groovy 的标准语法吧？ 这篇文章已对这个语法做了解释，故不推荐下面示例的这种写法

task clean(type: Delete) {
    delete rootProject.buildDir
}

API 说明

Task API 说明

TaskContainer API 说明

task 的描述

描述一个 task，可以用 name，group，description，path，type。

• name 为任务的名称，可以唯一标识一个任务，如 help 任务

• description 为任务的描述，此信息对 gradle 没什么用，主要是方便人的理解

• group 用于将任务聚合起来。比如下图的 build 和 help 就是不同的 group

  

• path 为任务的位置。此值可以不用设置，创建任务后，使用 [:projectName:]taskName 即可找到任务，当在 project 内查找任务时可以省略 project 名

• type 表示任务的实际类型，通常是 Class，比如 Copy.class，Zip.class

// task name 是 publish
task publish(type: Copy) {
    from "sources"
    into "output"
}

configure(publish) {   
    group = 'Publishing'
    description = 'Publish source code to output directory'
}

task 的例子

我们可以自定义实现 task，也可以使用 Gradle 内置的 task。它们都有不同的使用目的。此处简单举几个例子聊聊。

finalizer task

当目标任务准备运行时，它的 Finalizer 任务会自动添加到相关任务图中。无论目标任务执行失败或着目标任务被认为是最新(up-to-date)的，Finalizer 任务都会执行。Finalizer 任务的此种特性在某些场景下十分有用。比如构建无论失败还是成功，资源都必须清理，此时可以使用 Finalizer 任务。

使用 Task.finalizedBy 方法添加目标任务执行结束后立即执行的对应任务，被添加的任务的执行顺序是无序的

lifecycle task

Lifecycle 任务是本身不工作的任务。它们通常没有任何任务 actions。他们仅代表构建执行的几个阶段。Gradle Base Plugin 定义了几个标准的生命周期任务，例如 check、assemble、build。所有的核心编程语言插件，如 Java 插件、Kotlin 插件，都继承了 Base Plugin，因此它们具有相同的基本生命周期任务集。

除非 Lifecycle 任务有 actions，否则它的结果是由它依赖的任务决定的。如果 Gradle 执行了这些依赖任务中的任何一个，则该 Lifecycle 任务都将被视为 EXECUTED。如果所有任务依赖项都是UP-TO-DATE，SKIPPED 或者 FROM-CACHE，则生命周期任务将被视为 UP-TO-DATE。如下图，assembleDebug/assembleRelease 任务的任意一个执行完成，assemble 任务就算执行完成。

• check：使用 check.dependsOn(task) 方法将验证任务与 Lifecycle 任务关联，比如在编译 app 前检查签名

• assemble：使用 assemble.dependsOn(task) 方法，将生成目标产物的任务与此 Lifecycle 任务关联。比如 jar 任务生成 Java libraries

• build：依赖于 check、assemble 任务。该任务旨在构建一切，包括运行所有测试任务、生成目标产物和生成文档。应尽量少将任务直接与 build 任务关联，因为 check 和 assemble 任务通常更合适

other task

Gradle 还内置了其它很多用途的 task，想要了解具体的用途和如何使用，可以查阅 Gradle 的 api 文档说明。比如 File 任务、Download 任务、Exec 相关的任务、Test 任务、Sign 任务等等。

task 的定位

每个 task 都属于一个 project，一个 project 可以包含多个 task，这些 task 都存放在 project 的 task container 中。TaskContainer 是 Collection 的一个实现类，TaskContainer 具有的能力，是其本身及其父类定义的。TaskContainer 简要的继承关系如下：

想要从 TaskContainer 中找到我们需要的 task 示例(或 task provider)，我们主要使用以下几种方式：

使用方式如下：

tasks.withType(Copy.class).forEach {
    // ....
}
tasks.matching { it.class == Copy.class }.forEach {
    // ....
}
def task = tasks.findByName("assembleDebug")
// tasks.getAt("assembleDebug") 等价于 tasks["assembleDebug"]
def task = tasks["assembleDebug"]
def task = tasks.findByPath(":app:assembleDebug")

task 的创建

创建方式

Gradle 中，任务创建主要有两种方式：实时创建和延后创建(懒加载)。

• 使用 create 创建的 task，会在代码执行到时(此时任务还没运行)立即创建 task 的实例。即使用 create 相关方法实时创建任务实例。

• 而使用 register 创建的 task，不会在代码执行到时立即创建 task 的实例。该方式只是提供一个 provider，只有等到 task 真正运行时，才会创建任务的实例。即使用 register 相关方法延迟创建任务实例(懒加载)。register 相关 api 属于 Gradle 定义的 Task Configuration Avoidance APIs。

// 返回的是 Provider<Task> 的实例
def hello = tasks.register('hello') {
    doLast {
        println 'hello'
    }
}
// 返回的是 Provider<Copy> 的实例
def copy = tasks.register('copy', Copy) {
    from(file('srcDir'))
    into(buildDir)
}
// 返回的是 task 的实例
task myTask { configure closure }

任务类型

任务的分类方式有很多种，但都可以归纳为两类：Gradle 内置任务或者自定义任务。前者如 Copy/Delete 等任务，后者则是我们继承了 Task 类实现的自定义类。自定义任务有很多指的深入的点，比如属性配置、增量构建、构造函数传参等等。此处仅简单的说明下构建函数传参。

构造函数传参

与在创建后配置 Task 的可变属性相反，我们可以通过 Task 类的构造函数传递参数不可变值(形如 Kotlin 中的 val)。使用步骤如下：

1. 使用 @javax.inject.Inject 注解相关的构造函数

2. 创建任务时，在参数列表的末尾传递构造函数参数

注意：在任何情况下，向构造函数传递的值都必须是非空的。如果尝试传递空值，Gradle 将抛出 NullPointerException，以指明哪个值为空

abstract class CustomTask extends DefaultTask {
    final String message
    final int number

    @Inject
    CustomTask(String message, int number) {
        this.message = message
        this.number = number
    }
}
tasks.register('myTask', CustomTask, 'hello', 42)

任务配置

我们编写 task 的创建代码时，应注意 Configuration 和 Execution 两个阶段。定义任务时，我们使用的闭包为配置闭包(代码在 Configuration 阶段执行)，不是运行闭包(代码在Execution 阶段执行)。如果想要代码在运行阶段执行，则需要使用 doLast 和 doFirst 等方法。方法传入的闭包，会加入到 task 的 actions 列表中，actions 列表会在 Execution 阶段执行。

Task Actions 可以翻译为任务动作。一个 task 由一连串的 action 组成。执行 task 时，调用 Action.execute 方法，依次执行每个action。

• 可以通过调用 doFirst(Action) 或 doLast(Action) 向 task 添加 action。

• Groovy 闭包也可视作 action。可以通过调用 doFirst(Closure) 或 doLast(Closure) 将 action 闭包添加到 task。

• 执行 action 时，可以抛出 2 个特殊异常以中止执行当前 action，并继续接下来的流程，而不会导致构建失败。

  • action 可以通过抛出 org.gradle.api.tasks.StopActionException 中止 action 的执行并继续执行 task 的下一个 action。

  • action 可以通过抛出 org.gradle.api.tasks.StopExecutionException 中止 task 的执行并继续执行下一个 task。

使用这些异常可以让我们拥有特定条件下，跳过任务执行或跳过部分任务执行的能力

tasks.register("test") {
    println "代码运行在 configuration 阶段"
    doLast {
        println "代码运行在 execution 阶段"
    }
}

注：Groovy 的闭包有个解析顺序(this, owner, delegate)，可以调用闭包的 setResolveStrategy 方法更改闭包的默认的解析顺序。可以给闭包设置 delegate(形如代码：closure.delegate = project)。

任务依赖

一个 task 可能依赖于其他 task，也可能被安排为始终在另一个 task 之后运行。Gradle 会确保在执行 task 时，所有 task 的依赖项和排序规则都生效，以确保所有 task 的正确执行。

• 定义任务依赖，通常需要用到任务名，如果某个任务依赖的是其他项目的任务，则需要跟进一步，使用 projectName + taskName 的形式：

  // 示例 1：定义两个任务之间的依赖
  project('project-a') {
      tasks.register('taskX')  {
          // 如果是其他项目的任务，可以在任务名前指定项目名
          dependsOn ':project-b:taskY'
          doLast {
              println 'taskX'
          }
      }
  }
  
  project('project-b') {
      tasks.register('taskY') {
          doLast {
              println 'taskY'
          }
      }
  }
  

• 除了使用 task 实例定义任务之间的依赖以外，还可以使用 TaskProvider 定义任务之间的依赖

  // 示例 2：使用 TaskProvider 定义两个任务之间的依赖
  def taskX = tasks.register('taskX') {
      doLast {
          println 'taskX'
      }
  }
  
  def taskY = tasks.register('taskY') {
      doLast {
          println 'taskY'
      }
  }
  
  taskX.configure {
      dependsOn taskY
  }
  

• 可以使用 lazy block 定义任务依赖，通常我们使用 Gradle Provider 代表 lazy block。解析时 lazy block 会被传递给正在确定自己依赖的任务。lazy block 应返回单个任务(single task)或任务对象的集合(tasks’ collection)，这些返回值会被视为任务的依赖

  // // 示例 3：使用 lazy block 定义两个任务之间的依赖
  def taskX = tasks.register('taskX') {
      doLast {
          println 'taskX'
      }
  }
  
  // Gradle Provider 代表  lazy block
  taskX.configure {
      dependsOn(provider {
          tasks.findAll { task -> task.name.startsWith('lib') }
      })
  }
  
  tasks.register('lib1') {
      doLast {
          println('lib1')
      }
  }
  
  tasks.register('lib2') {
      doLast {
          println('lib2')
      }
  }
  
  tasks.register('notALib') {
      doLast {
          println('notALib')
      }
  }
  

可以使用以下方法定义依赖项和排序规则：

• 使用 dependsOn(Object…) 方法或 setDependsOn(Iterable) 方法添加对另一个 task 的依赖。简单的讲，就是指定在 taskA 之前应执行的任务

• 使用 finalizedBy 方法添加某个任务执行结束后立即执行的任务，被添加的任务的执行顺序是无序的。简单的讲，就是指定在 taskA 之后应执行的任务

上述方法的参数 Object 可以使用以下任何类型：

• 一个用于表示 task 路径或名称的 String、CharSequence 或 groovy.lang.GString。相对路径表示相对于当前项目的 task。也可以指定其他 project 中的 task。

• 一个 task 对象

• 一个 TaskDependency 对象

• 一个 org.gradle.api.tasks.TaskReference 对象

• 一个 Buildable 对象

• 一个 org.gradle.api.file.RegularFileProperty 或 org.gradle.api.file.DirectoryProperty 对象

• 一个 Provider 对象。对象的 value 可以是此处列出的任何类型

• 一个 Iterable、Collection、Map 或数组对象。对象的值可以是此处列出的任何类型。iterable、collection、map、array 的元素可以递归包含

• 一个 Callable 对象。call() 方法返回的值可以是此处列出的任何类型。它的返回值可以递归包含。返回 null 会被视为空 Collection。

• 一个 Groovy Closure 或者 Kotlin function，闭包可以将 Task 作为参数。返回的值可能是此处列出的任何类型。它的返回值可以递归包含。返回 null 会被视为空 Collection。

• 除上述类型外的其他任何类型都会被视为错误

任务排序

指定 2 个任务的执行顺序，而不在 2 个任务之间引入显式依赖关系，在下列场景中很有用。

• 固定任务执行顺序：例如 ‘build’ 任务永远不会在 ‘clean’ 任务之前运行

• 在构建(build)之前运行构建验证：例如在构建 release 包之前验证是否拥有正确的签名

• 在运行“耗时任务”之前运行“快速任务”，以更快地获得反馈。例如单元测试任务应在集成测试任务前运行

• 收集特定类型任务执行结果的任务：例如"测试报告任务"包含了所有执行了的"测试任务"的结果输出

任务排序和任务依赖之间的主要区别在于，排序规则不会影响将执行哪些任务，只会影响它们的执行顺序。即不管有没有排序规则，我们都可以在没有 taskB 的情况下执行 taskA，反之亦然。

• taskA 和 taskB 可以独立。排序规则仅在两个 task 都执行时才有效

• 运行时如果指定了 –continue，taskB 在 taskA 执行失败的情况下仍然可能会执行

有两种指定任务顺序的方式：“must run after” 和 “should run after”。使用 mustRunAfter(Object…)、setMustRunAfter(Iterable)、shouldRunAfter(Object…)和 setShouldRunAfter(Iterable) 指定 task 之间的排序。

• 当使用 “must run after” 排序规则时，我们指定了只要 taskA 和 taskB 都运行，则 taskB 必须始终在 taskA 之后运行。代码表达为：taskB.mustRunAfter(taskA)。

• “should run after” 排序规则与 “must run after” 类似，但不那么严格。我们应该在”指定排序顺序有益但不是必须项“的情况下使用 “should run after” 排序规则，它会在两种情况下被忽略。

  • 使用该规则时，如果引入了排序循环(你在我之后，我在你之后)，则该规则被忽略。

  • 任务的并行执行启用时，一个任务如果除了 “should run after” 依赖之外，其余所有依赖关系都已经确定。那么无论这个任务的 “should run after” 依赖任务是否已经运行，它都会运行。

  // 出现了依赖循环，则 should run after 规则被忽略
  def taskX = tasks.register('taskX') {
      doLast {
          println 'taskX'
      }
  }
  def taskY = tasks.register('taskY') {
      doLast {
          println 'taskY'
      }
  }
  def taskZ = tasks.register('taskZ') {
      doLast {
          println 'taskZ'
      }
  }
  
  taskX.configure { dependsOn(taskY) }
  taskY.configure { dependsOn(taskZ) }
  taskZ.configure { shouldRunAfter(taskX) }
  
  /**
   * 执行 gradle -q taskX 命令，打印结果如下
   * taskZ
   * taskY
   * taskX
   */
  
  // taskZ 之前并没有打印 taskX，说明 should run after 没有生效
  

task 的忽略

Gradle 提供了几种忽略任务(跳过任务执行)的途径：

使用 onlyIf 方法

我们可以使用 onlyIf() 方法将允许任务执行的条件附加到任务中，执行条件在任务即将执行之前解析。可以使用闭包提供执行条件。只有当执行条件解析为 true 时，才会执行任务。闭包作为参数传递给任务，如果任务需要执行，则返回 true，如果需要跳过任务，则返回 false。

// 执行 gradle hello -PskipHello 命令时，任务会被跳过
def hello = tasks.register('hello') {
    doLast {
        println 'hello world'
    }
}

hello.configure {
    onlyIf { !project.hasProperty('skipHello') }
}

使用 StopExecutionException

跳过任务的逻辑除了用闭包来表达，还可以使用 StopExecutionException，Gradle 默认导入了该类。如果某个 action 抛出此异常，则跳过该 action 以及该任务的任何后续 action 的进一步执行。但 build 还是会继续执行下一个任务。

def compile = tasks.register('compile') {
    doLast {
        println 'We are doing the compile.'
    }
}
compile.configure {
    doFirst {
        if (true) {
            throw new StopExecutionException()
        }
    }
}
tasks.register('myTask') {
    dependsOn('compile')
    doLast {
        println 'I am not affected'
    }
}

此功能会很有用，如果 Gradle 提供的内置任务预置了相关逻辑，那么它允许我们对这些内置任务的内置 actions 添加控制这些 action 执行的条件。

设置 enabled flag

每个任务都有一个默认为 true 的 enabled flag(enable and disable tasks)。将其设置为 false 会阻止任务所有 action 的执行。disabled 的 task 将被标记为 SKIPPED

def disableMe = tasks.register('disableMe') {
    doLast {
        println 'This should not be printed if the task is disabled.'
    }
}

disableMe.configure {
    enabled = false
}

设置任务 timeout

每个任务都有一个超时属性(timeout property)，用于限制任务的执行时间。当一个任务达到超时时间时，它的任务执行线程被中断(be interrupted)。该任务将被标记为失败(failed)。它的 Finalizer tasks(通过 finalizedBy 方法添加的任务)仍将运行。如果 gradle 使用了 –continue flag，其他任务可以在该任务之后继续运行。

注意不能中断的任务就不能设置超时。Gradle 的所有内置任务都能中断，并及时响应超时。

tasks.register("hangingTask") {
    doLast {
        Thread.sleep(100000)
    }
    timeout = Duration.ofMillis(500)
}

增量构建

在讲 task 的运行之前，我们需要先讲解下 task 的增量构建。因为要了解 task 运行相关的知识，很多部分都需要先明白 task 增量构建相关的知识。

知识背景

任何构建工具的一个重要功能，就是能够避免重复执行已经完成的工作。例如编译过程中，如果源文件没有更改，则下次编译时就不需要重新执行编译任务。因为编译可能会花费大量时间，因此在不需要时跳过编译步骤可以节省大量时间。这种功能叫做执行结果检查，或者又叫增量构建。

Gradle 默认支持这种功能。在 Gradle 中，这个功能被称为"增量构建"(incremental build)，也可以叫做"最新检查"(Up-to-date checks)。我们可以在项目中看到他们的身影：在运行构建时，我们可以看到 UP-TO-DATE 文本出现在任务名称后。此结果就是增量构建生效的体现。

为了支持增量构建，Gradle 定义了两套 API：IncrementalTask​​Inputs API(Gradle 5.4之前) 和 InputChanges API。Gradle 5.4 之前定义了 IncrementalTask​​Inputs API，但该 API 有两个缺点：

• 使用 IncrementalTask​​Inputs 时，只能查询任务输入的所有文件更改。无法查询单个输入文件属性的更改。

• IncrementalTask​​Inputs API 不区分增量和非增量的任务输入，因此任务实现本身需要确定更改的来源。

IncrementalTask​​Inputs API 已被弃用，最终将被删除。新的 InputChanges API 取代了它并解决了它的缺点。如果需要使用旧 API，则需要查看 Gradle 5.3.1 用户手册文档。

概念定义

通常，Gradle task 会接受一些输入(inputs)，并生成一些输出(outputs)。如编译任务会将 java 源文件编译成 class。此时 java 源文件是输入，生成的 class 文件是输出。Gradle 使用输入输出来确定任务是否是最新的(up-to-date)，并且使用此信息来确定是否需要执行任何工作。如果输入或输出都没有改变，Gradle 就能跳过该任务。我们将 Gradle 的这些内容称为 Gradle 的增量构建支持(incremental build support)。

为了支持增量构建，Gradle 将 task 抽象为 3 大部分：inputs、TaskAction、outputs。

• inputs 代表任务的输入

• TaskAction 代表任务要执行的操作

• ouputs 代表任务使用输入执行对应操作后，生成的输出

要利用增量构建支持，我们需要向 Gradle 提供与任务有关的输入和输出(tasks’ inputs and outputs)信息，当然任务也可以被配置为仅具有输出(only have outputs)。在执行任务之前，Gradle 会检查输出，如果输出没有更改，将跳过任务的执行。在实际构建中，任务通常也有输入——包括源文件、资源和属性。 Gradle 在执行任务之前检查输入和输出都没有改变。

注意：当 Gradle 版本更改时，Gradle 会检测并删除使用旧版本 Gradle 执行的任务的输出，以确保最新版本的任务从已知的 clean 状态开始。

工作逻辑

在第一次执行任务之前，Gradle 会获取输入(inputs)的指纹，该指纹包含输入文件的路径和每个文件内容的哈希值。之后 Gradle 再执行任务。如果任务成功完成执行，Gradle 会获取输出(outputs)的指纹。该指纹包含输出文件集合和每个文件内容的哈希值。 Gradle 会为下次执行任务保留两个指纹。

之后在每次执行任务之前，文件的状态信息(即 lastModified 和 size)更改，Gradle 都会获取输入和输出的新指纹。如果新指纹与之前的指纹相同，Gradle 会假定输出结果是最新的(up-to-date)并跳过该任务。如果指纹不相同，Gradle 将执行任务并保留生成的新指纹。

• 如果文件的状态信息(即 lastModified 和 size)没有改变，Gradle 将复用上次执行的文件指纹。这意味着当文件的统计信息没有更改时，Gradle 不会检测更改。

• Gradle 还将任务的代码(任务的实现逻辑)视为任务输入的一部分。当任务、任务的操作(task action)或其依赖任务在两次执行之间发生变化时，Gradle 会认为该任务已过期。为了跟踪任务、任务操作和嵌套输入的实现，Gradle 使用类名和包含类实现的类路径的 id。在某些情况下，Gradle 无法准确跟踪实现：

  • 未知的 classloader。当 Gradle 没有创建用于加载实现的 classloader 时，无法确定类路径。

  • java lambda 表达式。Java lambda 类是在运行时使用不确定的类名创建的。因此，类名并不能标识 lambda 的具体实现以及不同 Gradle 运行之间的更改

  当无法精确跟踪任务、任务的操作或嵌套输入的实现时，Gradle 会禁用该任务的任何缓存。这意味着该任务将永远不会是最新的(up-to-date)，并且任务不会从构建缓存中加载

• 如果一个文件属性(如持有 Java 类路径的属性)对顺序敏感。在比较此类属性的指纹时，即使文件顺序发生变化也会导致任务过时(out-of-date)

• 如果任务指定了输出目录，则自上次执行以来添加到该目录的任何文件都将被忽略，并且不会导致任务过期，这是因为不相关的任务可以共享一个输出目录而不会相互干扰。如果出于某些考虑这不是我们想要的行为，则可以考虑使用 TaskOutputs.upToDateWhen(Closure)

• 更改无效文件的有效性(如将损坏的文件链接的目标修改为有效文件，反之亦然)将被最新检查(up-to-date check)检测到，并被其处理。

简而言之，增量构建中，Gradle 会通过检测输入输出的校验和，对比本次和上次构建的任务的输入输出是否有任何变化。如果没有，Gradle 认定任务是最新的(up to date)，会跳过执行该任务的操作(action)。

非增量场景补充

在很多情况下，Gradle 无法确定需要处理哪些输入文件，此时需要以非增量方式执行。它们包括以下场景：

• 以前的执行没有可用的历史记录

• 使用不同版本的 Gradle 进行构建。目前 Gradle 只支持使用当前版本的任务历史记录

• 添加到任务的 TaskOutputs.upToDateWhen 条件返回了 false(表示任务不是 up-to-date，而是 out-of-date)

• 输入属性已更改

• 非增量输入文件属性(non-incremental input file property)已更改

• 一个或多个输出文件已更改

在这些情况下，Gradle 会将所有输入文件视为 ADDED，并且 getFileChanges() 方法将返回包含输入属性的所有文件的详细信息。

执行结果

Gradle 执行 task 时，会在控制台中或通过 Tooling API (在代码中使用)为 task 标记不同的执行结果。打上哪些状态标签取决于 task 有是否要执行的操作(action)、task 是否应该执行这些操作、task 是否确实执行了这些操作以及 task 的这些操作是否有结果更改。task 的标签类型有：

• (no label) 或者 EXECUTED：无标签或者标签为 EXECUTED，则代表 task 执行了 actions。以下几种场景会打上此标签：

  • task 有 actions 作为构建的一部分被执行

  • task 无 actions 执行，但是有依赖的 task，并且所有依赖的 task 都是 EXECUTED 状态

• UP-TO-DATE：task 的 outputs 没有任何改变。以下几种场景会打上此标签：

  • 任务有 inputs 和 outputs，但它们都没有任何变化

  • task 有 actions 执行，但是该 task 告诉 gradle 执行 actions 的 outputs 没有变化

  • task 无 actions 执行，但是有依赖的 task，并且所有依赖的 task 都是 UP-TO-DATE 状态，或 SKIPPED 状态，或者 FROM-CACHE 状态

  • task 无 actions 执行，并且无依赖的 task

• FROM-CACHE：task 的 outputs 可以从上一次的运行结果中找到

  • 任务从构建缓存拿了 ouputs 时会打上此标签。具体可以看： Build Cache (gradle.org)

• SKIPPED：task 并没有执行 actions

  • 构建运行前，task 在命令行中被显式的移除，不用运行时会打上此标签。详情见： Command-Line Interface (gradle.org)

  • 任务有 onlyIf 块限制，并且 onlyIf 结果返回了 false

• NO-SOURCE：任务不需要执行 actions

  • 任务有 inputs 和 outputs，但没有源码时会打上此标签。例如 JavaCompile 任务需要的 .java 源文件不存在时

代码定义

输入确定方式

处理增量构建时，一个很重要的议题是：如何确定哪个内容应作为任务的输入？

其实输入的一个重要特征就是它会影响一个或多个输出。如果某个内容会影响输出，则该内容应成为任务的输入；反之如果某个内容不影响输出，则该内容不必成为任务的输入。

从上面的 task 概念拆分图中可以看出，如果源文件不同或 java 版本不同，则会生成不同的字节码。这决定了它们应成为任务的 inputs。但是编译时是否有 500MB 或 600MB 的最大可用内存，由 memoryMaximumSize 属性确定，对生成的字节码 outpus 没有影响，则该属性无需作为 inputs。在 Gradle 术语中，memoryMaximumSize 只是一个内部任务属性。

另外一个值得注意的点是，增量构建要求任务至少有一个任务输出，即使任务至少定义了输入，否则增量构建将不起作用。

综上，要使用 Gradle 提供的增量构建能力，对开发者而言，操作十分简单：我们只需要告诉 Gradle 哪些 task properties 是输入，哪些是输出，并定义任务的操作即可。

• 如果 task properties 会影响输出，则需要将其注册为输入。注意：如果不注册，该任务将被认为是最新(up-to-date)的，即使任务实际上不是最新的

• 如果 task properties 不影响输出，则不要将其注册为输入，否则任务可能会在不需要时执行。

• 如果任务在完全相同的输入的前提下，生成了不同输出。则此任务不应配置为增量构建，因为此时最新检查(up-to-date check)将不起作用

实现方式

Gradle 中，主要有两种方式让任务获得增量构建的能力：注解和运行时 API。

• 注解：注解在自定义 Task 中使用，是官方推荐的实现增量构建的方式

• 运行时 API：在 task 的配置代码中使用(不仅限于自定义的 Task)。运行时 API 的一个重要的特点是可以让非增量的任务变得可增量构建。但是官方不推荐优先使用运行时 API，运行时 API 更适用于无法使用注解的情况。如我们看不到第三方插件定义的 task 的源码，则我们无法使用注解，但又想让该任务获得增量构建的能力，此时我们就可以使用运行时 API

使用注解

下列讲解中：IO 代表 inputs and outputs，即输入输出。而 ACTION 代表 task action。

IO：注解示例

当我们自定义任务类时，只需两步即可使增量构建生效。

1. 为任务的输入和输出创建指定类型的 Property

2. 为每个属性添加适当的注解。

注意注解必须放在 getter 或 Groovy 属性(properties)上。注解如果放在属性的 setter 上，或者如果属性上没有相应的注解，则属性将不被视为 inputs。

Gradle 支持四种主要的输入和输出类别：

• 简单的值，使用 @Input 注解

  • 数字、字符串等主要类型

  • 实现了 Serializable 的类型

• 文件相关类型，如 @InputFiles 注解

  • RegularFile 类

  • Directory 类

  • 标准 File 类

  • FileCollection 类

  • Project.file 和 Project.files 方法支持的 file/dir 属性

• 依赖解析结果，如

  • 该类型仅支持包装在 Provider 类中，不支持单独使用

  • artifact metadata 的 ResolvedArtifactResult 类

  • dependency graphs 的 ResolvedComponentResult 类

• 嵌套的值，使用 @Nested 注解

  • 自定义的类作为输入，可以使用 @Nested 注解，gradle 能够从中读取 inputs 和 outputs

举个列子，假设一个模版处理框架任务具有三个输入和一个输出：

• 输入：模版源代码

• 输入：java bean 数据(Model data)

• 输入：模版引擎

• 输出：outputs 的保存位置作为输出

// buildSrc/src/main/java/org/example/ProcessTemplates.java
package org.example;

import java.util.HashMap;
import org.gradle.api.DefaultTask;
import org.gradle.api.file.ConfigurableFileCollection;
import org.gradle.api.file.DirectoryProperty;
import org.gradle.api.provider.Property;
import org.gradle.api.tasks.*;

public abstract class ProcessTemplates extends DefaultTask {
    // 简单的值，输入
    @Input
    public abstract Property<TemplateEngineType> getTemplateEngine();
    @InputFiles
    public abstract ConfigurableFileCollection getSourceFiles();
    // 自定义 Model Data，嵌套类型
    @Nested
    public abstract TemplateData getTemplateData();
    // 输出
    @OutputDirectory
    public abstract DirectoryProperty getOutputDir();
    // 任务动作
    @TaskAction
    public void processTemplates() {
        // ...
    }
}

// buildSrc/src/main/java/org/example/TemplateData.java
import org.gradle.api.provider.MapProperty;

public abstract class TemplateData {
    @Input
    public abstract Property<String> getName();
    @Input
    public abstract MapProperty<String, String> getVariables();
}

上述代码中有很多需要讨论的内容，此处挨个讲解：

• templateEngine

  表示在处理源模板时使用哪个引擎。引擎类型其实可以定义为字符串。但在本例中，我们选择了自定义枚举，因为它提供了更大的类型信息和安全性。并且枚举自动实现了 Serializable，我们可以将其视为一个简单的取值并使用 @Input 注解，就像我们使用 String 一样

• sourceFiles

  表示任务将处理的模板源文件。单个文件和文件集合需要使用不同的注解。本例中，我们需要处理输入文件的集合，因此我们使用了 @InputFiles 注解。下面会列举更多关于文件的注解

• templateData

  本例中，我们使用了自定义类来表示 model data(java bean)。但是，它没有实现 Serializable，所以我们不能使用 @Input 注解。但这并不是什么大问题，因为 TemplateData 中的属性(字符串和 hashmap 继承自 Serializable))是可序列化的，可以使用 @Input 进行注解，然后我们可以在 templateData 上使用 @Nested 注解，让 Gradle 知道这是一个具有嵌套输入的属性

• outputDir

  生成的文件所在的目录。与输入文件一样，输出文件和目录也有几个注解。表示单个目录的属性需要使用 @OutputDirectory 注解

本例适用于多个源文件。那如果只有一个源文件发生更改会怎样呢？任务是再次处理所有源文件还是只处理那个修改后的文件？实际上这取决于任务的具体实现。如果是后者，那么任务本身就是增量的，这与我们在此处讨论的功能不同。此处我们讨论的是 Gradle 通过其内置的 incremental build support 功能帮助 task 实现增量构建的能力

IO：注解列表

输入输出可用的注解如下表所示：

• 表格中的 File 类型可以是 Project.file(Object) 方法接受的任何类型

• Iterable 类型可以是 Project.files(Object…​) 方法接受的任何类型。甚至是 Callable、closures。FileCollection 和 FileTree 也是 Iterable 类型的

• Map 类型本身可以封装在 Callables、closures 中

IO：注解优先级

子类会继承修饰父类(包括接口)的注解，对于修饰某个属性的注解，子类的注解会覆盖掉父类的注解，父类的注解会覆盖接口中的注解。即 child > parent > interface。

上述表中的 Console 和 Internal 注解是特殊情况，因为它们既不是任务输入也不是任务输出。那么问题来了，为什么要使用它们呢？因为这样就可以利用 Java Gradle Plugin Development plugin (即帮助开发 plugin 的 plugin)来帮助我们开发和发布自己的插件。此插件会检查我们的自定义 task 类的 properties 是否缺少增量构建注解。这可以防止我们在开发过程中忘记添加适当的注解

IO：使用依赖解析结果

依赖解析结果即 dependency resolution results。依赖关系解析结果可以通过两种方式作为任务输入使用：

• 使用 ResolvedComponentResult 处理已解析了的元数据的图(the graph of the resolved metadata)。解析图可以通过 Configuration 的 incoming resolution result 中懒加载获取，并连接到 @Input 属性

  // inputs 定义输入
  @Input
  public abstract Property<ResolvedComponentResult> getRootComponent();
  

  // 获取配置
  Configuration runtimeClasspath = configurations.getByName("runtimeClasspath");
  
  // input 绑定输入结果
  task.getRootComponent().set(
      runtimeClasspath.getIncoming().getResolutionResult().getRootComponent()
  );
  

• 使用 ResolvedArtifactResult 处理已解析了的产物的集合(the flat set of the resolved artifacts)。已解析的工件集可以从 Configuration 的 incoming artifacts 中懒加载获取。下面的例子中，鉴于 ResolvedArtifactResult 类型包含元数据和文件信息，实例只需要在连接到 @Input 属性之前转换为元数据即可：

  // 定义输入
  @Input
  public abstract ListProperty<ComponentArtifactIdentifier> getArtifactIds();
  

  Configuration runtimeClasspath = configurations.getByName("runtimeClasspath");
  Provider<Set<ResolvedArtifactResult>> artifacts = runtimeClasspath.getIncoming().getArtifacts().getResolvedArtifacts();
  // 将元数据转换为 id，并绑定到 inputs
  task.getArtifactIds().set(artifacts.map(new IdExtractor()));
  
  static class IdExtractor
      implements Transformer<List<ComponentArtifactIdentifier>, Collection<ResolvedArtifactResult>> {
      @Override
      public List<ComponentArtifactIdentifier> transform(Collection<ResolvedArtifactResult> artifacts) {
          return artifacts.stream().map(ResolvedArtifactResult::getId).collect(Collectors.toList());
      }
  }
  

  graph 和 set 都可以和解析的文件信息相结合和扩充，更具体的讲解见： Implementing tasks with dependency resolution result inputs Sample (gradle.org)

IO：使用 classpath 注解(可跳过)

除了 @InputFiles 注解以外，对于 JVM 相关的任务，Gradle 还需处理类路径输入(classpath inputs)(涉及 JVM，Android 开发一般用不上)。

当 Gradle 查找任务变更时，运行时和编译类路径(runtime and compile classpaths)的处理方式会有所不同。

与使用 @InputFiles 注解的输入属性相反，对于类路径属性(classpath properties)，文件集合中定义的顺序很重要。另一方面，计算输入是否改变时，类路径本身上的目录和 jar 文件的名称和路径、jar 包中的时间戳、类文件和资源的顺序，都会被忽略。因此重新创建具有不同文件日期的 jar 包不会使任务过期(换句话讲，选取 class 所在的 jar 时，顺序很重要。而 jar 中的文件和资源的顺序、时间戳这些不重要)

运行时类路径用 @Classpath 标记，它们通过类路径规范提供更深入的定制。

使用 @CompileClasspath 注解的输入属性被视为 Java 编译时类路径。除了前面提到的类路径规则之外，编译类路径还会进一步忽略除对 class 以外的所有内容的更改。 Gradle 使用 Java 编译说明( The Java Plugin (gradle.org) )中描述的相同逻辑来进一步过滤不改变类的 ABI 的更改。这意味着仅涉及类实现的更改不会使任务过时。

IO：嵌套输入

在解析输入和输出属性需要使用那些数据时，如果检测到 @Nested 任务属性，Gradle 会使用 @Nested 任务属性的子属性。它可以发现运行时配置的所有子属性

• Provider 被 @Nested 修饰时，Provider 的值被视为嵌套输入(nested input)

• iterable 被 @Nested 修饰时，iterable 中的每个元素都被视为单独的嵌套输入。iterable 中的每个嵌套输入都被分配了一个名称，默认情况下，该名称是 $ 符号后跟对象在 iterable 中的索引，例如 $2。如果 iterable 中的元素实现了 Named 接口，则该名称用作对应属性的名称(每个 setter 都可以当作属性使用，如编译任务的 setSource 方法)。如果不是所有元素都实现了 Named 接口，那么 iterable 中元素的顺序对于可靠的 up-to-date 检查和缓存至关重要。不允许有多个具有相同名称的元素。

• map 被 @Nested 修饰，每个 value 会被视为一个嵌套输入，使用 key 作为名称。

嵌套输入的类型和类路径也被跟踪。这确保了对嵌套输入实现的更改会导致构建过时。示例可见： Authoring Tasks (gradle.org)

IO：数据验证

• Gradle 会对带注解的属性执行一些基本验证。此类验证提高了构建的稳健性，使我们能够快速识别与输入和输出相关的问题。Gradle 在任务执行之前会对下列带注解的属性执行以下操作:

  • @InputFile：验证该属性是否设置了 value，并验证 value 路径表示的文件(不是目录)是否存在

  • @InputDirectory：同 @InputFile，区别是验证的目录(不是文件)是否存在

  • @OutputDirectory：验证路径是否与文件匹配；并验证目录存在，不存在则创建该目录

• 如果一个任务(生产者)的输出作为另一个任务(消费者)的输入，则 Gradle 会检查这两个任务的依赖性。当生产者和消费者任务同时执行时，构建将失败，以避免产生不正确的状

• 如果我们想要禁用某些验证，特别是当输入文件实际上可能真的不存在时。可以使用 @Optional 注解来告诉 Gradle 特定输入是可选的(仅适用于 Optional API 相关的注解)，如果相应的文件或目录不存在，构建不应输出失败的结果。

ACTION：增量任务操作

对于增量处理输入的任务，该任务必须包含增量任务操作(incremental task action)。增量任务操作是一个具有单个 InputChanges 入参的任务操作方法(task action method)，该参数告诉 Gradle 该操作只想处理更改的输入。此外，该任务需要使用 @Incremental 注解或 @SkipWhenEmpty 注解声明至少一个增量文件输入属性。

注意要查询输入文件属性(input file property)的增量更改，该属性(property)始终需要返回相同的实例。完成此操作的最简单方法是对此类文件属性使用以下类型之一：RegularFileProperty、DirectoryProperty 或 ConfigurableFileCollection。

• 对于给定的基于文件类型输入属性(file-based input property)，无论是 RegularFileProperty、DirectoryProperty 还是 ConfigurableFileCollection 类型，增量任务操作可以使用 InputChanges.getFileChanges() 方法来找出哪些文件发生了更改。该方法返回一个可以查询以下内容的 FileChange 类型的 Iterable：

  • 通过 getFile() 方法获取受影响的文件

  • 通过 getChangeType() 方法获取文件变化的类型：ADDED, REMOVED 或者 MODIFIED(文件的添加、删除或者修改)

  • 通过 getNormalizedPath() 方法获取获取变化文件的路径。路径的返回值受 PathSensitivity、Classpath、CompileClasspath 等设置的影响

  • 通过 getFileType() 查询文件的类型：DIRECTORY、FILE 或者 MISSING

• 可以使用 InputChanges.isIncremental() 方法检查任务是否是增量执行的

• 可以使用 Task.doNotTrackState() 方法抛弃了增量编译的能力

以下示例演示了具有目录输入的增量任务。它假设该目录包含一组文本文件，操作将它们复制到输出目录，并反转每个文件中的文本。需要注意的关键点是 inputDir 属性的类型、其注解以及操作(execute() 方法)如何使用 getFileChanges() 处理部分更改的文件。如果相应的输入文件已被删除，同时还可以看到该操作如何删除目标文件：

// 注意 abstract 关键字
abstract class IncrementalReverseTask extends DefaultTask {
    @Incremental
    @PathSensitive(PathSensitivity.NAME_ONLY)
    @InputDirectory
    abstract DirectoryProperty getInputDir()

    @OutputDirectory
    abstract DirectoryProperty getOutputDir()

    @Input
    abstract Property<String> getInputProperty()
    /**
     * 任务操作只需要为任何过时的输入生成输出文件，
     * 并删除已被删除的输入对应的输出文件
     */
    @TaskAction
    void execute(InputChanges inputChanges) {
        println(inputChanges.incremental
            ? 'Executing incrementally'
            : 'Executing non-incrementally'
        )

        inputChanges.getFileChanges(inputDir).each { change ->
            if (change.fileType == FileType.DIRECTORY) return

            println "${change.changeType}: ${change.normalizedPath}"
            def targetFile = outputDir.file(change.normalizedPath).get().asFile
            if (change.changeType == ChangeType.REMOVED) {
                targetFile.delete()
            } else {
                targetFile.text = change.file.text.reverse()
            }
        }
    }
}

如果由于某种原因任务以非增量的方式执行，则所有文件都被视为 ADDED，与之前执行的状态无关。在这种情况下，Gradle 会自动移除之前的输出，因此增量任务只需要处理给定的文件即可(不用考虑之前的处理结果)。

使用运行时 API

自定义 task 类是一种将我们自定义的构建逻辑引入增量构建领域的简单方法，但我们并不是总能使用这种方式。例如使用第三方 plugin 提供的 task，我们无法更改其源码。如果我们无法访问自定义任务类的源代码，那我们就无法添加上面介绍的任何注解。如果这时候我们想要启用增量构建该怎么做？Gradle 为这样的场景提供了运行时 API(runtime API)。它可以用于任何任务实例。

代码示例

运行时 API 是通过几个见名知义的属性提供的，这些属性可用于每个 Gradle 任务：

• Task.getInputs() 方法，代表输入，方法返回 TaskInputs 实例

• Task.getOutputs() 方法，代表输出，方法返回 TaskOutputs 实例

• Task.getDestroyables() 方法，代表被任务删除的 files 或 dirs，方法返回 TaskDestroyables 实例

这些对象中定义的方法允许我们指定构成任务输入和输出的文件、目录和值(files, directories and values)。实际上，运行时 API 基本上具有与使用注解相同的功能，它所缺少的只是 @Nested 的等价物。

tasks.register('processTemplatesAdHoc') {
    // engine input property 的值是 TemplateEngineType.FREEMARKER
    inputs.property('engine', TemplateEngineType.FREEMARKER)
    // sourceFiles input files 的值是 src/templates
    inputs.files(fileTree('src/templates'))
        .withPropertyName('sourceFiles')
        .withPathSensitivity(PathSensitivity.RELATIVE)
    inputs.property('templateData.name', 'docs')
    inputs.property('templateData.variables', [year: '2013'])
    outputs.dir(layout.buildDirectory.dir('genOutput2'))
        .withPropertyName('outputDir')

    doLast {
        // Process the templates here
    }
}

该示例有很多可以讨论的点。

• 实际上，我们应该编写一个自定义任务类实现上述逻辑，因为它其实可以是一个具有多个配置选项的较复杂的实现。此例并有设计其他任务属性来存储根源代码文件夹(root source folder)、输出目录的位置或任何其他设置，此处仅是为了强调运行时 API 不需要任务具有任何其他条件就可以达到与自定义任务注解相同的功能，所以简单点写。在增量构建方面，上述任务实例的行为与自定义任务类相同。

• 运行时 API 和注解之间的一个显着区别是运行时 API 缺少直接对应 @Nested 的方法。这就是为什么该示例使用了两个 property() 声明，每个 TemplateData 属性一个。在实现带有嵌套值的运行时 API 时，我们应该使用相同的方式。任何给定的任务都可以声明 destroyables 或 inputs/outputs，但不能同时声明两者

• 所有输入和输出的定义都是通过 inputs 和 outputs 的相关方法完成的，例如 property()、files() 和 dir()。 Gradle 对参数值执行 up-to-date 检查以确定任务是否需要再次运行。每个方法都对应一个增量构建注解，例如，inputs.property() 对应 @Input 注解，outputs.dir() 对应 @OutputDirectory 注解

• 任务可删除的文件可以通过 Task.getDestroyables.register() 指定

  tasks.register('removeTempDir') {
      destroyables.register(layout.projectDirectory.dir('tmpDir'))
      doLast {
          delete(layout.projectDirectory.dir('tmpDir'))
      }
  }
  

注意如果任务类型已经在使用增量构建注解，则使用相同名称的运行时 API 注册输入或输出将导致错误。

使任务可增量构建

上面我们讲过，运行时 API 可以让非增量构建的任务具备增量构建的能力。要实现这种功能，主要有两种方式：

• 如果可以拿到 task 实例，则可以直接对 task 实例增加配置项。此种方式在上面的例子中已经讲解过了。

• 如果无法拿到 task 实例，则可以新定义一个包装任务，原任务要做的任务放入此包装任务中，包装任务负责检测原任务的输入输出。借用讲解文件时的例子，我们来说明这种功能如何实现。

因为 Project.copy(org.gradle.api.Action) 方法进行复制时默认不是增量构建的，并且无法拿到 Task 实例。所以我们需要对该方法进行包装。

我们定义一个 copyIncremental 方法包装 copy 操作。copyIncremental 任务是增量的，其输入来自于 copyTask，输出为 some-dir。虽然 copyIncremental 任务并没有直接改动这些文件，但是 copy 方法使输出发生了改变，此时增量编译检查也能生效(copyIncremental 定义输入输出，copy 使用了输入输出。inputs 和 outputs 可以改变，一改变就能检测到)。

tasks.register('copyIncremental') {
    // inputs 的 up-to-date check 增加 copyTask
    // 返回的是 TaskInputFilePropertyBuilder，
    // 属性名为：inputs(第二行代码)
    inputs.files(copyTask)
        .withPropertyName("inputs")
        .withPathSensitivity(PathSensitivity.RELATIVE)
    // outputs 的 up-to-date check 增加 some-dir
    // 返回的是 TaskOutputFilePropertyBuilder
    // 属性名为：outputDir(第二行代码)
    outputs.dir('some-dir')
        .withPropertyName("outputDir")
    doLast{
        copy {
            // 复制 copyTask 的 ouput 到 some-dir
            from copyTask
            into 'some-dir'
        }
    }
}

更多配置

• 运行时 API 方法虽然只允许我们声明输入和输出。但是针对文件类型，运行时 API 会返回一个 TaskInputFilePropertyBuilder 类型的构建器(builder)，该 builder 允许我们提供有关这些输入和输出的更多额外信息。我们可以在其 API 文档中了解构建器提供的所有选项，此处仅展示一个简单的示例，方便我们了解它可以做什么。

  假设我们不想在没有源文件的情况下运行 processTemplates 任务(无论它是否 clean build)，毕竟如果没有源文件，任务就没有什么可做的了。此时我们可以这样配置：

  tasks.register('processTemplatesAdHocSkipWhenEmpty') {
      // ...
      inputs.files(fileTree('src/templates') {
              include '**/*.fm'
          })
          .skipWhenEmpty()
          .withPropertyName('sourceFiles')
          .withPathSensitivity(PathSensitivity.RELATIVE)
          .ignoreEmptyDirectories()
      // ...
  }
  

  上述实例中，TaskInputs.files() 方法返回一个TaskInputFilePropertyBuilder。调用 skipWhenEmpty 方法等价于使用 @SkipWhenEmpty 对属性进行注释。

• 假设有一个将 processTemplates 任务的输出打包的归档任务。我们肯定能知道归档任务运行前需要先运行 processTemplates 任务，因此我们会添加显式的 dependsOn。但是，如果我们使用下面的代码定义归档任务，Gradle 会自动使 packageFiles 任务依赖于 processTemplates。Gradle 之所以这样做，是因为 Gradle 知道 packageFiles 的输入之一是 processTemplates 任务的输出。这种功能在 Gradle 被称为推断的任务依赖(an inferred task dependency)：

  tasks.register('packageFiles', Zip) {
      from processTemplates.map {it.outputs }
  }
  

  因为 from() 方法可以接受任务实例作为参数，例子也可以简化为如下形式。在具体的实现中，from() 方法会使用 project.files() 方法包装入参，这会将任务的输出转为文件集合。换句话说， from(taskObject) 是一个特例，下述代码也是一个特例，非普遍情况。

  tasks.register('packageFiles2', Zip) {
      from processTemplates
  }
  

• Copy 任务的 from() 方法没有用 @InputFiles 注解，但任何传递给它的文件都被视为任务的正式输入。它是如何工作的呢？代码实现其实非常简单，我们可以对自己的自定义任务使用相同的技术来改进，以便将文件直接添加到适当的注解属性。例如，以下示例介绍了如何将 sources() 方法添加到我们之前介绍的自定义 ProcessTemplates 类：

  public abstract class ProcessTemplates extends DefaultTask {
      // ...
      @SkipWhenEmpty
      @InputFiles
      @PathSensitive(PathSensitivity.NONE)
      public abstract ConfigurableFileCollection getSourceFiles();
  
      public void sources(FileCollection sourceFiles) {
          getSourceFiles().from(sourceFiles);
      }
  
      // ...
  }
  
  tasks.register('processTemplates', ProcessTemplates) {
      // ...
      outputDir = file(layout.buildDirectory.dir('genOutput'))
      sources fileTree('src/templates')
  }
  

• 如果我们想将任务作为参数并将它们的输出视为输入，我们可以使用 project.layout.files() 方法解析任务。使用这个方法的一个好处是，我们的自定义方法可以通过 Gradle 自动推断任务的依赖关系。如下所示：

  // ProcessTemplates 类
  public void sources(TaskProvider<?> inputTask) {
      getSourceFiles().from(getProject().getLayout().files(inputTask));
  }
  
  def copyTemplates = tasks.register('copyTemplates', Copy) {
      into file(layout.buildDirectory.dir('tmp'))
      from 'src/templates'
  }
  
  tasks.register('processTemplates2', ProcessTemplates) {
      // ...
      sources copyTemplates
  }
  

  注意如果我们正在开发一个将源文件集合作为输入的任务，例如这个示例，那么请考虑使用 Gradle 内置的 SourceTask 任务。它将使我们免于定义一些如需要放到 ProcessTemplates 任务中的属性和方法。此处仅是为了举例，才自定义了 source。

• 将 @OutputDirectory 链接到 @InputFiles。

  想将一个任务的输出链接为另一个任务的输入时，输入输出的类型通常需要匹配(例如文件输出属性(File output property)可以分配给文件输入(File input))，并且需要一个简单的属性表示该链接。

  不幸的是，当我们希望任务的 @OutputDirectory 中的文件成为另一个任务的 @InputFiles 属性的源时，这种方法就失效了。因为两者具有不同的类型，因此属性分配将不起作用。

  例如，假设我们想使用 Java 编译任务的输出作为自定义任务(任务名为 Instrument)的输入。该自定义任务检测包含 Java 字节码的文件，并且有一个用 @InputFiles 注解的 classFiles 属性。

  最初我们可能会尝试像这样配置任务：

  plugins {
      id 'java-library'
  }
  
  tasks.register('badInstrumentClasses', Instrument) {
      classFiles.from fileTree(tasks.named('compileJava').map { it.destinationDir })
      destinationDir = file(layout.buildDirectory.dir('instrumented'))
  }
  

  这段代码没有明显的问题，但是我们可以从控制台输出中看到缺少编译任务 compileJava 的执行(即用 fileTree() 意味着 Gradle 无法自动推断任务依赖)。此问题有几个解决方案。

  1. 我们需要通过 dependsOn 方法在 instrumentClasses 和 compileJava 之间添加显式任务依赖项。

  2. 使用 TaskOutputs.files 方法，如以下示例所示：

     tasks.register('instrumentClasses', Instrument) {
         classFiles.from tasks.named('compileJava').map { it.outputs.files }
         destinationDir = file(layout.buildDirectory.dir('instrumented'))
     }
     

  3. 使用 project.files()、project.layout.files() 或 project.objects.fileCollection() 方法之一代替 project.fileTree() 方法，以便让 Gradle 能自动访问适当的属性。因为 project.files()、project.layout.files() 和 project.objects.fileCollection() 可以将任务作为参数，而 fileTree() 不能

     tasks.register('instrumentClasses2', Instrument) {
         classFiles.from layout.files(tasks.named('compileJava'))
         destinationDir = file(layout.buildDirectory.dir('instrumented'))
     }
     

  上述方法的缺点是源任务的所有文件输出都会成为目标(此处是 instrumentClasses2)任务的输入文件。当源任务只有一个文件输出(file-based output)是 OK 的(比如 JavaCompile 任务)；但是当源任务有多个输出，而我们只想指定其中一个作为目标任务的输入时，上述方法就不行了。此时需要使用下面的方法。

  • 使用 builtBy 方法(等价于 task 的 dependsOn 方法)明确告诉 Gradle 哪个任务生成输入文件：

  tasks.register('instrumentClassesBuiltBy', Instrument) {
      classFiles.from fileTree(tasks.named('compileJava').map { it.destinationDir }) {
          // 声明产生此 ConfigurableFileCollection 的任务
          // Gradle 会自动推导出任务之间的依赖关系
          builtBy tasks.named('compileJava')
      }
      destinationDir = file(layout.buildDirectory.dir('instrumented'))
  }
  

增量状态缓存

使用 Gradle 的 InputChanges API 并不是创建增量构建任务的唯一方法。Kotlin 编译器等工具内置了增量功能。这些功能实现的方式通常是编译器将一些有关上次执行状态的分析数据存储在某个文件中。如果这样的状态文件是可重定位的，那么它们可以被视为任务的输出。这样当任务的运行结果被从缓存中加载时，下次执行也可以使用从缓存中加载的分析数据

但是，如果状态文件是不可重定位的，那么它们就不能通过构建缓存共享。实际上，当从缓存加载任务时，必须清理任何此类状态文件，以防止旧状态在下次执行时搞乱编译工具。

通过 task.localState.register() 方法声明这些陈旧文件或使用 @LocalState 注释标记属性，Gradle 可以确保删除这些旧的状态文件

禁用最新检查

Gradle 会自动处理对输出文件和目录的最新检查。但当任务输出不是普通的产物，如对 Web 服务或数据库表的更新；或者有时我们需要有一个始终应该运行的任务。该怎么做呢？

此时可以使用 Task.doNotTrackState() 方法，完全禁用任务的最新(up-to-date)检查；如果是自定义任务，还可以使用 @UntrackedTask 注解代替，而不是调用 Task.doNotTrackState() 方法。

例如 Gradle 可以集成如 Git 的外部工具，它们都做自己的最新(up-to-date)检查。此时 Gradle 再进行最新检查就没有多大意义了。我们可以通过在包装工具的任务上使用 @UntrackedTask 注解或者使用运行时 API 方法 Task.doNotTrackState() 来禁用 Gradle 的最新检查。

// 类：buildSrc/src/main/java/org/example/GitClone.java
@UntrackedTask(because = "Git tracks the state")                                           
public abstract class GitClone extends DefaultTask {
    @Input
    public abstract Property<String> getRemoteUri();
    @Input
    public abstract Property<String> getCommitId();
    @OutputDirectory
    public abstract DirectoryProperty getDestinationDir();

    @TaskAction
    public void gitClone() throws IOException {
        File destinationDir = getDestinationDir().get()
            .getAsFile()
            .getAbsoluteFile(); 
        String remoteUri = getRemoteUri().get();
        // ...
    }
}

tasks.register("cloneGradleProfiler", GitClone) {
    destinationDir = layout.buildDirectory.dir("gradle-profiler")                      
    remoteUri = "https://github.com/gradle/gradle-profiler.git"
    commitId = "d6c18a21ca6c45fd8a9db321de4478948bdf801b"
}

自定义 up-to-date 检查

Gradle 会自动处理对输出文件和目录的最新检查，但如果任务输出不标准，如对 Web 服务或数据库表的更新。Gradle 在检查时就无法判断任务是否是最新的了。此时我们可以使用 TaskOutputs 上的 upToDateWhen() 方法，增加自定义的检查逻辑。该方法需要一个闭包参数，用于确定任务是否是最新的。例如，我们可以从数据库中读取数据库模式的版本号。或者您可以检查数据库表中的特定记录是否存在或已更改。

请注意，使用自定义最新检查(up-to-date check)的原则是自定义最新检查应可以节省我们的时间。我们不应添加比标准方式执行任务，花费更多资源或更多时间的检查代码。事实上，如果一个任务最终要频繁运行，因为它很少是最新(up-to-date)的，那么它可能根本不值得最新检查。

一个常见的错误混淆使用 upToDateWhen() 而不是使用 Task.onlyIf()。如果我们想用与任务输入和输出无关的某些条件跳过任务，那么我们应该使用 onlyIf()。例如，在设置或未设置特定属性时跳过任务。

规范补充

对于最新(up-to-date)检查和构建缓存，Gradle 需要确定两个任务输入属性是否具有相同的值(value)。为此，Gradle 首先对两个输入进行规范化处理，然后比较结果。例如，对于类路径(compile classpath)，Gradle 从类路径中的类中提取 ABI 签名，然后比较上次运行结果和当前运行结果的签名，如 The Java Plugin (gradle.org) 中所述。

排除整个文件

规范化适用于类路径上的所有 zip 文件（例如 jars、wars、aars、apks 等）。这允许 Gradle 识别两个 zip 文件何时在功能上相同，即使 zip 文件本身可能由于元数据（例如时间戳或文件顺序）而略有不同。规范化不仅适用于在类路径上的直接 zip 文件，还适用于 嵌套在目录内或者 zip 文件内的 zip 文件。

我们可以自定义 Gradle 内置的运行时类路径规范化策略。所有带有 @Classpath 注释的输入都被认为是运行时类路径。

假设我们想将文件 build-info.properties 添加到所有生成的 jar 中，该 jar 包含相关构建信息(如构建开始时的时间戳或用于标识发布工件的 CI 作业的某个 ID)。该 jar 是测试任务(test task)的运行时类路径的一部分。但是该 jar 在每次构建调用时都会发生变化(build-info.properties 文件会变化)，因此 test 任务永远不会是最新的，test 任务永远不会从构建缓存中提取。这种情况下，为了让增量构建生效，我们可以使用 Project.normalization(org.gradle.api.Action) 告诉 Gradle 在项目(project)级别的运行时类路径上忽略此文件的变化。

normalization {
    runtimeClasspath {
        ignore 'build-info.properties'
    }
}

如果将此类文件添加到 jar 文件中是我们为构建中的所有项目执行的操作，并且我们希望为所有消费者都过滤此文件，则我们应考虑在 Sharing Build Logic between Subprojects (gradle.org) 中配置此类规范以在子项目之间共享它(就像 CopySpec 一样的共享逻辑)。

此配置的效果是在进行最新检查和构建缓存计算 key 时，build-info.properties 的更改将被忽略。请注意，这不会改变 test 任务的运行时行为——即任何 test 仍然能够加载 build-info.properties 并且运行时类路径仍然与之前相同。

排除部分属性

默认情况下，属性文件(即以 .properties 扩展名结尾的文件)将被规范化以忽略注释、空格和属性顺序的差异。 但是有时某些属性会对运行时产生影响，而另一些则不会。此时排除整个文件会影响运行时的属性选项。而我们又想将不影响运行的属性从最新检查和构建缓存键计算中排除。

此时可以使用 properties 将忽略属性的规则应用于一组特定的文件。如果文件与规则匹配且无法作为属性文件加载，则它将视为普通文件，参与到 up-to-date 检查或者构建缓存计算。换句话说，如果文件不能作为属性文件加载，我们对空格、属性顺序或注释的任何更改都可能导致任务过期或导致缓存缺失。

normalization {
    runtimeClasspath {
        properties('**/build-info.properties') {
            ignoreProperty 'timestamp'
        }
    }
}

// 例子 2
normalization {
    runtimeClasspath {
        // 针对所有 properties files
        properties {
            ignoreProperty 'timestamp'
        }
    }
}

Java META-INF 设置

对于 jar 包中 META-INF 目录中的文件，由于它们存在运行时影响，并不总是可以忽略整个文件。

META-INF 中的清单文件可以被规范化，以忽略注释、空格和顺序差异。清单中的属性名称也会以不区分大小写的方式进行比较。

normalization {
    runtimeClasspath {
        // 忽略 attributes
        metaInf {
            ignoreAttribute("Implementation-Version")
        }
    }
}

normalization {
    runtimeClasspath {
        // 忽略 property keys
        metaInf {
            ignoreProperty("app.version")
        }
    }
}
// 忽略 META-INF/MANIFEST.MF
normalization {
    runtimeClasspath {
        metaInf {
            ignoreManifest()
        }
    }
}
// 忽略 META-INF 中的所有文件和目录
normalization {
    runtimeClasspath {
        metaInf {
            ignoreCompletely()
        }
    }
}

task 的运行

在讲解了增量构建的相关知识之后，我们可以来讲讲 task 运行的一些知识点了。

构建缓存

Gradle 的构建缓存与 task 的增量构建功能密切相关，构建缓存会使用与最新检查(up-to-date check)类似的逻辑，以节省构建时间。

默认情况下，构建缓存并未启用。我们可以通过多种方式启用构建缓存

• 在命令行上使用 –build-cache 语句启用。当对当前一次构建生效

• 将 org.gradle.caching=true 配置项放入 gradle.properties 文件。Gradle 将尝试为所有构建重用之前构建的输出，除非使用 –no-build-cache 语句明确禁用。

如果任务的输出缓存可用，则任务的输入还用于计算构建缓存的键值，该构建缓存用于加载任务输出。具体讲解可见： Build Cache (gradle.org)

并行运行

默认情况下，task 之间不会并行执行，除非一个 task 正在等待另一个异步动作，并且另一个不依赖于它的 task 已准备好去执行。

启动构建时，可以通过设置 –parallel flag 启用 task 的并行执行。在并行模式下，不同 project(即在多项目 multi-project 构建中) 的 task 能够并行执行

当使用"–parallel"选项时，Gradle 可以使用此信息来决定如何运行任务。比如以下一些场景：

• Gradle 将在选择下一个要运行的任务时检查任务的输出，并避免并发执行写入同一输出目录的任务。

• Gradle 将使用有关任务销毁哪些文件(由 Destroys 注解指定)的信息，并避免运行在另一个任务正在使用或创建文件时删除这些相同文件(反之亦然)的任务

• Gradle 还可以确保创建文件的任务(生产者任务)运行时，使用这些文件的任务(消费者)不运行，避免在生产者和消费者之间运行删除这些文件的任务。

通过提供任务输入和输出信息，Gradle 可以推断任务之间(针对输入输出)的创建/消费/销毁关系，并可以确保任务执行时不会违反这些关系

任务验证

在执行构建时，Gradle 会检查是否使用正确的注解声明了任务类型。验证时 Gradle 会试图定位问题，例如注解被用在不兼容的类型或 setter 上。任何未使用输入/输出相关注解进行注解的 getter 也会被标记。这些检测出的问题会导致构建失败或在执行任务时标注为废弃。

可以做验证警告的任务会在没有任何优化的情况下执行。具体来说，它们有以下特点：

• 不执行 up-to-date 检查

• 不从构建缓存加载或存储在构建缓存中

• 即使在启用了并行执行的情况下，也不与其他任务并行执行

• 不进行增量执行

• 在执行无效性验证任务之前，文件系统状态(也称为虚拟文件系统)在内存中的表示也是无效的

持续构建

定义任务输入和输出的另一个好处是持续构建。由于 Gradle 知道任务依赖于哪些文件，因此如果其任何输入发生更改，它可以自动再次运行任务。通过在运行 Gradle 时激活持续构建(通过 –continuous 或 -t 选项)，您将让 Gradle 进入一种状态，在这种状态下，它会不断检查更改并在遇到此类更改时执行需要执行的任务(任务的输入与这些更改关联)

我们可以在 Command-Line Interface (gradle.org) 中找到有关此功能的更多信息

添加规则

上面我们介绍了，在 TaskContainer 中，我们可以使用 task 的 name 获取 task 实例。但是当 TaskContainer 中不存在对应名称的任务时，我们有没有办法拿到任务实例呢？答案是可以的。有两种方式实现这种效果。

• 一种是当 task 不存在时，我们主动像 TaskContainer 中 add 一个任务实例。

• 另一种方法是可以使用 TaskContainer.addRule(String description, Action ruleAction) 方法为任务添加任务规则。当我们使用了不在列表中的名称获取任务实例时，会调用到规则闭包里的代码。

实际上，addRule 方法没有定义在 TaskContainer 中，而是定义在其父类 NamedDomainObjectCollection 中(可以用 name 定位元素的集合)。所以 addRule 实际上不是针对 Task 添加规则的方法，而是针对集合中某一元素添加规则的方法。

addRule 的第二个入参 Action 可以等价替换为 Groovy 的闭包。闭包中的变量代表当前元素的名称(name)，我们可以使用该名称定位元素。

tasks.addRule("Pattern: ping<ID>") { String taskName ->
    if (taskName.startsWith("ping")) {
        // 使用 Project.task 方法创建任务
        task(taskName) {
            doLast {
                println "Pinging: " + (taskName - 'ping')
            }
        }
    }
}

tasks.register('groupPing') {
    dependsOn 'pingServer1', 'pingServer2'
}

Gradle Task 的内容就先讲这么多。下面让我们看看 Gradle 的产物。

Gradle 产物

在讲解 Gradle 产物的相关知识前，我们需要先明确 Gradle 中的几个概念。

在 Gradle 和其他管理工具中，有 component 和 artifact 的概念。前者可以翻译为组件，实际上就是指编译后的产物；后者可以翻译为工件，实际上就是指编译过程中或临时的、或最终的一个文件。另外还有 dependency 的概念，dependency 可以翻译为依赖，实际上就是指产物里用到的，非本项目的能力，能力由代码定义。

Gradle 和其他管理工具的一个明显差别是 Gradle 还有一个 Variant 的概念，Variant 可以翻译为变体，是 component 的不同使用方式，如 doc 文档或者 jar。如果把 Component 视为抽象类，那么 Variant 就是其具体实现。

组件模型

Maven 组件模型

Gradle 组件模型

在 Gradle 中，artifact 被附加到一个变体，并且每个变体可以有一组不同的依赖关系(dependencies)。当有多个变体时，Gradle 如何知道选择哪个变体呢？实际上，Gradle 使用属性( Variant Attributes )来匹配变体。

Gradle 中有区分两种组件：本地组件和外部组件。前者是如 Project 一样使用项目源代码构建的，后者是发布到远程仓库的。对于本地组件，变体与配置(Configuration)映射；对于外部组件，变体根据已发布的 Gradle Module Metadata 定义或从 Ivy/Maven Metadata 解析得到( Understanding variant selection (gradle.org) )。

注意本文到此处，我们已提及了两种"属性"：Provider/Property 和 Attribute，虽然中文都翻译为属性，但是他们有着不同的使用场景。

组件定义变体的数量没有限制。虽然通常一个组件至少有一个变体。虽然组件的功能通常被变体代替，但是组件也能对外公开文档或源代码等内容。对于相同用途的不同使用者(消费者)，组件也可以定义不同的变体。例如在编译时，针对 Linux、Windows 和 macOS 系统，组件能有不同的 headers。

变体

由于历史原因，在部分文档、DSL 或 API 中，变体(Variants)和配置(configurations)可以互换使用。所有组件都提供变体，并且这些变体由一个配置支持。但是并非所有配置都是变体，因为配置还可能被用于声明或解析依赖项(dependencies)。

简单的讲，就是 variant 都会对应一个 configuration。但是 configuration 可能并不一定对应 variant，因为 configuration 可能对应 dependencies。

变体属性

属性(attribute)是类型安全的键值对(key-value)，在变体或者配置中定义产生(生产者)，在配置解析时使用(配置是消费者)。

可解析的配置(消费者)可以定义任意数量的属性。每个属性都有助于缩小可选择变体的范围。属性值可以不精准匹配。

变体(生产者)也可以定义任意数量的属性，这些属性应该描述如何 Gradle 使用变体。例如，Gradle 使用 org.gradle.usage 属性来描述如何使用组件(编译、运行时执行等场景)。变体具有的属性通常比选中它时所需的属性更多。

属性包含 Gradle 官方文档中介绍了几种 Gradle 定义的标准属性和开发者自定以的属性：

自定义属性

属性是类型确定的 key，在 build script 或者 plugin 中，我们可以创建属性。下面是实现步骤：

1. 使用 Attribute 的相关方法创建一个属性。属性的类型支持绝大多数 Java 主要类，例如 String 和 Integer，或者任何继承实现了 org.gradle.api.Named 的类。

2. 必须在 dependencies handler 的 attribute schema 中声明属性

3. configurations 为 attribute 设值。对于扩展了 Named 的属性，其值必须通过 object factory 创建：

// `String` 类型的 attribute
def myAttribute = Attribute.of("my.attribute.name", String)
// `Usage` 类型的 attribute
def myUsage = Attribute.of("my.usage.attribute", Usage)

dependencies.attributesSchema {
    // 注册 attribute 到 attributes schema
    attribute(myAttribute)
    attribute(myUsage)
}

configurations {
    // 找到名为 myConfiguration 的 Configuration
    myConfiguration {
        attributes {
            // attributes 中添加 myAttribute 属性
            attribute(myAttribute, 'my-value')
            // object factory 创建 Named Attribute 的值
            attribute(myUsage, project.objects.named(Usage, 'my-value'))
        }
    }
}

属性兼容性规则

在某些情况下，生产者可能没有完全满足消费者的要求，但此时可能会有一个可以使用的变体。例如，如果消费者需要一个 library 的 API 变体而生产者没有完全匹配的变体，则可以认为 runtime 变体是兼容的。这是一个需要发布到外部仓库的 library 经常遇到的典型场景。在这种情况下，我们知道即使我们没有完全匹配(API)，我们仍然可以针对 runtime 变体进行编译(它包含的内容比我们需要的要多，使用起来是 ok 的)。

• Gradle 可以为每个属性定义了属性兼容性规则(attribute compatibility rules)。兼容性规则的作用是根据消费者的要求解释哪些属性值是兼容的。

• 属性兼容性规则必须通过属性匹配策略(AttributeMatchingStrategy)注册，我们可以从属性模式(AttributesSchema)中获取该策略

属性消歧规则

由于一个属性可以设置多个值，并且多个值之间可以兼容(如目标需要 Java 11，而变体提供了 Java 8 和 Java 7)。所以 Gradle 需要在所有兼容的候选值中选择"最佳"候选值。这个逻辑被称为“消歧”

• 消歧功能是通过实现属性消歧规则(AttributeDisambiguationRule)来完成的。

• 属性消歧规则必须通过属性匹配策略(AttributeMatchingStrategy)注册，我们可以从属性模式(AttributesSchema)中获取该策略。

匹配变体属性

变体名称主要用于调试目的和获取错误消息，不参与变体匹配——只有变体的属性参与匹配。

变体的匹配过程可以将 Gradle 视作一个选择器。消费者定义变体应具备哪些属性，以及属性具备哪些值；生产者(即变体)也定义自己哪些属性和值。两者将信息交给 Gradle，由 Gradle 的依赖管理引擎(Gradle’s dependency management engine)选择最为匹配的变体。

Gradle 通过将消费者请求的属性与生产者定义的属性进行匹配，来选择变体(variant aware selection)。注意有两个例外绕过算法定义的规则：

• 当生产者没有变体(Variant)时，将选择默认工件。

• 当消费者通过名称明确选择配置(Configuration)时，将选择与配置对应的工件。

例子

在实际的构建中，消费者和生产者通常具有不止一种属性。例如 Gradle 中的一个 Java Library 项目涉及到了几个不同的属性。

• org.gradle.usage：描述如何使用变体

• org.gradle.dependency.bundling：描述变体如何处理依赖项(shadow jar(有修改包名的 jar) vs fat jar(包含所有依赖的 jar) vs regular jar(一般的 jar))

• org.gradle.libraryelements，描述变体如何打包(classes 或 jar)

• org.gradle.jvm.version 描述了变体最小的目标 Java 版本

• org.gradle.jvm.environment 描述了变体的目标 JVM 类型

假设一个消费者想要使用 Java 8 的库运行测试逻辑，生产者支持两个不同的 Java 版本(Java 8 和 Java 11)的场景。下面是对应操作。

1. 消费者定义它需要哪个版本的 Java：消费者想要解析一个具备下面两个条件的变体：

   • 具有 org.gradle.usage=JAVA_RUNTIME，表示变体可以在运行时使用

   • 具备 org.gradle.jvm.version=8，表示最低运行版本是 Java 8

2. 生产者需要公开组件的不同变体：组件同时存在 API(编译)和运行时变体。组件的 Java 8 和 Java 11 版本中都存在这些变体。

3. 最后，Gradle 通过查看所有属性来选择最合适的变体：

   • 消费者想要一个具有与 org.gradle.usage=JAVA_RUNTIME 和 org.gradle.jvm.version=8 兼容属性的变体

   • 生产者与消费者的属性匹配结果。runtime11Elements 和 apiJava11Elements 不能在 Java 8 上运行，而 apiJava8Elements 不具备 org.gradle.usage=JAVA_RUNTIME 属性

   	org.gradle.usage=JAVA_RUNTIME	org.gradle.jvm.version=8	结果
   apiJava8Elements	org.gradle.usage=JAVA_API ×	org.gradle.jvm.version=8 ✔	×
   runtime8Elements	org.gradle.usage=JAVA_RUNTIME ✔	org.gradle.jvm.version=8 ✔	✔
   apiJava11Elements	org.gradle.usage=JAVA_API ×	org.gradle.jvm.version=11 ×	×
   runtime11Elements	org.gradle.usage=JAVA_RUNTIME ✔	org.gradle.jvm.version=11 ×	×

4. 最终 Gradle 选择的是 runtime8Elements 变体，向消费者提供来自 runtime8Elements 变体的工件和依赖项

变体的兼容性

• 如果消费者将 org.gradle.jvm.version 设置为了 7，则 Gradle 的依赖解析操作将会失败，并显示一条用于说明没有合适的变体的错误消息。Gradle 认为消费者需要兼容 Java 7 的 library，而生产者可用的最低 Java 版本是 8。

• 如果消费者将 org.gradle.jvm.version 设置为了 15，则 Gradle 认为 Java 8 或 Java 11 变体都可以工作，最终 Gradle 将选择 Java 版本最高的(11)兼容的变体。

处理匹配错误

当选择最合适的组件变体时，解析可能会失败，产生以下错误：

• 歧义错误：生产者有不止一个变体匹配消费者的属性

• 不兼容错误：生产者没有变体匹配消费者的属性

处理歧义错误

歧义的变体选择的报错信息如下所示，project :ui 是消费者，project :lib 是生产者。

• 下面的报错信息中，所有兼容的候选变体都与其属性一起显示

  • 首先显示不匹配的属性，因为它们可能是选择正确变体时缺失的部分

  • 兼容属性排在第二位，因为它们表明消费者想要什么以及变体(生产者)如何匹配消费者的请求

  • 此处不会列举有任何不兼容的属性，因为这些变体不会被视为候选者

• 错误修复的关键不在于属性匹配(attribute matching)，而在于能力匹配(capability matching)，这显示在变体名称旁边。因为这两个变体都有效地提供了相同的属性和功能，所以它们无法消除歧义。因此，在这种情况下，修复错误的最好方式是在生产者端(project :lib)提供不同的能力，并在消费者端(project :ui)指定要选择的能力。

> Could not resolve all files for configuration ':compileClasspath'.
   > Could not resolve project :lib.
     Required by:
         project :ui
      > Cannot choose between the following variants of project :lib:
          - feature1ApiElements
          - feature2ApiElements
        All of them match the consumer attributes:
          - Variant 'feature1ApiElements' capability org.test:test-capability:1.0:
              - Unmatched attribute:
                  - Found org.gradle.category 'library' but wasn't required.
              - Compatible attributes:
                  - Provides org.gradle.dependency.bundling 'external'
                  - Provides org.gradle.jvm.version '11'
                  - Required org.gradle.libraryelements 'classes' and found value 'jar'.
                  - Provides org.gradle.usage 'java-api'
          - Variant 'feature2ApiElements' capability org.test:test-capability:1.0:
              - Unmatched attribute:
                  - Found org.gradle.category 'library' but wasn't required.
              - Compatible attributes:
                  - Provides org.gradle.dependency.bundling 'external'
                  - Provides org.gradle.jvm.version '11'
                  - Required org.gradle.libraryelements 'classes' and found value 'jar'.
                  - Provides org.gradle.usage 'java-api'

处理无匹配变体错误

没有匹配的变体的错误信息如下所示。

• 所有兼容的候选变体都与其属性一起显示。

  • 首先展示不兼容的属性，因为通常它们是帮助我们理解不选择变体的原因的关键。

  • 然后显示其他属性，包括消费者必需和可兼容的属性，以及生产者声明了而消费者没定义的所有属性。

• 与变体的歧义错误类似，我们的目标应该是了解选择哪个变体。在某些情况下，生产者可能没有任何兼容的变体(例如尝试在Java 8 上运行为 Java 11 构建的库)

> No variants of project :lib match the consumer attributes:
  - Configuration ':lib:compile':
      - Incompatible attribute:
          - Required artifactType 'dll' and found incompatible value 'jar'.
      - Other compatible attribute:
          - Provides usage 'api'
  - Configuration ':lib:compile' variant debug:
      - Incompatible attribute:
          - Required artifactType 'dll' and found incompatible value 'jar'.
      - Other compatible attributes:
          - Found buildType 'debug' but wasn't required.
          - Provides usage 'api'
  - Configuration ':lib:compile' variant release:
      - Incompatible attribute:
          - Required artifactType 'dll' and found incompatible value 'jar'.
      - Other compatible attributes:
          - Found buildType 'release' but wasn't required.
          - Provides usage 'api'

变体属性匹配算法

当组件有许多不同的变体和属性时，找到最合适的变体会变得很复杂。

插件和构建环境可以通过实施兼容性规则、消歧规则或者告诉 Gradle 属性的优先级来影响选择算法。具有更高优先级的属性按顺序兼容匹配。例如在 Java 构建环境中，org.gradle.usage 属性的优先级高于 org.gradle.libraryelements。这意味着如果两个候选对象都具有 org.gradle.usage 和 org.gradle.libraryelements 的兼容值，Gradle 将选择通过 org.gradle.usage 消歧规则检测的候选对象。

Gradle 的依赖解析引擎在寻找最佳结果(可能失败)时会执行以下算法：

1. 每个变体属性值都与消费者需要的属性值进行比较。如果候选变体属性的值与消费者需要的属性值完全匹配，则 Gradle 认为该候选变体是合适的。

2. 如果只有一名候选变体，则该候选变体被选择。

3. 如果多个候选变体都，但其中一个候选变体具有其他候选变体匹配的所有属性，则 Gradle 会选择该候选变体。这是"最长"匹配规则的体现(the “longest” match)。

4. 如果有多个候选变体兼容，并且每个变体都有相同数量的匹配属性，则 Gradle 需要消除候选变体的歧义

   • 对于每个消费者请求的属性，如果候选变体没有匹配消歧规则的值，则 Gradle 将舍弃该候选变体，考虑其他变体

   • 如果属性具有已知的优先级，Gradle 将按照属性优先级进行比较，并在剩下一个候选变体时立即停止，此时可能并未比较完所有属性

   • 如果属性没有已知的优先级，泽 Gradle 必须考虑比较所有属性

5. 如果仍有几个候选变体，Gradle 将开始考虑使用额外的属性，以消除多个候选变体之间的歧义。额外属性是消费者未请求，但至少出现在一个候选人身上的属性。这些额外的属性按优先顺序进行比较。

   • 如果额外属性具有已知的优先级，Gradle 将按照属性优先级进行比较，并在剩下一个候选变体时立即停止

   • 在比较了所有具有优先级的额外属性之后，生于候选变体如果与所有无序的消歧规则兼容，则可以选择它们。

6. 如果还有几个候选变体，Gradle 将再次考虑额外的属性。如果候选变体具有最少数量的额外属性，则可以选择它。

7. 如果最终仍没有候选变体，则匹配解析失败。此时 Gradle 会输出一个步骤 1 中所有兼容候选变体的列表，以帮助开发者调试解决变体匹配失败的错误。

打印变体信息

outgoingVariants 任务打印

类似于 dependencyInsight 打印任务( Viewing and debugging dependencies (gradle.org) )，outgoingVariants 打印任务会显示可供项目消费者(the consumers of the project)选择的变体列表。它显示每个变体的功能、属性和工件(the capabilities, attributes and artifacts)。

默认情况下，outgoingVariants 任务会打印有关所有变体的信息。

• 任务接受可选参数 –variant ，该参数用于选择要显示的单个变体

• 任务接受 –all 标志，该标志用于打印包含一流的、弃用的配置的信息。

下面的日志信息是在 java-library 项目上，outgoingVariants 任务的输出记录：

> Task :outgoingVariants
--------------------------------------------------
Variant apiElements
--------------------------------------------------
Description = API elements for main.

Capabilities
    - new-java-library:lib:unspecified (default capability)
Attributes
    - org.gradle.category            = library
    - org.gradle.dependency.bundling = external
    - org.gradle.jvm.version         = 11
    - org.gradle.libraryelements     = jar
    - org.gradle.usage               = java-api
Artifacts
    - build/libs/lib.jar (artifactType = jar)

Secondary Variants (*)

    --------------------------------------------------
    Secondary Variant classes
    --------------------------------------------------
        Description = Directories containing compiled class files for main.

        Attributes
            - org.gradle.category            = library
            - org.gradle.dependency.bundling = external
            - org.gradle.jvm.version         = 11
            - org.gradle.libraryelements     = classes
            - org.gradle.usage               = java-api
        Artifacts
            - build/classes/java/main (artifactType = java-classes-directory)

--------------------------------------------------
Variant mainSourceElements (i)
--------------------------------------------------
Description = List of source directories contained in the Main SourceSet.

Capabilities
    - new-java-library:lib:unspecified (default capability)
Attributes
    - org.gradle.category            = verification
    - org.gradle.dependency.bundling = external
    - org.gradle.verificationtype    = main-sources
Artifacts
    - src/main/java (artifactType = directory)
    - src/main/resources (artifactType = directory)

--------------------------------------------------
Variant runtimeElements
--------------------------------------------------
Description = Elements of runtime for main.

Capabilities
    - new-java-library:lib:unspecified (default capability)
Attributes
    - org.gradle.category            = library
    - org.gradle.dependency.bundling = external
    - org.gradle.jvm.version         = 11
    - org.gradle.libraryelements     = jar
    - org.gradle.usage               = java-runtime
Artifacts
    - build/libs/lib.jar (artifactType = jar)

Secondary Variants (*)

    --------------------------------------------------
    Secondary Variant classes
    --------------------------------------------------
        Description = Directories containing compiled class files for main.

        Attributes
            - org.gradle.category            = library
            - org.gradle.dependency.bundling = external
            - org.gradle.jvm.version         = 11
            - org.gradle.libraryelements     = classes
            - org.gradle.usage               = java-runtime
        Artifacts
            - build/classes/java/main (artifactType = java-classes-directory)

    --------------------------------------------------
    Secondary Variant resources
    --------------------------------------------------
        Description = Directories containing the project's assembled resource files for use at runtime.

        Attributes
            - org.gradle.category            = library
            - org.gradle.dependency.bundling = external
            - org.gradle.jvm.version         = 11
            - org.gradle.libraryelements     = resources
            - org.gradle.usage               = java-runtime
        Artifacts
            - build/resources/main (artifactType = java-resources-directory)

--------------------------------------------------
Variant testResultsElementsForTest (i)
--------------------------------------------------
Description = Directory containing binary results of running tests for the test Test Suite's test target.

Capabilities
    - new-java-library:lib:unspecified (default capability)
Attributes
    - org.gradle.category              = verification
    - org.gradle.testsuite.name        = test
    - org.gradle.testsuite.target.name = test
    - org.gradle.testsuite.type        = unit-test
    - org.gradle.verificationtype      = test-results
Artifacts
    - build/test-results/test/binary (artifactType = directory)

(i) Configuration uses incubating attributes such as Category.VERIFICATION.
(*) Secondary variants are variants created via the Configuration#getOutgoing(): ConfigurationPublications API which also participate in selection, in addition to the configuration itself.