第五十八章. 编写自定义插件

有几个地方可以放插件的源码。
There are several places where you can put the source for the plugin.

在我们的例子中，我们将从在构建脚本中定义插件开始，以保持简单。随后我们会着眼于创建一个独立的项目。
In our examples, we will start with the plugin in the build script, to keep things simple. Then we will look at creating a standalone project.

要创建自定义插件，你需要编写一个 Plugin 的实现。当插件用于项目时， Gradle 将实例化插件并调用插件实例的 Plugin.apply() 方法。项目对象将作为参数传进去，插件可使用该参数来配置项目。以下示例包含了一个 greeting 插件，其向项目添加了一个 hello 任务。
To create a custom plugin, you need to write an implementation of Plugin. Gradle instantiates the plugin and calls the plugin instance's Plugin.apply() method when the plugin is used with a project. The project object is passed as a parameter, which the plugin can use to configure the project however it needs to. The following sample contains a greeting plugin, which adds a hello task to the project.

apply plugin: GreetingPlugin

class GreetingPlugin implements Plugin<Project> {
    void apply(Project project) {
        project.task('hello') << {
            println "Hello from the GreetingPlugin"
        }
    }
}

> gradle -q hello
Hello from the GreetingPlugin

需要注意的一点是，对于一个给定的插件，每一个应用它的项目都会创建一个新的实例。
One thing to note is that a new instance of a given plugin is created for each project it is applied to.

大多数插件需要从构建脚本获取一些配置。其中一种实现的方法是使用扩展对象。Gradle Project 有一个相关联的 ExtensionContainer 对象，该对象能帮助跟踪传给插件的所有设置和属性。你可以通过告知扩展容器有关插件的信息来捕获用户输入。只要将符合 Java Bean 的类添加到扩展容器的扩展列表中，你就可以获取输入。对于一个插件而言，Groovy 是一种不错的语言选择，因为普通的旧 Groovy 对象就包含了 Java Bean 需要的所有 getter 和 setter 方法。
Most plugins need to obtain some configuration from the build script. One method for doing this is to use extension objects. The Gradle Project has an associated ExtensionContainer object that helps keep track of all the settings and properties being passed to plugins. You can capture user input by telling the extension container about your plugin. To capture input, simply add a Java Bean compliant class into the extension container's list of extensions. Groovy is a good language choice for a plugin because plain old Groovy objects contain all the getter and setter methods that a Java Bean requires.

让我们向项目添加一个简单的扩展对象。这里我们向项目添加了一个 greeting 扩展对象，它可以让从外配置问候语。
Let's add a simple extension object to the project. Here we add a greeting extension object to the project, which allows you to configure the greeting.

apply plugin: GreetingPlugin

greeting.message = 'Hi from Gradle'

class GreetingPlugin implements Plugin<Project> {
    void apply(Project project) {
        // Add the 'greeting' extension object
        project.extensions.create("greeting", GreetingPluginExtension)
        // Add a task that uses the configuration
        project.task('hello') << {
            println project.greeting.message
        }
    }
}

class GreetingPluginExtension {
    def String message = 'Hello from GreetingPlugin'
}

> gradle -q hello
Hi from Gradle

在这个示例中，GreetingPluginExtension 是一个普通的旧 Groovy 对象，它有一个叫 message的字段。这个扩展对象以 greeting 名字添加到插件列表中。然后该对象变为一个有效的项目属性，属性名称与这个扩展对象相同。
In this example, GreetingPluginExtension is a plain old Groovy object with a field called message. The extension object is added to the plugin list with the name greeting. This object then becomes available as a project property with the same name as the extension object.

通常情况下，你会有几个相关联的属性需要在一个插件上指定。Gradle 为每个扩展对象添加了一个配置闭包块，因此你可以把这些设置分组。下面是其如何使用的例子。
Oftentimes, you have several related properties you need to specify on a single plugin. Gradle adds a configuration closure block for each extension object, so you can group settings together. The following example shows you how this works.

apply plugin: GreetingPlugin

greeting {
    message = 'Hi'
    greeter = 'Gradle'
}

class GreetingPlugin implements Plugin<Project> {
    void apply(Project project) {
        project.extensions.create("greeting", GreetingPluginExtension)
        project.task('hello') << {
            println "${project.greeting.message} from ${project.greeting.greeter}"
        }
    }
}

class GreetingPluginExtension {
    String message
    String greeter
}

> gradle -q hello
Hi from Gradle

在此示例中，可以将多个设置分组到 greeting 闭包中。构建脚本中的这个闭包块的名字（greeting）需要与扩展对象的名字匹配。然后，当执行闭包时，扩展对象上的字段将根据标准 Groovy 闭包委托功能映射到闭包内的变量上。
In this example, several settings can be grouped together within the greeting closure. The name of the closure block in the build script (greeting) needs to match the extension object name. Then, when the closure is executed, the fields on the extension object will be mapped to the variables within the closure based on the standard Groovy closure delegate feature.

在开发自定义任务和插件时，文件位置如果能够配置将使插件非常灵活。为此，你可以利用 Project.file() 方法尽可能晚地将值解析为文件。
When developing custom tasks and plugins, it's a good idea to be very flexible when accepting input configuration for file locations. To do this, you can leverage the Project.file() method to resolve values to files as late as possible.

