第21章 Gradleのプラグインについて

There are two general types of plugins in Gradle, script plugins and binary plugins. Script plugins are additional build scripts that further configure the build and usually implement a declarative approach to manipulating the build. They are typically used within a build although they can be externalized and accessed from a remote location. Binary plugins are classes that implement the Plugin interface and adopt a programmatic approach to manipulating the build. Binary plugins can reside within a build script, within the project hierarchy or externally in a plugin jar.

Plugins are said to be applied, which is done via the Project.apply() method.

プラグインの、いわゆる適用は、Project.apply()メソッドで行います。

apply plugin: 'java'

apply from: 'other.gradle'

apply plugin: 'java'

apply plugin: JavaPlugin

The new plugins DSL provides a more succinct and convenient way to declare plugin dependencies. It works with the new Gradle plugin portal to provide easy access to both core and community plugins. The plugins script block configures an instance of PluginDependenciesSpec.

プラグインは、自分自身を示す短縮名を保持、公開しています。 上の例では、短縮名'java'を使ってJavaPluginを適用しています。

We could also have used the following syntax:

以下は短縮名を使わなかった場合の例です。

apply plugin: JavaPlugin

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

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

No further configuration is necessary. Specifically, there is no need to configure the buildscript classpath. Gradle will resolve the plugin in the plugin portal, locate it, and make it available to the build.

See PluginDependenciesSpec for more information on using the Plugin DSL.

Gradle has a vibrant community of plugin developers who contribute plugins for a wide variety of capabilities. The Gradle plugin portal provides an interface for searching and exploring community plugins.

また、プラグインの作り方は59章カスタムプラグインの作成に詳しく記載されています。

Applying a plugin to the project allows the plugin to extend the project's capabilities. It can do things such as:

プラグインを適用することで、そのプロジェクトの機能を拡張することができます。例えば、

Let's check this out:

次の例を見てください。

apply plugin: 'java'

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

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

The Java plugin has added a compileJava task and a processResources task to the project and configured the destinationDir property of both of these tasks.

Javaプラグインは、compileJavaタスクとprocessResourceタスクをプロジェクトに追加し、それぞれのタスクにdestinationDirプロパティを設定しています。

Plugins can pre-configure the project in smart ways to support convention-over-configuration. Gradle provides mechanisms and sophisticated support and it's a key ingredient in powerful-yet-concise build scripts.

プラグインは、CoC(設定より規約)をというスマートな方法をサポートするため、プロジェクトを事前に設定しておくことができます。 Gradleにはこのメカニズムと洗練されたサポートがあり、パワフルかつ簡潔なビルドスクリプトを記述するためのカギになっています。

We saw in the example above that the Java plugins adds a task named compileJava that has a property named destinationDir (that configures where the compiled Java source should be placed). The Java plugin defaults this property to point to build/classes/main in the project directory. This is an example of convention-over-configuration via a reasonable default.

先ほどの例、JavaプラグインがcompileJavaタスクを追加し、そこにdestinationDirプロパティ(コンパイルしたソースが出力される場所)を追加したコードを思い出してください。 Javaプラグインは、デフォルトでこのプロパティが、プロジェクトディレクトリのbuild/classes/mainを指すよう設定します。これは、合理的なデフォルト値を設定するCoCの一例です。

We can change this property simply by giving it a new value.

このプロパティは、新しい値を設定するだけで簡単に変更できます。

apply plugin: 'java'

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

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

> gradle -q show
build/output/classes

However, it's likely that the compileJava task is not the only task that needs to know where the class files are.

ただ、クラスファイルの出力場所が関係するタスクは、おそらくcompileJavaタスクだけではないでしょう。

The Java plugin adds the concept of source sets (see SourceSet) to describe the aspects of a set of source files, one aspect being where the class files should be written to when they are compiled. The Java plugin maps the destinationDir property of the compileJava task to this aspect of the source set.

Javaプラグインは、プロジェクトにソースセットという概念を追加します(SourceSet参照)。 ソースセットは、ソースコード一式を示す概念であり、それらがコンパイルされた際にクラスファイルが書き出される場所を示す概念でもあります。 Javaプラグインは、compileJavaタスクのdestinationDirプロパティを、ソースセットが示す出力場所にマップしているのです。

We can change where the class files are written via the source set.

クラスファイルの書き出される場所を、ソースセットで変更することができます。

apply plugin: 'java'

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

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

> gradle -q show
build/output/classes

In the example above, we applied the Java plugin which, among other things, did the following:

この例で、Javaプラグインは以下のようなことを含む様々な処理を行っています。

All of this happened during the “apply plugin: "java"” step. In the example above, we changed the desired location of the class files after this conventional configuration had been performed. Notice by the output with the example that the value for compileJava.destinationDir also changed to reflect the configuration change.

この全てが、apply plugin: "java"のステップで行われています。例では、規定の設定が行われた後、クラスファイルの場所を変更しました。 compileJava.destinationDirの値が、設定の変更を反映して変わっていることに注目してください。

Consider the case where another task needs to consume the class files. If this task is configured to use the value from sourceSets.main.output.classesDir, then changing it in this location will update this new task in addition to the compileJava task whenever it is changed.

別のタスクが、クラスファイルを使用するケースを考えてください。そのタスクが、クラスファイルの場所をsourceSets.main.output.classesDirを参照して取得するようになっていれば、ソースセットを変更するだけでcompileJavaとそのタスク、両方の設定が更新されます。

This ability to configure properties of objects to reflect the value of another object's task at all times (i.e. even when it changes) is known as “convention mapping”. It allows Gradle to provide conciseness through convention-over-configuration and sensible defaults yet not require complete reconfiguration if a conventional default needs to be changed. Without this, in the example above, we would have had to reconfigure every object that needs to work with the class files.

他のタスクの設定値をいつでも(つまり、変更されたときでさえ)反映するよう、オブジェクトのプロパティを設定できるこの方法は、規約マッピングとして知られています。 この方法により、GradleはCoCと合理的なデフォルト値による簡潔さを達成しています。また、規定のデフォルト値を変更する場合も一部のオブジェクトを設定するだけでよくなっています。 もしこの方法を採用していなければ、クラスファイルの設定をするのに全てのオブジェクトを変更してまわらなければならなかったところです。

This chapter aims to serve as an introduction to plugins and Gradle and the role they play. For more information on the inner workings of plugins, see 59章カスタムプラグインの作成.