第59章 カスタムプラグインの作成

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.

このサンプルでは、簡単のためにビルドスクリプト内のプラグインからはじめます。 その後、スタンドアロンプロジェクトの作り方をみてみましょう。

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.

カスタムプラグインを作るには、Pluginの実装を作成する必要があります。 Gradleはプラグインのインスタンスを生成し、プロジェクトでプラグインが利用されるときにプラグインインスタンスのPlugin.apply()メソッドを呼びます。 プロジェクトオブジェクトがパラメータとして渡され、必要に応じてプラグインがプロジェクトを構成するのに使えます。 次のサンプルは、プロジェクトにhelloタスクを追加するgreetingプラグインを含んでいます。

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. Also note that the Plugin class is a generic type. This example has it receiving the Plugin type as a type parameter. It's possible to write unusual custom plugins that take different type parameters, but this will be unlikely (until someone figures out more creative things to do here).

注意すべきは、指定されたプラグインが適用されるプロジェクト毎に、新しいプラグインのインスタンスが生成されることです。Also note that the Plugin class is a generic type. This example has it receiving the Plugin type as a type parameter. It's possible to write unusual custom plugins that take different type parameters, but this will be unlikely (until someone figures out more creative things to do here).

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.

プロジェクトにシンプルなextensionオブジェクトを追加してみましょう ここでは、プロジェクトにextensionオブジェクトgreetingを追加し、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

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.

この例では、GreetingPluginExtensionはmessageフィールドを持つPOGO(plain old Groovy object)です。 extensionオブジェクトはgreetingという名前でプラグインリストに追加されます。 このオブジェクトは、extensionオブジェクトと同じ名前のプロジェクトプロパティとして有効になります。

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.

しばしば、ひとつのプラグインに対していくつかの関連したプロパティを指定する必要がある場合があります。 Gradleはそれぞれのextensionオブジェクトに対してコンフィグレーションクロージャブロックを追加するので、 グループの設定をまとめて行うことができます。 次のサンプルは、これがどのように働くのかを示しています。

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

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.

この例では、greetingクロージャ内にいくつかの設定をグループ化してまとめることができています。 ビルドスクリプトにおけるクロージャブロックの名前(greeting)は、extensionオブジェクトの名前と一致している必要があります。 そして、クロージャが実行されると、Groovyの標準のクロージャ委譲機能に基づいて、extensionオブジェクトのフィールドはクロージャ内の変数にマップされます。

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.

カスタムタスクやプラグインを開発するとき、ファイルロケーションの入力コンフィグレーションを柔軟に行えるようにするのは良いアイデアです。 これを実現するにあたり、ファイルに対する値の解決をなるべく遅らせるためにProject.file()メソッドを活用できます

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!

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.

この例では、greetタスクのdestinationプロパティをクロージャで定義したので、 クロージャの戻り値をfileオブジェクトに変換することが必要になる直前にProject.file()メソッドによって評価されます。 上記のサンプルでは、タスクで値を利用するコンフィグレーションを行った後でgreetingFileプロパティの値を指定していることに気づくでしょう。 この種の遅延評価は、ファイルプロパティを設定する際に任意の値を受け入れ、そしてプロパティの読み出し時に値を解決することができるという重要なメリットをもたらします。

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.

それでは、プラグインをスタンドアロンプロジェクトに移動して、発行して他のユーザーと共有できるようにしましょう。 このプロジェクトは、プラグインクラスを含むJARを発行する単なるGroovyプロジェクトです。 プロジェクトに対するシンプルなビルドスクリプトはこのようになります。 Groovyプラグインを適用して、コンパイル時の依存関係としてGradle APIを追加しています。

apply plugin: 'groovy'

dependencies {
    compile gradleApi()
    compile localGroovy()
}

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 id of your plugin.

GradleはどのようにしてPluginの実装を探すのでしょうか？ その答えは、JARのMETA-INF/gradle-pluginsディレクトリに、 プラグインのIDに対応するプロパティファイルを提供する必要があるということです。

implementation-class=org.gradle.GreetingPlugin

Notice that the properties filename matches the plugin id and is placed in the resources folder, and that the implementation-class property identifies the Plugin implementation class.

プロパティファイルの名前がプラグインIDと一致していてリソースフォルダに配置されていること、 implementation-classプロパティにPluginの実装クラスを指定していることに注意してください。

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

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

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

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

apply plugin: 'java-gradle-plugin'

Gradle provides some utility classes for maintaining collections of objects, which work well with the Gradle build language.

Gradleはオブジェクトのコレクションを管理するためのユーティリティクラスを提供しており、それらはGradleビルド言語の中で活用できます。

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

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.

Project.container()メソッドは、 オブジェクトの管理やコンフィグレーションに便利な多くのメソッドを提供する NamedDomainObjectContainerのインスタンスを生成します。 project.containerのメソッドでタイプを扱うためには、 オブジェクトのユニークかつ固定の名前を提供する“name”プロパティを公開しなければなりません。 project.container(Class)メソッドおよびそのバリエーションは、 単一のstringを引数として取るクラスのコンストラクタの実行を試みることで新しいインスタンスを生成します。 このとき、引数はオブジェクトの名前となることが期待されます。 カスタムのインスタンス化戦略を可能にするproject.containerメソッドのバリエーションについては、上記のリンクを参照してください。