通过开发 Build 脚本学习编写 Gradle 的基础知识。

在本节中，您将

  • 理解 Project 对象

  • 更新 Build 脚本

  • 更新插件

  • 应用插件

  • 从插件运行 Task

步骤 0. 开始之前

  1. 您在第 1 部分中初始化了您的 Java 应用程序。

  2. 您从第 2 部分了解了 Gradle 构建生命周期。

  3. 您在第 3 部分中添加了一个子项目和一个单独的 Build。

  4. 您在第 4 部分中查看了一个 Settings 文件。

步骤 1. Project 对象

Build 脚本调用 Gradle API 来配置构建。

在配置阶段，Gradle 会在根目录和子项目目录中查找 build 脚本。

当找到 build 脚本 build.gradle(.kts) 时，Gradle 会配置一个 Project 对象。

Project 对象的目的是创建 Task 对象的集合、应用插件和检索依赖项。

您可以直接在脚本中使用 Project 接口上的任何方法和属性。

例如

defaultTasks("some-task")      // Delegates to Project.defaultTasks()
reportsDir = file("reports")   // Delegates to Project.file() and the Java Plugin
defaultTasks 'some-task'      // Delegates to Project.defaultTasks()
reportsDir = file('reports')  // Delegates to Project.file() and the Java Plugin

步骤 2. Build 脚本

让我们分解插件的 build 脚本

gradle/license-plugin/plugin/build.gradle.kts
plugins {                                                             (1)
    `java-gradle-plugin`                                              (2)
    id("org.jetbrains.kotlin.jvm") version "1.9.0"                    (3)
}

repositories {                                                        (4)
    mavenCentral()                                                    (5)
}

