第21章 Gradle Plugins 插件 · Gradle 2 用戶指南

Gradle 在它的核心中有意地提供了一些小但有用的功能，用于在真實世界中的自動化。所有有用的功能，例如以能夠編譯 Java 代碼為例，都是通過插件進行添加的。插件添加了新任務（例如?[JavaCompile](http://gradle.org/docs/current/dsl/org.gradle.api.tasks.compile.JavaCompile.html)），域對象（例如?[SourceSet](http://gradle.org/docs/current/dsl/org.gradle.api.tasks.SourceSet.html)?），約定（例如主要的 Java 源代碼是位于 src/main/java ），以及擴展的核心對象和其他插件的對象。在這一章中，我們將討論如何使用插件以及術語和插件相關的概念。 ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2021.%20Gradle%20Plugins%20%E6%8F%92%E4%BB%B6.md#211-types-of-plugins-插件類型)21.1\. Types of plugins 插件類型 Gradle 一般有兩種類型的插件 :script 插件和 binary 插件。script 插件是額外的構建腳本，用于進一步配置構建，以及實現一種聲明性方法操縱構建。他們通常用于構建雖然他們可以外部化和從遠程位置訪問。binary插件的類實現?[Plugin](http://gradle.org/docs/current/javadoc/org/gradle/api/Plugin.html)?接口,采用的編程方法操縱構建。binary 插件通過項目層次結構或外部插件 jar 駐留在構建腳本中。 ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2021.%20Gradle%20Plugins%20%E6%8F%92%E4%BB%B6.md#212-applying-plugins-應用插件)21.2\. Applying plugins 應用插件插件是可以被應用的，通過?[Project.apply()](http://gradle.org/docs/current/dsl/org.gradle.api.Project.html#org.gradle.api.Project:apply(java.util.Map))?方法來完成。 ### [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2021.%20Gradle%20Plugins%20%E6%8F%92%E4%BB%B6.md#2121-script-plugins)21.2.1\. Script plugins Example 21.1\. Applying a script plugin build.gradle ~~~ apply from: 'other.gradle' ~~~ script 插件可以從本地文件系統或在遠程位置的腳本應用。文件位置是相對于項目目錄，而遠程腳本的位置是一個 HTTP URL 指定。多個腳本插件（或形式）可以應用到一個給定的建立。 ### [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2021.%20Gradle%20Plugins%20%E6%8F%92%E4%BB%B6.md#2122-binary-plugins)21.2.2\. Binary plugins Example 21.2\. Applying a binary plugin build.gradle ~~~ apply plugin: 'java' ~~~ 核心插件注冊一個簡短的名字。在上面的例子中，我們使用短名稱“java”來應用?[JavaPlugin](http://gradle.org/docs/current/javadoc/org/gradle/api/plugins/JavaPlugin.html)。插件也有插件ID，以一個完全合格的形式如 com.github.foo.bar，雖然一些遺留的插件還可以利用短期的，不合格的形式。該方法還可以接受一個類識別插件： Example 21.3\. Applying a binary plugin by type build.gradle ~~~ apply plugin: JavaPlugin ~~~ 在上述樣本JavaPlugin 符號就是指?[JavaPlugin](http://gradle.org/docs/current/javadoc/org/gradle/api/plugins/JavaPlugin.html)。這類不需要嚴格引入 org.gradle.api.plugins 包在所有構建腳本會自動導入（見[Appendix E. Existing IDE Support and how to cope without it 支持的 IDE 以及如何應對沒有它](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Appendix%20E.%20Existing%20IDE%20Support%20and%20how%20to%20cope%20without%20it%20%E6%94%AF%E6%8C%81%E7%9A%84%20IDE%20%E4%BB%A5%E5%8F%8A%E5%A6%82%E4%BD%95%E5%BA%94%E5%AF%B9%E6%B2%A1%E6%9C%89%E5%AE%83.md)）。此外，不需要追加 .class 來確認這個類是在 Groovy 還是在 Java。插件的應用是冪等。就是說一個插件，可多次應用。如果插件已被應用，任何進一步的應用將沒有任何效果。 #### [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2021.%20Gradle%20Plugins%20%E6%8F%92%E4%BB%B6.md#21221-locations-of-binary-plugins-關于-binary-插件的位置)21.2.2.1\. Locations of binary plugins 關于 binary 插件的位置一個插件是任意類實現?[Plugin](http://gradle.org/docs/current/javadoc/org/gradle/api/Plugin.html)?接口。Gradle 提供核心插件為其分配部分簡單地應用插件來提供所有你需要做的。然而，非核心 binary 插件需要可用于構建類路徑才可以應用。這可以通過很多途徑實現，包括： * 定義插件為內聯類的聲明在一個構建腳本。 * 定義插件作為一個源在項目目錄下的文件 buildsrc。 * 包括從外部罐定義為 buildscript 依賴插件（見[60.5節，“外部依賴關系的構建腳本”](http://gradle.org/docs/current/userguide/organizing_build_logic.html#sec:external_dependencies)）。 * 包括插件從插件門戶使用插件的DSL（見[21.3節，“應用插件與插件DSL”](http://gradle.org/docs/current/userguide/plugins.html#sec:plugins_block)）。更多關于定義你自己的插件，見[Chapter 59\. Writing Custom Plugins 編寫自定義插件](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2059.%20Writing%20Custom%20Plugins%20%E7%BC%96%E5%86%99%E8%87%AA%E5%AE%9A%E4%B9%89%E6%8F%92%E4%BB%B6.md)。 ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2021.%20Gradle%20Plugins%20%E6%8F%92%E4%BB%B6.md#213-applying-plugins-with-the-plugins-dsl-使用dsl應用插件)21.3\. Applying plugins with the plugins DSL 使用DSL應用插件插件DSL目前正在[醞釀中](http://gradle.org/docs/current/userguide/feature_lifecycle.html)。請注意,DSL和其他配置可能會在以后 Gradle版本改變。新的插件提供了一個更簡潔的 DSL 和方便的方式來聲明插件的依賴關系。它的工作原理與新的?[Gradle 插件門戶](http://plugins.gradle.org/)?提供方便地訪問核心和社區插件。插件腳本塊配置實例?[PluginDependenciesSpec](http://gradle.org/docs/current/dsl/org.gradle.plugin.use.PluginDependenciesSpec.html)。申請一個核心插件，可以使用短名稱： 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" } ~~~ 不需要進一步配置。具體來說,不需要配置 buildscript 類路徑。Gradle將在插件門戶解決插件,找到它,使它可用于構建。有關更多信息,請參見?[PluginDependenciesSpec](http://gradle.org/docs/current/dsl/org.gradle.plugin.use.PluginDependenciesSpec.html)?使用插件的 DSL。 ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2021.%20Gradle%20Plugins%20%E6%8F%92%E4%BB%B6.md#214-finding-community-plugins-尋找社區插件)21.4\. Finding community plugins 尋找社區插件 Gradle 至今有一個充滿活力的社區插件開發人員貢獻為各種功能的插件。Gradle?[插件門戶](http://plugins.gradle.org/)提供了一個接口用于搜索和探索社區插件。 ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2021.%20Gradle%20Plugins%20%E6%8F%92%E4%BB%B6.md#215-what-plugins-do-插件做啥)21.5\. What plugins do 插件做啥把插件應用到項目中可以讓插件來擴展項目的功能。它可以做的事情如： * 將任務添加到項目（如編譯、測試） * 使用有用的默認設置對已添加的任務進行預配置。 * 向項目中添加依賴配置（見[第 8.3 節，“依賴配置”](http://gradle.org/docs/current/userguide/artifact_dependencies_tutorial.html#configurations)）。 * 通過擴展對現有類型添加新的屬性和方法。舉例 Example 21.6\. Tasks added by a plugin build.gradle ~~~ apply plugin: 'java' task show << { println relativePath(compileJava.destinationDir) println relativePath(processResources.destinationDir) } ~~~ 執行 gradle -q show ~~~ > gradle -q show build/classes/main build/resources/main ~~~ 這個 Java 插件增加了 compileJava 任務 processResources 任務到項目中，以及給這兩個任務配置 destinationDir 屬性。 ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2021.%20Gradle%20Plugins%20%E6%8F%92%E4%BB%B6.md#216-conventions-約定)21.6\. Conventions 約定插件可以通過智能的方法對項目進行預配置以支持約定優于配置。Gradle 對此提供了機制和完善的支持，而它是強大-然而-簡潔的構建腳本中的一個關鍵因素。在上面的示例中我們看到，Java 插件添加了一個任務，名字為compileJava ，有一個名為 destinationDir 的屬性（即配置編譯的 Java 代碼存放的地方）。Java 插件默認此屬性指向項目目錄中的build/classes/main。這是通過一個合理的默認的約定優于配置的例子。我們可以簡單地通過給它一個新的值來更改此屬性。 Example 21.7\. Changing plugin defaults build.gradle ~~~ apply plugin: 'java' compileJava.destinationDir = file("$buildDir/output/classes") task show << { println relativePath(compileJava.destinationDir) } ~~~ 執行 gradle -q show ~~~ > gradle -q show build/output/classes ~~~ 然而， compileJava 任務很可能不是唯一需要知道類文件在哪里的任務。 Java 插件添加了 source sets 的概念（見[SourceSet](http://gradle.org/docs/current/dsl/org.gradle.api.tasks.SourceSet.html)）來描述的源文件集的各個方面，其中一個方面是在編譯的時候這些類文件應該被寫到哪個地方。Java 插件將 compileJava 任務的 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) } ~~~ 執行 gradle -q show ~~~ > gradle -q show build/output/classes ~~~ 在上面的示例中，我們應用 Java 插件，除其他外，還做了下列操作： * 添加了一個新的域對象類型：?[SourceSet](http://gradle.org/docs/current/dsl/org.gradle.api.tasks.SourceSet.html) * 通過屬性的默認（即常規）配置了 main 源碼集 * 配置支持使用這些屬性來執行工作的任務所有這一切都發生在?`apply plugin: "java"`這一步過程中。在上面例子中，我們在約定配置被執行之后，修改了類文件所需的位置。在上面的示例中可以注意到，compileJava.destinationDir 的值也被修改了，以反映出配置的修改。考慮一下另一種消費類文件的任務的情況。如果這個任務使用sourceSets.main.output.classesDir 的值來配置，那么修改了這個位置的值，無論它是什么時候被修改，將同時更新 compileJava 任務和這一個消費者任務。這種配置對象的屬性以在所有時間內（甚至當它更改的時候）反映另一個對象的任務的值的能力被稱為“映射約定”。它可以令 Gradle 通過約定優于配置及合理的默認值來實現簡潔的配置方式。而且，如果默認約定需要進行修改時，也不需要進行完全的重新配置。如果沒有這一點，在上面的例子中，我們將不得不重新配置需要使用類文件的每個對象。 ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2021.%20Gradle%20Plugins%20%E6%8F%92%E4%BB%B6.md#217-more-on-plugins-更多插件)21.7\. More on plugins 更多插件這一章旨在作為對插件和 Gradle 及他們扮演的角色的導言。關于插件的內部運作的詳細信息，請參閱[Chapter 59\. Writing Custom Plugins 編寫自定義插件](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2059.%20Writing%20Custom%20Plugins%20%E7%BC%96%E5%86%99%E8%87%AA%E5%AE%9A%E4%B9%89%E6%8F%92%E4%BB%B6.md)。