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

Gradle at its core intentionally provides very little for real world automation. All of the useful features, like the ability to compile Java code, are added by plugins. Plugins add new tasks (e.g. JavaCompile), domain objects (e.g. SourceSet), conventions (e.g. Java source is located at src/main/java) as well as extending core objects and objects from other plugins.

Gradleのコア部分には、実際の自動化に役に立つような機能は含まれていません。 これは意図的なもので、Javaのコードをコンパイルしたりといった便利な機能は、全てプラグインにより追加されます。 プラグインは、コア部分のオブジェクトや他のプラグインのオブジェクトを拡張するだけでなく、新しいタスク(JavaCompileなど)やドメインオブジェクト(SourceSetなど)、規約(Javaのコードはsrc/main/javaに置く)、などをGradleに追加します。

In this chapter we will discuss how to use plugins and the terminology and concepts surrounding plugins.

この章では、プラグインを使う方法、プラグインまわりの用語や概念について議論します。

21.1. Types of plugins

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.

21.2. プラグインの適用 Applying plugins

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

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

例21.1 プラグインの適用

build.gradle

apply plugin: 'java'

21.2.1. Script plugins

例21.2 Applying a script plugin

build.gradle

apply from: 'other.gradle'

Script plugins can be applied from a script on the local filesystem or at a remote location. Filesystem locations are relative to the project directory, while remote script locations are specified with an HTTP URL. Multiple script plugins (of either form) can be applied to a given build.

21.2.2. Binary plugins

例21.3 Applying a binary plugin

build.gradle

apply plugin: 'java'

Core plugins register a short name. In the above case, we are using the short name ‘java’ to apply the JavaPlugin. Plugins also have a plugin id that takes a fully qualified form like com.github.foo.bar, although some legacy plugins may still utilize the short, unqualified form.

This method can also accept a class to identify the plugin:

例21.4 Applying a binary plugin by type

build.gradle

apply plugin: JavaPlugin

The JavaPlugin symbol in the above sample refers to the the JavaPlugin. This class does not strictly need to be import as the org.gradle.api.plugins package is automatically imported in all build scripts (see 付録E IDE対応の現状と、IDEによらない開発支援Existing IDE Support and how to cope without it). Furthermore, it is not necessary to append .class to identify a class literal in Groovy as it is in Java.

The application of plugins is idempotent. That is, a plugin can be applied multiple times. If the plugin has previously been applied, any further applications will have no effect.

21.2.2.1. Locations of binary plugins

A plugin is simply any class that implements the Plugin interface. Gradle provides the core plugins as part of its distribution so simply applying the plugin as above is all you need to do. However, non-core binary plugins need to be available to the build classpath before they can be applied. This can be achieved in a number of ways, including:

For more on defining your own plugins, see 59章カスタムプラグインの作成.

21.3. Applying plugins with the plugins DSL

The plugins DSL is currently incubating. Please be aware that the DSL and other configuration may change in later Gradle versions.

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:

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

例21.5 型でプラグインを適用する

build.gradle

apply plugin: JavaPlugin

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

例21.6 Applying a community plugin

build.gradle

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.

21.4. Finding community plugins

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章カスタムプラグインの作成に詳しく記載されています。

21.5. プラグインがすること What plugins do

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:

次の例を見てください。

例21.7 プラグインにより追加されたタスク

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

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プロパティを設定しています。

21.6. 規約 Conventions

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.

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

例21.8 プラグインのデフォルトを変更する

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

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.

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

例21.9 プラグインの規約オブジェクト

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

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

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

  • Added a new domain object type: SourceSet 新しいドメインオブジェクト、SourceSetを追加。
  • Configured a main source set with default (i.e. conventional) values for propertiesmainソースセットに、デフォルト値(つまり規約)を設定。
  • Configured supporting tasks to use these properties to perform work タスクがこれらのプロパティを使って動作するように設定。

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と合理的なデフォルト値による簡潔さを達成しています。また、規定のデフォルト値を変更する場合も一部のオブジェクトを設定するだけでよくなっています。 もしこの方法を採用していなければ、クラスファイルの設定をするのに全てのオブジェクトを変更してまわらなければならなかったところです。

21.7. プラグインをさらに詳しく知るには More on plugins

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章カスタムプラグインの作成.

この章は、プラグインと、プラグインがGradleで果たしている役割について簡単に紹介するためのものです。 プラグインの内部動作について、さらに詳しく知るには、59章カスタムプラグインの作成を参照してください。