dependencies {                                                        (6)
    testImplementation("org.jetbrains.kotlin:kotlin-test-junit5")     (7)
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

gradlePlugin {                                                        (8)
    val greeting by plugins.creating {                                (9)
        id = "license.greeting"
        implementationClass = "license.LicensePlugin"
    }
}

// Additional lines //
1 在 Kotlin DSL 中使用 KotlinSettingsScript 中的 plugins{} 代码块
2 应用 Java Gradle 插件开发插件，以添加对开发 Gradle 插件的支持
3 应用 Kotlin JVM 插件，以添加对 Kotlin 的支持
4 使用 Project.repositories() 为此项目配置仓库
5 使用 Maven Central 来解析依赖项
6 使用 Project.dependencies() 为此项目配置依赖项
7 使用 Kotlin JUnit 5 集成
8 在 Kotlin DSL 中使用 GradlePluginDevelopmentExtension 中的 gradlePlugin{} 代码块
9 定义插件 id 和 implementationClass
gradle/license-plugin/plugin/build.gradle
plugins {                                                           (1)
    id 'java-gradle-plugin'                                         (2)
    id 'groovy'                                                     (3)
}

repositories {                                                      (4)
    mavenCentral()                                                  (5)
}

dependencies {                                                      (6)
    testImplementation libs.spock.core
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

gradlePlugin {                                                      (7)
    plugins {
        greeting {
            id = 'license.greeting'                                 (8)
            implementationClass = 'license.LicensePlugin'
        }
    }
}

// Additional lines //
1 在 Groovy DSL 中使用 PluginDependenciesSpec API 中的 plugins{} 代码块
2 应用 Java Gradle 插件开发插件，以添加对开发 Gradle 插件的支持
3 应用 Groovy 插件以添加对 Groovy 的支持
4 使用 Project.repositories() 为此项目配置仓库
5 使用 Maven Central 来解析依赖项
6 使用 Project.dependencies() 为此项目配置依赖项
7 在 Groovy DSL 中使用 PluginAware API 中的 gradlePlugin{} 代码块
8 定义插件 id 和 implementationClass

插件（可以增强您的构建能力）像这样包含：

plugins {
    id("java")                          // core plugin, no version required
    id("org.some.plugin") version "2.8" // community plugin, version required
}
plugins {
    id 'java'                          // core plugin, no version required
    id 'org.some.plugin' version '2.8' // community plugin, version required
}

repositories 部分让 Gradle 知道从哪里拉取依赖项

repositories {
    mavenCentral()  // get dependencies from the Maven central repository
}
repositories {
    mavenCentral()  // get dependencies from the Maven central repository
}

依赖项是构建应用程序或库的要求

dependencies {
    // group: 'org.apache.commons', name: 'commons-lang3', version: '3.13.0'
    implementation("org.apache.commons:commons-lang3:3.13.0")
}
dependencies {
    // group: 'org.apache.commons', name: 'commons-lang3', version: '3.13.0'
    implementation 'org.apache.commons:commons-lang3:3.13.0'
}

在此示例中，implementation() 意味着必须将 commons-lang3 库添加到 Java 类路径中。

为 Gradle 项目声明的每个依赖项都必须应用于一个作用域。也就是说，依赖项在编译时、运行时或两者都需要。这称为配置，当依赖项仅在运行时类路径中需要时，将使用 implementation 配置。

配置代码块（不要与上面的依赖配置混淆）通常用于配置已应用的插件

gradlePlugin {  // Define a custom plugin
    val greeting by plugins.creating {  // Define `greeting` plugin using the `plugins.creating` method
        id = "license.greeting" // Create plugin with the specified ID
        implementationClass = "license.LicensePlugin"   // and specified implementation class
    }
}
gradlePlugin {  // Define a custom plugin
    plugins {
        greeting {  // Define a plugin named greeting
            id = 'license.greeting' // using the id
            implementationClass = 'license.LicensePlugin' // and implementationClass
        }
    }
}

当应用 java-gradle-plugin 时，用户必须使用 gradlePlugin{} 配置代码块配置他们正在开发的插件。

Task 是在构建期间执行的工作单元。它们可以由插件定义，也可以内联定义

val functionalTest by tasks.registering(Test::class) {
    testClassesDirs = functionalTestSourceSet.output.classesDirs
    classpath = functionalTestSourceSet.runtimeClasspath
    useJUnitPlatform()
}

tasks.named<Test>("test") {
    // Use JUnit Jupiter for unit tests.
    useJUnitPlatform()
}
tasks.register('functionalTest', Test) {
    testClassesDirs = sourceSets.functionalTest.output.classesDirs
    classpath = sourceSets.functionalTest.runtimeClasspath
    useJUnitPlatform()
}

tasks.named('test') {
    // Use JUnit Jupiter for unit tests.
    useJUnitPlatform()
}

在 Gradle init 生成的示例中，我们定义了两个 Task

  1. functionalTest：此 Task 使用 tasks.register() 注册。它为功能测试配置 test Task。

  2. test：此 Task 使用 tasks.named() 为现有的 test Task 进行配置。它还配置 Task 以使用 JUnit Jupiter 进行单元测试。

步骤 3. 更新 Build 脚本

在接下来的章节中，我们将把 LicensePlugin 更新为一个自动为源代码文件生成许可证头的插件。让我们首先使用新的 license 插件的正确名称更新 build 脚本

gradle/license-plugin/plugin/build.gradle.kts
gradlePlugin {
    val license by plugins.creating {   // Update name to license
        id = "com.tutorial.license"     // Update id to com.gradle.license
        implementationClass = "license.LicensePlugin"
    }
}
gradle/license-plugin/plugin/build.gradle
gradlePlugin {
    // Define the plugin
    plugins {
        license {                       // Update name to license
            id = 'com.tutorial.license' // Update id to com.gradle.license
            implementationClass = 'license.LicensePlugin'
        }
    }
}

步骤 3. 应用插件

让我们将 license 插件应用于 app 子项目

app/build.gradle.kts
plugins {
    application
    id("com.tutorial.license")  // Apply the license plugin
}
app/build.gradle
plugins {
    id 'application'
    id('com.tutorial.license')  // Apply the license plugin
}

步骤 4. 查看插件 Task

当生成 Gradle 插件项目时，Build init 会创建一个 “hello world” 插件。LicensePlugin 内部只是一个向控制台打印问候语的 Task，Task 名称为 greeting

gradle/license-plugin/plugin/src/main/kotlin/license/LicensePlugin.kt
class LicensePlugin: Plugin<Project> {
    override fun apply(project: Project) {                          // Apply plugin
        project.tasks.register("greeting") { task ->                // Register a task
            task.doLast {
                println("Hello from plugin 'com.tutorial.greeting'")  // Hello world printout
            }
        }
    }
}
gradle/license-plugin/plugin/src/main/groovy/license/LicensePlugin.groovy
class LicensePlugin implements Plugin<Project> {
    void apply(Project project) {
        // Register a task
        project.tasks.register("greeting") {
            doLast {
                println("Hello from plugin 'com.tutorial.greeting'")
            }
        }
    }
}

正如我们所见，license 插件在应用时，会公开一个带有简单打印语句的 greeting Task。

步骤 5. 查看插件 Tasks

当 license 插件应用于 app 项目时，greeting Task 变为可用

要在根目录中查看 Task，请运行

$ ./gradlew tasks --all

------------------------------------------------------------
Tasks runnable from root project 'authoring-tutorial'
------------------------------------------------------------

...

Other tasks
-----------
app:greeting
app:task1
app:task2
lib:task3

最后，使用 ./gradlew greeting 或以下命令运行 greeting Task

$ ./gradlew :app:greeting

> Task :app:greeting
Hello from plugin 'com.tutorial.greeting'

下一步： 编写 Task >>