第21章 Gradle Plugins 插件

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

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

21.1. Types of plugins 插件類(lèi)型

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

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

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

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)用。文件位置是相對(duì)于項(xiàng)目目錄，而遠(yuǎn)程腳本的位置是一個(gè) HTTP URL 指定。多個(gè)腳本插件（或形式）可以應(yīng)用到一個(gè)給定的建立。

21.2.2. Binary plugins

Example 21.2. Applying a binary plugin

build.gradle

apply plugin: 'java'

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

該方法還可以接受一個(gè)類(lèi)識(shí)別插件：

Example 21.3. Applying a binary plugin by type

build.gradle

apply plugin: JavaPlugin

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

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

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

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

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

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

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

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

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

申請(qǐng)一個(gè)核心插件，可以使用短名稱：

Example 21.4. Applying a core plugin

build.gradle

plugins {
    id 'java'
}

通過(guò)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)一步配置。具體來(lái)說(shuō),不需要配置 buildscript 類(lèi)路徑。Gradle將在插件門(mén)戶解決插件,找到它,使它可用于構(gòu)建。

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

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

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

21.5. What plugins do 插件做啥

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

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

舉例

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

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

21.6. Conventions 約定

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

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

我們可以簡(jiǎn)單地通過(guò)給它一個(gè)新的值來(lái)更改此屬性。

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ù)很可能不是唯一需要知道類(lèi)文件在哪里的任務(wù)。

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

我們可以通過(guò)這個(gè)源碼集修改寫(xiě)入類(lèi)文件的位置。

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 插件，除其他外，還做了下列操作：

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

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

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

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

21.7. More on plugins 更多插件

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