理解任务 - Gradle 中文

任务表示构建执行的某些独立工作单元，例如编译类、创建 JAR、生成 Javadoc 或将归档文件发布到存储库。

在阅读本章之前，建议您先阅读学习基础知识并完成教程。

列出任务

项目中所有可用的任务都来自 Gradle 插件和构建脚本。

可以通过在终端中运行以下命令列出项目中所有可用的任务

$ ./gradlew tasks

我们以一个非常基本的 Gradle 项目为例。该项目具有以下结构

gradle-project
├── app
│   ├── build.gradle.kts    // empty file - no build logic
│   └── ...                 // some java code
├── settings.gradle.kts     // includes app subproject
├── gradle
│   └── ...
├── gradlew
└── gradlew.bat

gradle-project
├── app
│   ├── build.gradle    // empty file - no build logic
│   └── ...             // some java code
├── settings.gradle     // includes app subproject
├── gradle
│   └── ...
├── gradlew
└── gradlew.bat

settings 文件包含以下内容

settings.gradle.kts

rootProject.name = "gradle-project"
include("app")

settings.gradle

rootProject.name = 'gradle-project'
include('app')

目前，app 子项目的构建文件为空。

要查看 app 子项目中可用的任务，请运行 ./gradlew :app:tasks

$ ./gradlew :app:tasks

> Task :app:tasks

------------------------------------------------------------
Tasks runnable from project ':app'
------------------------------------------------------------

Help tasks
----------
buildEnvironment - Displays all buildscript dependencies declared in project ':app'.
dependencies - Displays all dependencies declared in project ':app'.
dependencyInsight - Displays the insight into a specific dependency in project ':app'.
help - Displays a help message.
javaToolchains - Displays the detected java toolchains.
kotlinDslAccessorsReport - Prints the Kotlin code for accessing the currently available project extensions and conventions.
outgoingVariants - Displays the outgoing variants of project ':app'.
projects - Displays the sub-projects of project ':app'.
properties - Displays the properties of project ':app'.
resolvableConfigurations - Displays the configurations that can be resolved in project ':app'.
tasks - Displays the tasks runnable from project ':app'.

我们观察到目前只有少量帮助任务可用。这是因为 Gradle 的核心仅提供用于分析构建的任务。其他任务（例如构建项目或编译代码的任务）由插件添加。

让我们通过将Gradle 核心base 插件添加到 app 构建脚本来探索这一点

app/build.gradle.kts

plugins {
    id("base")
}

app/build.gradle

plugins {
    id('base')
}

base 插件添加了中心生命周期任务。现在，当我们运行 ./gradlew app:tasks 时，可以看到 assemble 和 build 任务可用

$ ./gradlew :app:tasks

> Task :app:tasks

------------------------------------------------------------
Tasks runnable from project ':app'
------------------------------------------------------------

Build tasks
-----------
assemble - Assembles the outputs of this project.
build - Assembles and tests this project.
clean - Deletes the build directory.

Help tasks
----------
buildEnvironment - Displays all buildscript dependencies declared in project ':app'.
dependencies - Displays all dependencies declared in project ':app'.
dependencyInsight - Displays the insight into a specific dependency in project ':app'.
help - Displays a help message.
javaToolchains - Displays the detected java toolchains.
outgoingVariants - Displays the outgoing variants of project ':app'.
projects - Displays the sub-projects of project ':app'.
properties - Displays the properties of project ':app'.
resolvableConfigurations - Displays the configurations that can be resolved in project ':app'.
tasks - Displays the tasks runnable from project ':app'.

Verification tasks
------------------
check - Runs all checks.

任务结果

当 Gradle 执行任务时，它会通过控制台对任务标记结果。

这些标签基于任务是否有要执行的操作以及 Gradle 是否执行了它们。操作包括但不限于编译代码、压缩文件和发布存档。

（无标签）或 EXECUTED

任务执行了其操作。

任务有操作，并且 Gradle 执行了它们。
任务没有操作和一些依赖项，并且 Gradle 执行了一个或多个依赖项。另请参阅生命周期任务。

UP-TO-DATE

任务的输出没有改变。

任务有输出和输入，但它们没有改变。请参阅增量构建。
任务有操作，但任务告诉 Gradle 它没有改变其输出。
任务没有操作和一些依赖项，但所有依赖项都是 UP-TO-DATE、SKIPPED 或 FROM-CACHE。请参阅生命周期任务。
任务没有操作和依赖项。

FROM-CACHE

可以从以前的执行中找到任务的输出。