class GreetingToFileTask extends DefaultTask {

    def destination

    File getDestination() {
        project.file(destination)
    }

    @TaskAction
    def greet() {
        def file = getDestination()
        file.parentFile.mkdirs()
        file.write "Hello!"
    }
}

task greet(type: GreetingToFileTask) {
    destination = { project.greetingFile }
}

task sayGreeting(dependsOn: greet) << {
    println file(greetingFile).text
}

ext.greetingFile = "$buildDir/hello.txt"

> gradle -q sayGreeting
Hello!

在这个例子中，我们将 greet 任务的 destination 属性作为闭包配置，它将在最后通过 Project.file() 方法将闭包中的返回值转换为一个文件对象。你会注意到，在上面例子中，我们是配置在任务中使用 greettingFile 属性之后才指定它的值。这种惰性求值的主要好处是在设置文件属性时它能够接收任何值，然后在读取属性时才解析这个值。
In this example, we configure the greet task destination property as a closure, which is evaluated with the Project.file() method to turn the return value of the closure into a file object at the last minute. You will notice that in the example above we specify the greetingFile property value after we have configured to use it for the task. This kind of lazy evaluation is a key benefit of accepting any value when setting a file property, then resolving that value when reading the property.

现在我们将插件移到一个独立的项目中，这样我们就可以发布它，并与他人共享。这个项目只是一个 Groovy 项目，其将生成包含插件类的 JAR。以下是该项目的一个简单的构建脚本。它应用了 Groovy 插件，并将 Gradle API 添加为编译时依赖。
Now we will move our plugin to a standalone project, so we can publish it and share it with others. This project is simply a Groovy project that produces a JAR containing the plugin classes. Here is a simple build script for the project. It applies the Groovy plugin, and adds the Gradle API as a compile-time dependency.

apply plugin: 'groovy'

dependencies {
    compile gradleApi()
    compile localGroovy()
}

那么，Gradle 是如何找到 Plugin 的实现的？答案是你需要在 jar 文件里的 META-INF/gradle-plugins 目录中提供一个属性文件，并且文件名要和插件名相匹配。
So how does Gradle find the Plugin implementation? The answer is you need to provide a properties file in the jar's META-INF/gradle-plugins directory that matches the name of your plugin.

implementation-class=org.gradle.GreetingPlugin

注意，属性的文件名要和插件名相匹配，放在资源文件夹里，并且 implementation-class 属性要指定 Plugin 的实现类。
Notice that the properties filename matches the plugin's name and is placed in the resources folder, and that the implementation-class property identifies the Plugin implementation class.

buildscript {
    repositories {
        maven {
            url uri('../repo')
        }
    }
    dependencies {
        classpath group: 'org.gradle', name: 'customPlugin', version: '1.0-SNAPSHOT'
    }
}
apply plugin: 'greeting'

class GreetingPluginTest {
    @Test
    public void greeterPluginAddsGreetingTaskToProject() {
        Project project = ProjectBuilder.builder().build()
        project.apply plugin: 'greeting'

        assertTrue(project.tasks.hello instanceof GreetingTask)
    }
}

Gradle 提供了一些维护对象集合的实用工具类，能够良好地在 Gradle 构建语言中使用。
Gradle provides some utility classes for maintaining collections of object, which work well with the Gradle build language.

apply plugin: DocumentationPlugin

books {
    quickStart {
        sourceFile = file('src/docs/quick-start')
    }
    userGuide {

    }
    developerGuide {

    }
}

task books << {
    books.each { book ->
        println "$book.name -> $book.sourceFile"
    }
}

class DocumentationPlugin implements Plugin<Project> {
    void apply(Project project) {
        def books = project.container(Book)
        books.all {
            sourceFile = project.file("src/docs/$name")
        }
        project.extensions.books = books
    }
}

class Book {
    final String name
    File sourceFile

    Book(String name) {
        this.name = name
    }
}

> gradle -q books
developerGuide -> /home/user/gradle/samples/userguide/organizeBuildLogic/customPluginWithDomainObjectContainer/src/docs/developerGuide
quickStart -> /home/user/gradle/samples/userguide/organizeBuildLogic/customPluginWithDomainObjectContainer/src/docs/quick-start
userGuide -> /home/user/gradle/samples/userguide/organizeBuildLogic/customPluginWithDomainObjectContainer/src/docs/userGuide

Project.container() 方法创建了 NamedDomainObjectContainer的实例，这些实例有许多用于管理和配置对象的有用方法。为能使用任意一种 project.container 方法的类型，必须公开一个“name”属性，作为对象的唯一且不变的名称。容器方法的 project.container(Class) 变体通过尝试调用该类只有一个 string 参数的构造函数来创建新实例，该参数是这个对象所想要的名称。请参阅以上链接，以查看 project.container 允许自定义实例化策略的重载方法。
The Project.container() methods create instances of NamedDomainObjectContainer, that have many useful methods for managing and configuring the objects. In order to use a type with any of the project.container methods, it MUST expose a property named “name” as the unique, and constant, name for the object. The project.container(Class) variant of the container method creates new instances by attempting to invoke the constructor of the class that takes a single string argument, which is the desired name of the object. See the above link for project.container method variants that allow custom instantiation strategies.