第21章 Gradle Plugins 插件

Gradle 在它的核心中有意地提供了一些小但有用的功能，用于在真實(shí)世界中的自動化。所有有用的功能，例如以能夠編譯 Java 代碼為例，都是通過插件進(jìn)行添加的。插件添加了新任務(wù) （例如?JavaCompile），域?qū)ο?（例如?SourceSet?），約定（例如主要的 Java 源代碼是位于 src/main/java ），以及擴(kuò)展的核心對象和其他插件的對象。

在這一章中，我們將討論如何使用插件以及術(shù)語和插件相關(guān)的概念。

21.1. Types of plugins 插件類型

Gradle 一般有兩種類型的插件 :script 插件和 binary 插件。script 插件是額外的構(gòu)建腳本，用于進(jìn)一步配置構(gòu)建，以及實(shí)現(xiàn)一種聲明性方法操縱構(gòu)建。他們通常用于構(gòu)建雖然他們可以外部化和從遠(yuǎn)程位置訪問。binary插件的類實(shí)現(xiàn)?Plugin?接口,采用的編程方法操縱構(gòu)建。binary 插件通過項(xiàng)目層次結(jié)構(gòu)或外部插件 jar 駐留在構(gòu)建腳本中。

21.2. Applying plugins 應(yīng)用插件

插件是可以被應(yīng)用的，通過?Project.apply()?方法來完成。

21.2.1. Script plugins

Example 21.1. Applying a script plugin

build.gradle

apply from: 'other.gradle'

script 插件可以從本地文件系統(tǒng)或在遠(yuǎn)程位置的腳本應(yīng)用。文件位置是相對于項(xiàng)目目錄，而遠(yuǎn)程腳本的位置是一個 HTTP URL 指定。多個腳本插件（或形式）可以應(yīng)用到一個給定的建立。

21.2.2. Binary plugins

Example 21.2. Applying a binary plugin

build.gradle

apply plugin: 'java'

核心插件注冊一個簡短的名字。在上面的例子中，我們使用短名稱“java”來應(yīng)用?JavaPlugin。插件也有插件ID，以一個完全合格的形式如 com.github.foo.bar，雖然一些遺留的插件還可以利用短期的，不合格的形式。

該方法還可以接受一個類識別插件：

Example 21.3. Applying a binary plugin by type

build.gradle

apply plugin: JavaPlugin

在上述樣本JavaPlugin 符號就是指?JavaPlugin。這類不需要嚴(yán)格引入 org.gradle.api.plugins 包在所有構(gòu)建腳本會自動導(dǎo)入（見Appendix E. Existing IDE Support and how to cope without it 支持的 IDE 以及如何應(yīng)對沒有它）。此外，不需要追加 .class 來確認(rèn)這個類是在 Groovy 還是在 Java。

插件的應(yīng)用是冪等。就是說一個插件，可多次應(yīng)用。如果插件已被應(yīng)用，任何進(jìn)一步的應(yīng)用將沒有任何效果。

21.2.2.1. Locations of binary plugins 關(guān)于 binary 插件的位置

一個插件是任意類實(shí)現(xiàn)?Plugin?接口。Gradle 提供核心插件為其分配部分簡單地應(yīng)用插件來提供所有你需要做的。然而，非核心 binary 插件需要可用于構(gòu)建類路徑才可以應(yīng)用。這可以通過很多途徑實(shí)現(xiàn)，包括：

• 定義插件為內(nèi)聯(lián)類的聲明在一個構(gòu)建腳本。
• 定義插件作為一個源在項(xiàng)目目錄下的文件 buildsrc。
• 包括從外部罐定義為 buildscript 依賴插件（見60.5節(jié)，“外部依賴關(guān)系的構(gòu)建腳本”）。
• 包括插件從插件門戶使用插件的DSL（見21.3節(jié)，“應(yīng)用插件與插件DSL”）。

更多關(guān)于定義你自己的插件，見Chapter 59. Writing Custom Plugins 編寫自定義插件。

21.3. Applying plugins with the plugins DSL 使用DSL應(yīng)用插件

插件DSL目前正在醞釀中。請注意,DSL和其他配置可能會在以后 Gradle版本改變。

新的插件提供了一個更簡潔的 DSL 和方便的方式來聲明插件的依賴關(guān)系。它的工作原理與新的?Gradle 插件門戶?提供方便地訪問核心和社區(qū)插件。插件腳本塊配置實(shí)例?PluginDependenciesSpec。

申請一個核心插件，可以使用短名稱：

Example 21.4. Applying a core plugin

build.gradle

plugins {
    id 'java'
}

通過To apply a community plugin from the portal, the fully qualified plugin id must be used:

Example 21.5. Applying a community plugin

build.gradle

plugins {
    id "com.jfrog.bintray" version "0.4.1"
}

不需要進(jìn)一步配置。具體來說,不需要配置 buildscript 類路徑。Gradle將在插件門戶解決插件,找到它,使它可用于構(gòu)建。