任务有从构建缓存恢复的输出。请参阅构建缓存。

SKIPPED

任务没有执行其操作。

任务已从命令行中明确排除。请参阅从执行中排除任务。
任务有一个 onlyIf 谓词返回 false。请参阅使用谓词。

NO-SOURCE

任务不需要执行其操作。

任务有输入和输出，但没有源（即，未找到输入）。

任务组和描述

任务组和描述用于组织和描述任务。

组: 任务组用于对任务进行分类。当运行 ./gradlew tasks 时，任务会列在各自的组下，这样可以更轻松地了解其目的和与其他任务的关系。组使用 group 属性设置。
说明: 说明提供了任务的作用的简要解释。当运行 ./gradlew tasks 时，说明会显示在每个任务旁边，帮助你了解其目的和使用方法。说明使用 description 属性设置。

我们以一个基本的 Java 应用程序为例。该构建包含一个名为 app 的子项目。

我们列出 app 中当前可用的任务

$ ./gradlew :app:tasks

> Task :app:tasks

------------------------------------------------------------
Tasks runnable from project ':app'
------------------------------------------------------------

Application tasks
-----------------
run - Runs this project as a JVM application.

Build tasks
-----------
assemble - Assembles the outputs of this project.

此处，:run 任务是 Application 组的一部分，说明为 将此项目作为 JVM 应用程序运行。在代码中，它看起来像这样

app/build.gradle.kts

tasks.register("run") {
    group = "Application"
    description = "Runs this project as a JVM application."
}

app/build.gradle

tasks.register("run") {
    group = "Application"
    description = "Runs this project as a JVM application."
}

私有任务和隐藏任务

Gradle 不支持将任务标记为私有。

但是，仅当设置了 task.group 或没有其他任务依赖于它时，任务才会在运行 :tasks 时显示。

例如，以下任务在运行 ./gradlew :app:tasks 时不会出现，因为它没有组；它称为隐藏任务

app/build.gradle.kts

tasks.register("helloTask") {
    println("Hello")
}

app/build.gradle

tasks.register("helloTask") {
    println("Hello")
}

虽然 helloTask 没有列出，但它仍然可以由 Gradle 执行

$ ./gradlew :app:tasks

> Task :app:tasks

------------------------------------------------------------
Tasks runnable from project ':app'
------------------------------------------------------------

Application tasks
-----------------
run - Runs this project as a JVM application

Build tasks
-----------
assemble - Assembles the outputs of this project.

我们向同一任务添加一个组

app/build.gradle.kts

tasks.register("helloTask") {
    group = "Other"
    description = "Hello task"
    println("Hello")
}

app/build.gradle

tasks.register("helloTask") {
    group = "Other"
    description = "Hello task"
    println("Hello")
}

现在已添加组，任务可见

$ ./gradlew :app:tasks

> Task :app:tasks

------------------------------------------------------------
Tasks runnable from project ':app'
------------------------------------------------------------

Application tasks
-----------------
run - Runs this project as a JVM application

Build tasks
-----------
assemble - Assembles the outputs of this project.

Other tasks
-----------
helloTask - Hello task

相比之下，./gradlew tasks --all 将显示所有任务；隐藏任务和可见任务都会列出。

分组任务

如果你想自定义在列出时向用户显示哪些任务，你可以对任务进行分组并设置每个组的可见性。

请记住，即使你隐藏任务，它们仍然可用，Gradle 仍然可以运行它们。

我们从一个由 Gradle init 构建的 Java 应用程序（包含多个子项目）的示例开始。项目结构如下

gradle-project
├── app
│   ├── build.gradle.kts
│   └── src                 // some java code
│       └── ...
├── utilities
│   ├── build.gradle.kts
│   └── src                 // some java code
│       └── ...
├── list
│   ├── build.gradle.kts
│   └── src                 // some java code
│       └── ...
├── buildSrc
│   ├── build.gradle.kts
│   ├── settings.gradle.kts
│   └── src                 // common build logic
│       └── ...
├── settings.gradle.kts
├── gradle
├── gradlew
└── gradlew.bat

gradle-project
├── app
│   ├── build.gradle
│   └── src             // some java code
│       └── ...
├── utilities
│   ├── build.gradle
│   └── src             // some java code
│       └── ...
├── list
│   ├── build.gradle
│   └── src             // some java code
│       └── ...
├── buildSrc
│   ├── build.gradle
│   ├── settings.gradle
│   └── src             // common build logic
│       └── ...
├── settings.gradle
├── gradle
├── gradlew
└── gradlew.bat

