透過開發建置腳本來學習撰寫 Gradle 的基礎知識。

在本節中，您將會

  • 了解 Project 物件

  • 更新建置腳本

  • 更新外掛

  • 套用外掛

  • 從外掛執行任務

步驟 0. 開始之前

  1. 您已在第 1 部分初始化了您的 Java 應用程式。

  2. 您從第 2 部分了解了 Gradle 建置生命週期。

  3. 您在第 3 部分中新增了一個子專案和一個獨立的建置。

  4. 您在第 4 部分中檢視了一個設定檔。

步驟 1. Project 物件

建置腳本調用 Gradle API 來配置建置。

在配置階段期間，Gradle 會在根目錄和子專案目錄中尋找建置腳本。

當找到建置腳本 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. 建置腳本

讓我們分解外掛的建置腳本

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
}

儲存庫區段讓 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{} 配置區塊來配置他們正在開發的外掛。

任務是在您的建置期間執行的工作單元。它們可以由外掛或內聯方式定義

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 產生的範例中，我們定義了兩個任務

  1. functionalTest：此任務是使用 tasks.register() 註冊的。它為功能測試配置測試任務。

  2. test：此任務是使用 tasks.named() 為現有的 test 任務配置的。它也配置任務以使用 JUnit Jupiter 進行單元測試。

步驟 3. 更新建置腳本

在接下來的章節中，我們將更新 LicensePlugin 為一個自動為原始碼檔案產生授權標頭的外掛。讓我們先使用我們新的 license 外掛的正確名稱來更新建置腳本

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. 檢視外掛任務

當產生 Gradle 外掛專案時，Build init 會建立一個「hello world」外掛。在 LicensePlugin 內部只是一個將問候語列印到控制台的任務，任務名稱為 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 任務。

步驟 5. 檢視外掛任務

當 license 外掛套用至 app 專案時，greeting 任務將會變為可用

若要在根目錄中檢視任務，請執行

$ ./gradlew tasks --all

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

...

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

最後，使用 ./gradlew greeting 或以下指令執行 greeting 任務

$ ./gradlew :app:greeting

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

下一步： 撰寫任務 >>