有關(guān)更多信息,請參見?PluginDependenciesSpec?使用插件的 DSL。

21.4. Finding community plugins 尋找社區(qū)插件

Gradle 至今有一個充滿活力的社區(qū)插件開發(fā)人員貢獻(xiàn)為各種功能的插件。Gradle?插件門戶提供了一個接口用于搜索和探索社區(qū)插件。

21.5. What plugins do 插件做啥

把插件應(yīng)用到項(xiàng)目中可以讓插件來擴(kuò)展項(xiàng)目的功能。它可以做的事情如：

• 將任務(wù)添加到項(xiàng)目 （如編譯、 測試）
• 使用有用的默認(rèn)設(shè)置對已添加的任務(wù)進(jìn)行預(yù)配置。
• 向項(xiàng)目中添加依賴配置 （見第 8.3 節(jié)，“依賴配置”）。
• 通過擴(kuò)展對現(xiàn)有類型添加新的屬性和方法。

舉例

Example 21.6. Tasks added by a plugin

build.gradle

apply plugin: 'java'

task show << {
    println relativePath(compileJava.destinationDir)
    println relativePath(processResources.destinationDir)
}

執(zhí)行 gradle -q show

> gradle -q show
build/classes/main
build/resources/main

這個 Java 插件增加了 compileJava 任務(wù) processResources 任務(wù)到項(xiàng)目中，以及給這兩個任務(wù)配置 destinationDir 屬性。

21.6. Conventions 約定

插件可以通過智能的方法對項(xiàng)目進(jìn)行預(yù)配置以支持約定優(yōu)于配置。Gradle 對此提供了機(jī)制和完善的支持，而它是強(qiáng)大-然而-簡潔的構(gòu)建腳本中的一個關(guān)鍵因素。

在上面的示例中我們看到，Java 插件添加了一個任務(wù)，名字為compileJava ，有一個名為 destinationDir 的屬性（即配置編譯的 Java 代碼存放的地方）。Java 插件默認(rèn)此屬性指向項(xiàng)目目錄中的build/classes/main。這是通過一個合理的默認(rèn)的約定優(yōu)于配置的例子。

我們可以簡單地通過給它一個新的值來更改此屬性。

Example 21.7. Changing plugin defaults

build.gradle

apply plugin: 'java'

compileJava.destinationDir = file("$buildDir/output/classes")

task show << {
    println relativePath(compileJava.destinationDir)
}

執(zhí)行 gradle -q show

> gradle -q show
build/output/classes

然而， compileJava 任務(wù)很可能不是唯一需要知道類文件在哪里的任務(wù)。

Java 插件添加了 source sets 的概念 （見SourceSet） 來描述的源文件集的各個方面，其中一個方面是在編譯的時候這些類文件應(yīng)該被寫到哪個地方。Java 插件將 compileJava 任務(wù)的 destinationDir 屬性映射到源文件集的這一個方面。

我們可以通過這個源碼集修改寫入類文件的位置。

Example 21.8. Plugin convention object

build.gradle

apply plugin: 'java'

sourceSets.main.output.classesDir = file("$buildDir/output/classes")

task show << {
    println relativePath(compileJava.destinationDir)
}

執(zhí)行 gradle -q show

> gradle -q show
build/output/classes

在上面的示例中，我們應(yīng)用 Java 插件，除其他外，還做了下列操作：

• 添加了一個新的域?qū)ο箢愋停?SourceSet
• 通過屬性的默認(rèn)（即常規(guī)）配置了 main 源碼集
• 配置支持使用這些屬性來執(zhí)行工作的任務(wù)

所有這一切都發(fā)生在?apply plugin: "java"這一步過程中。在上面例子中，我們在約定配置被執(zhí)行之后，修改了類文件所需的位置。在上面的示例中可以注意到，compileJava.destinationDir 的值也被修改了，以反映出配置的修改。

考慮一下另一種消費(fèi)類文件的任務(wù)的情況。如果這個任務(wù)使用sourceSets.main.output.classesDir 的值來配置，那么修改了這個位置的值，無論它是什么時候被修改，將同時更新 compileJava 任務(wù)和這一個消費(fèi)者任務(wù)。

這種配置對象的屬性以在所有時間內(nèi)（甚至當(dāng)它更改的時候）反映另一個對象的任務(wù)的值的能力被稱為“映射約定”。它可以令 Gradle 通過約定優(yōu)于配置及合理的默認(rèn)值來實(shí)現(xiàn)簡潔的配置方式。而且，如果默認(rèn)約定需要進(jìn)行修改時，也不需要進(jìn)行完全的重新配置。如果沒有這一點(diǎn)，在上面的例子中，我們將不得不重新配置需要使用類文件的每個對象。

21.7. More on plugins 更多插件

這一章旨在作為對插件和 Gradle 及他們扮演的角色的導(dǎo)言。關(guān)于插件的內(nèi)部運(yùn)作的詳細(xì)信息，請參閱Chapter 59. Writing Custom Plugins 編寫自定義插件。