运行 app:tasks 以查看 app 子项目中可用的任务

$ ./gradlew :app:tasks

> Task :app:tasks

------------------------------------------------------------
Tasks runnable from project ':app'
------------------------------------------------------------

Application tasks
-----------------
run - Runs this project as a JVM application

Build tasks
-----------
assemble - Assembles the outputs of this project.
build - Assembles and tests this project.
buildDependents - Assembles and tests this project and all projects that depend on it.
buildNeeded - Assembles and tests this project and all projects it depends on.
classes - Assembles main classes.
clean - Deletes the build directory.
jar - Assembles a jar archive containing the classes of the 'main' feature.
testClasses - Assembles test classes.

Distribution tasks
------------------
assembleDist - Assembles the main distributions
distTar - Bundles the project as a distribution.
distZip - Bundles the project as a distribution.
installDist - Installs the project as a distribution as-is.

Documentation tasks
-------------------
javadoc - Generates Javadoc API documentation for the 'main' feature.

Help tasks
----------
buildEnvironment - Displays all buildscript dependencies declared in project ':app'.
dependencies - Displays all dependencies declared in project ':app'.
dependencyInsight - Displays the insight into a specific dependency in project ':app'.
help - Displays a help message.
javaToolchains - Displays the detected java toolchains.
kotlinDslAccessorsReport - Prints the Kotlin code for accessing the currently available project extensions and conventions.
outgoingVariants - Displays the outgoing variants of project ':app'.
projects - Displays the sub-projects of project ':app'.
properties - Displays the properties of project ':app'.
resolvableConfigurations - Displays the configurations that can be resolved in project ':app'.
tasks - Displays the tasks runnable from project ':app'.

Verification tasks
------------------
check - Runs all checks.
test - Runs the test suite.

如果我们查看可用的任务列表，即使对于标准 Java 项目，它也是很长的。其中许多任务很少由使用构建的开发人员直接需要。

我们可以配置 :tasks 任务并将显示的任务限制为某个组。

我们创建一个自己的组，以便通过更新 app 构建脚本默认隐藏所有任务

app/build.gradle.kts

val myBuildGroup = "my app build"               // Create a group name

tasks.register<TaskReportTask>("tasksAll") {    // Register the tasksAll task
    group = myBuildGroup
    description = "Show additional tasks."
    setShowDetail(true)
}

tasks.named<TaskReportTask>("tasks") {          // Move all existing tasks to the group
    displayGroup = myBuildGroup
}

app/build.gradle

def myBuildGroup = "my app build"               // Create a group name

tasks.register(TaskReportTask, "tasksAll") {    // Register the tasksAll task
    group = myBuildGroup
    description = "Show additional tasks."
    setShowDetail(true)
}

tasks.named(TaskReportTask, "tasks") {          // Move all existing tasks to the group
    displayGroup = myBuildGroup
}

现在，当我们列出在 app 中可用的任务时，列表会更短

$ ./gradlew :app:tasks

> Task :app:tasks

------------------------------------------------------------
Tasks runnable from project ':app'
------------------------------------------------------------

My app build tasks
------------------
tasksAll - Show additional tasks.

任务类别

Gradle 区分两种类别的任务

生命周期任务
可操作任务

生命周期任务定义您可以调用的目标，例如 :build 您的项目。生命周期任务不为 Gradle 提供操作。它们必须连接到可操作任务。base Gradle 插件仅添加生命周期任务。

可操作任务定义 Gradle 要执行的操作，例如 :compileJava，它编译您项目的 Java 代码。操作包括创建 JAR、压缩文件、发布存档等等。java-library 插件等插件添加可操作任务。

让我们更新前一个示例的构建脚本，它当前是一个空文件，以便我们的 app 子项目是一个 Java 库

app/build.gradle.kts

plugins {
    id("java-library")
}

app/build.gradle

plugins {
    id('java-library')
}

我们再次列出可用任务，以查看有哪些新任务可用

$ ./gradlew :app:tasks

> Task :app:tasks

------------------------------------------------------------
Tasks runnable from project ':app'
------------------------------------------------------------

Build tasks
-----------
assemble - Assembles the outputs of this project.
build - Assembles and tests this project.
buildDependents - Assembles and tests this project and all projects that depend on it.
buildNeeded - Assembles and tests this project and all projects it depends on.
classes - Assembles main classes.
clean - Deletes the build directory.
jar - Assembles a jar archive containing the classes of the 'main' feature.
testClasses - Assembles test classes.

