第五十七章. 编写自定义任务类

要在一个构建脚本中使用一个任务类，你需要将这个类添加到构建脚本的类路径中。要做到这一点，请使用《第 59.5 节，“构建脚本的外部依赖”》中所述的 buildscript { } 块。以下示例展示了当包含任务类的 JAR 已发布到本地存储库时，你可以如何操作。
To use a task class in a build script, you need to add the class to the build script's classpath. To do this, you use a buildscript { } block, as described in Section 59.5, “External dependencies for the build script”. The following example shows how you might do this when the JAR containing the task class has been published to a local repository:

buildscript {
    repositories {
        maven {
            url uri('../repo')
        }
    }
    dependencies {
        classpath group: 'org.gradle', name: 'customPlugin', version: '1.0-SNAPSHOT'
    }
}

task greeting(type: org.gradle.GreetingTask) {
    greeting = 'howdy!'
}

你可以使用 ProjectBuilder 类来创建 Project 实例以在测试任务类时使用。
You can use the ProjectBuilder class to create Project instances to use when you test your task class.

class GreetingTaskTest {
    @Test
    public void canAddTaskToProject() {
        Project project = ProjectBuilder.builder().build()
        def task = project.task('greeting', type: GreetingTask)
        assertTrue(task instanceof GreetingTask)
    }
}

对于一个要增量处理输入的任务，它必须包含一个增量任务操作。这是一个任务操作方法，它包含了一个 IncrementalTaskInputs 参数，该参数提示 Gradle 这个操作将只处理那些更改的输入。
For a task to process inputs incrementally, that task must contain an incremental task action. This is a task action method that contains a single IncrementalTaskInputs parameter, which indicates to Gradle that the action will process the changed inputs only.

这个增量任务操作可以提供一个 IncrementalTaskInputs.outOfDate() 操作来处理所有过时的输入文件，以及一个对自上次执行以来已经被删除的文件执行的 IncrementalTaskInputs.removed() 操作。
The incremental task action may supply an IncrementalTaskInputs.outOfDate() action for processing any input file that is out-of-date, and a IncrementalTaskInputs.removed() action that executes for any input file that has been removed since the previous execution.

class IncrementalReverseTask extends DefaultTask {
    @InputDirectory
    def File inputDir

    @OutputDirectory
    def File outputDir

    @Input
    def inputProperty

    @TaskAction
    void execute(IncrementalTaskInputs inputs) {
        println inputs.incremental ? "CHANGED inputs considered out of date" : "ALL inputs considered out of date"
        inputs.outOfDate { change ->
            println "out of date: ${change.file.name}"
            def targetFile = new File(outputDir, change.file.name)
            targetFile.text = change.file.text.reverse()
        }

        inputs.removed { change ->
            println "removed: ${change.file.name}"
            def targetFile = new File(outputDir, change.file.name)
            targetFile.delete()
        }
    }
}

对于像这样的简单转换任务，任务操作只需要对任何过时的输入生成输出文件，并删除任何已移除的输入的输出文件。
For a simple transformer task like this, the task action simply needs to generate output files for any out-of-date inputs, and delete output files for any removed inputs.

一个任务可能只包含一个增量任务操作。
A task may only contain a single incremental task action.

当 Gradle 有了前一次任务执行的历史，并且从那一次执行之后任务执行的上下文中只有输入有修改，那么 Gradle 就能够确定这个任务需要重新处理哪些文件。在这种情况下，将对已添加的或已修改的的输入文件执行 IncrementalTaskInputs.outOfDate() 操作，并且对任何已移除的输入文件执行 IncrementalTaskInputs.removal() 操作。
When Gradle has history of a previous task execution, and the only changes to the task execution context since that execution are to input files, then Gradle is able to determine which input files need to be reprocessed by the task. In this case, the IncrementalTaskInputs.outOfDate() action will be executed for any input file that was added or modified, and the IncrementalTaskInputs.removed() action will be executed for any removed input file.

然而，有许多情况下，Gradle 还是无法确定需要重新处理哪些输入文件。包括比如：
However, there are many cases where Gradle is unable to determine which input files need to be reprocessed. Examples include:

在以上所述的任一情况下，Gradle 将把所有输入文件视为 outOfDate，然后会对每个输入文件执行 IncrementalTaskInputs.outOfDate() 操作，并且将不再执行 IncrementalTaskInputs.removremoval() 操作。
In any of these cases, Gradle will consider all of the input files to be outOfDate. The IncrementalTaskInputs.outOfDate() action will be executed for every input file, and the IncrementalTaskInputs.removed() action will not be executed at all.

你可以使用 IncrementalTaskInputs.isIncremental() 来检查 Gradle 是否能够确定输入文件的增量更改。
You can check if Gradle was able to determine the incremental changes to input files with IncrementalTaskInputs.isIncremental().

考虑到上面的增量任务实现，我们可以通过示例探讨各种更改场景。请注意，各种变化的任务（“updateInputs”，“removeInput”等）仅用于演示：它们通常不会在构建脚本中。
Given the incremental task implementation above, we can explore the various change scenarios by example. Note that the various mutation tasks ('updateInputs', 'removeInput', etc) are only present for demonstration purposes: these would not normally be part of your build script.

首先，考虑到 IncrementalReverseTask 第一次针对一组输入执行。在这种情况下，所有输入都将认为是“过时的”：
First, consider the IncrementalReverseTask executed against a set of inputs for the first time. In this case, all inputs will be considered "out of date":

task incrementalReverse(type: IncrementalReverseTask) {
    inputDir = file('inputs')
    outputDir = file("$buildDir/outputs")
    inputProperty = project.properties['taskInputProperty'] ?: "original"
}

incrementalTask/
  build.gradle
  inputs/
    1.txt
    2.txt
    3.txt

> gradle -q incrementalReverse
ALL inputs considered out of date
out of date: 1.txt
out of date: 2.txt
out of date: 3.txt

当然，当再次执行任务时没有任何修改，那么任务本身是最新的，并且不会向这个任务操作报告任何文件：
Naturally when the task is executed again with no changes, then task itself is up to date and no files are reported to the task action:

> gradle -q incrementalReverse

当以某种方式修改了输入文件，或者新增输入文件时，重新执行这个任务会使这些文件被上报到 IncrementalTaskInputs.outOfDate()：
When an input file is modified in some way or a new input file is added, then re-executing the task results in those files being reported to IncrementalTaskInputs.outOfDate():

task updateInputs() << {
    file('inputs/1.txt').text = "Changed content for existing file 1."
    file('inputs/4.txt').text = "Content for new file 4."
}

> gradle -q updateInputs incrementalReverse
CHANGED inputs considered out of date
out of date: 1.txt
out of date: 4.txt

当删除一个现有的输入文件后，重新执行这个任务会使该文件被报告给 IncrementalTaskInputs.removal()：
When an existing input file is removed, then re-executing the task results that file being reported to IncrementalTaskInputs.removed():

task removeInput() << {
    file('inputs/3.txt').delete()
}

> gradle -q removeInput incrementalReverse
CHANGED inputs considered out of date
removed: 3.txt

当删除（或修改）输出文件时，Gradle 无法确定哪些输入文件是已过时的。在这种情况下，所有的 输入文件都会被报告给 IncrementalTaskInputs.outOfDate() 操作，并且不会向 IncrementalTaskInputs.removal() 操作报告任何输入文件：
When an output file is deleted (or modified), then Gradle is unable to determine which input files are out of date. In this case, all input files are reported to the IncrementalTaskInputs.outOfDate() action, and no input files are reported to the IncrementalTaskInputs.removed() action:

task removeOutput() << {
    file("$buildDir/outputs/1.txt").delete()
}

> gradle -q removeOutput incrementalReverse
ALL inputs considered out of date
out of date: 1.txt
out of date: 2.txt
out of date: 3.txt

当修改任务的输入属性时，Gradle 无法确定该属性对任务的输出会有怎样的影响，因此将假定所有输入文件都已过时。所以与更改输出文件的示例类似，所有的输入文件将报告给 IncrementalTaskInputs.outOfDate() 操作，并且不会向 IncrementalTaskInputs.removal() 操作报告任何输入文件：
When a task input property modified, Gradle is not able to determine how this property impacted the task outputs, so all input files are assumed to be out of date. So similar to the changed output file example, all input files are reported to the IncrementalTaskInputs.outOfDate() action, and no input files are reported to the IncrementalTaskInputs.removed() action:

> gradle -q -PtaskInputProperty=changed incrementalReverse
ALL inputs considered out of date
out of date: 1.txt
out of date: 2.txt
out of date: 3.txt