Documentation tasks
-------------------
javadoc - Generates Javadoc API documentation for the 'main' feature.

Help tasks
----------
buildEnvironment - Displays all buildscript dependencies declared in project ':app'.
dependencies - Displays all dependencies declared in project ':app'.
dependencyInsight - Displays the insight into a specific dependency in project ':app'.
help - Displays a help message.
javaToolchains - Displays the detected java toolchains.
outgoingVariants - Displays the outgoing variants of project ':app'.
projects - Displays the sub-projects of project ':app'.
properties - Displays the properties of project ':app'.
resolvableConfigurations - Displays the configurations that can be resolved in project ':app'.
tasks - Displays the tasks runnable from project ':app'.

Verification tasks
------------------
check - Runs all checks.
test - Runs the test suite.

我们看到许多新任务可用，例如 jar 和 testClasses。

此外，java-library 插件已将可操作任务连接到生命周期任务。如果我们调用 :build 任务，我们可以看到已执行了几个任务，包括 :app:compileJava 任务。

$./gradlew :app:build

> Task :app:compileJava
> Task :app:processResources NO-SOURCE
> Task :app:classes
> Task :app:jar
> Task :app:assemble
> Task :app:compileTestJava
> Task :app:processTestResources NO-SOURCE
> Task :app:testClasses
> Task :app:test
> Task :app:check
> Task :app:build

可操作的 :compileJava 任务已连接到生命周期 :build 任务。

增量任务

Gradle 任务的一个关键特性是它们的增量特性。

Gradle 可以重用以前构建的结果。因此，如果我们之前构建过我们的项目并且只做了小的更改，则重新运行 :build 将不需要 Gradle 执行大量工作。

例如，如果我们只修改项目中的测试代码，而生产代码保持不变，则执行构建将仅重新编译测试代码。Gradle 将生产代码的任务标记为 UP-TO-DATE，表示自上次成功构建以来它保持不变

$./gradlew :app:build

lkassovic@MacBook-Pro temp1 % ./gradlew :app:build
> Task :app:compileJava UP-TO-DATE
> Task :app:processResources NO-SOURCE
> Task :app:classes UP-TO-DATE
> Task :app:jar UP-TO-DATE
> Task :app:assemble UP-TO-DATE
> Task :app:compileTestJava
> Task :app:processTestResources NO-SOURCE
> Task :app:testClasses
> Task :app:test
> Task :app:check UP-TO-DATE
> Task :app:build UP-TO-DATE

缓存任务

Gradle 可以使用构建缓存重用过去构建的结果。

要启用此功能，请使用 --build-cache 命令行参数或在 gradle.properties 文件中设置 org.gradle.caching=true 来激活构建缓存。

此优化有可能显著加速您的构建

$./gradlew :app:clean :app:build --build-cache

> Task :app:compileJava FROM-CACHE
> Task :app:processResources NO-SOURCE
> Task :app:classes UP-TO-DATE
> Task :app:jar
> Task :app:assemble
> Task :app:compileTestJava FROM-CACHE
> Task :app:processTestResources NO-SOURCE
> Task :app:testClasses UP-TO-DATE
> Task :app:test FROM-CACHE
> Task :app:check UP-TO-DATE
> Task :app:build

当 Gradle 可以从缓存中获取任务的输出时，它会用 FROM-CACHE 标记该任务。

如果您经常在分支之间切换，构建缓存非常方便。Gradle 支持本地和远程构建缓存。

开发任务

在开发 Gradle 任务时，您有两个选择

使用现有的 Gradle 任务类型，例如 Zip、Copy 或 Delete
创建您自己的 Gradle 任务类型，例如 MyResolveTask 或 CustomTaskUsingToolchains。

任务类型只是 Gradle Task 类的子类。

对于 Gradle 任务，需要考虑三种状态

注册任务 - 在您的构建逻辑中使用任务（由您实现或由 Gradle 提供）。
配置任务 - 定义已注册任务的输入和输出。
实现任务 - 创建自定义任务类（即自定义类类型）。

注册通常使用 register() 方法完成。
配置任务通常使用 named() 方法完成。
实现任务通常通过扩展 Gradle 的 DefaultTask 类完成

tasks.register<Copy>("myCopy")                              (1)

tasks.named<Copy>("myCopy") {                               (2)
    from("resources")
    into("target")
    include("**/*.txt", "**/*.xml", "**/*.properties")
}

abstract class MyCopyTask : DefaultTask() {                 (3)
    @TaskAction
    fun copyFiles() {
        val sourceDir = File("sourceDir")
        val destinationDir = File("destinationDir")
        sourceDir.listFiles()?.forEach { file ->
            if (file.isFile && file.extension == "txt") {
                file.copyTo(File(destinationDir, file.name))
            }
        }
    }
}

1	注册 `myCopy` 任务类型为 `Copy`，以让 Gradle 知道我们打算在构建逻辑中使用它。
2	根据其 API，使用所需的输入和输出配置已注册的 `myCopy` 任务。
3	实现一个名为 `MyCopyTask` 的自定义任务类型，它扩展了 `DefaultTask` 并定义了 `copyFiles` 任务操作。

tasks.register(Copy, "myCopy")                              (1)

tasks.named(Copy, "myCopy") {                               (2)
    from "resources"
    into "target"
    include "**/*.txt", "**/*.xml", "**/*.properties"
}

abstract class MyCopyTask extends DefaultTask {             (3)
    @TaskAction
    void copyFiles() {
        fileTree('sourceDir').matching {
            include '**/*.txt'
        }.forEach { file ->
            file.copyTo(file.path.replace('sourceDir', 'destinationDir'))
        }
    }
}

1	注册 `myCopy` 任务类型为 `Copy`，以让 Gradle 知道我们打算在构建逻辑中使用它。
2	根据其 API，使用所需的输入和输出配置已注册的 `myCopy` 任务。
3	实现一个名为 `MyCopyTask` 的自定义任务类型，它扩展了 `DefaultTask` 并定义了 `copyFiles` 任务操作。

1. 注册任务

您可以通过在构建脚本或插件中注册任务来定义 Gradle 要执行的操作。

任务使用字符串定义任务名称

build.gradle.kts

tasks.register("hello") {
    doLast {
        println("hello")
    }
}

build.gradle

tasks.register('hello') {
    doLast {
        println 'hello'
    }
}

在上面的示例中，使用 TasksCollection 中的 register() 方法将任务添加到 TaskContainer 中。

2. 配置任务

必须配置 Gradle 任务才能成功完成其操作。如果任务需要压缩文件，则必须使用文件名和位置对其进行配置。您可以参考 Gradle Zip 任务的 API 以了解如何对其进行适当配置。

我们以 Gradle 提供的 Copy 任务为例。我们首先在构建脚本中注册一个名为 myCopy 的 Copy 类型任务

build.gradle.kts

tasks.register<Copy>("myCopy")

build.gradle

tasks.register('myCopy', Copy)

这会注册一个没有默认行为的复制任务。由于该任务的类型为 Copy（Gradle 支持的任务类型），因此可以使用其 API 对其进行配置。

以下示例显示了实现相同配置的几种方法

1. 使用 `named()` 方法：

使用 named() 配置在其他位置注册的现有任务

build.gradle.kts

tasks.named<Copy>("myCopy") {
    from("resources")
    into("target")
    include("**/*.txt", "**/*.xml", "**/*.properties")
}

build.gradle

tasks.named('myCopy') {
    from 'resources'
    into 'target'
    include('**/*.txt', '**/*.xml', '**/*.properties')
}

2. 使用配置块：

使用块在注册任务后立即配置任务

build.gradle.kts

tasks.register<Copy>("copy") {
   from("resources")
   into("target")
   include("**/*.txt", "**/*.xml", "**/*.properties")
}

build.gradle

tasks.register('copy', Copy) {
   from 'resources'
   into 'target'
   include('**/*.txt', '**/*.xml', '**/*.properties')
}

3. 名称方法作为调用：

只在 Groovy 中支持的一种流行选项是速记符号

copy {
    from("resources")
    into("target")
    include("**/*.txt", "**/*.xml", "**/*.properties")
}

此选项会破坏任务配置规避，不建议使用！

无论选择哪种方法，都使用要复制的文件的名称和文件的位置配置任务。

3. 实现任务

Gradle 提供了许多任务类型，包括 Delete、Javadoc、Copy、Exec、Tar 和 Pmd。如果 Gradle 未提供满足您的构建逻辑需求的任务类型，您可以实现自定义任务类型。

要创建自定义任务类，请扩展 DefaultTask 并使扩展类变为抽象

app/build.gradle.kts

abstract class MyCopyTask extends DefaultTask {

}

app/build.gradle

abstract class MyCopyTask : DefaultTask() {

}

你可以在实现任务中了解有关开发自定义任务类型的更多信息。

此页面是否有帮助？