Java Quickstart 日本語訳

gradle 公式ページの Chapter 47. Java Quickstart の日本語訳。

Chapter 47. Java Quickstart

47.1. Java プラグイン

これまで見てきたように、 Gradle は汎用ビルドツールです。
ユーザが実装したいことは、ビルドスクリプトでほとんどすべてビルドすることができます。
ただしビルドを実行する為に、ビルドスクリプトにコードを追加する必要があります。

ほとんどの Java プロジェクトは基本的には似ています。
Java ソースファイルをコンパイルし、単体テストを実行し、
クラスを含む JAR ファイルを作成する必要があります。
全プロジェクトにおいて上記の処理をコーディングする必要がなくなれば、
それは素敵なことでしょう。
幸いにも、 Gradle ユーザーは上記の処理をコーディングする必要がありません。
Gradle はこの問題をプラグインの使用によって解決します。
プラグインは何らかの形でプロジェクトを設定できるように拡張するものであり、
事前に設定された便利なタスクを追加します。
Gradle には多数のプラグインが同梱されていますので、
簡単に自分で作成して他の人と共有することができます。
そのようなプラグインの 1 つが Java プラグインです。
このプラグインはプロジェクトの Java ソースコードをコンパイルして単体テストを実行し、
JAR ファイルを生成するいくつかのタスクを追加します。

Java プラグインは規約に基づいています。
プラグインは Java ソースファイルの場所など、
プロジェクトのさまざまな側面の既定値を定義します。
プロジェクト内で規約に従う限り、ビルドスクリプトを大きく変更せずとも
ビルドを実行することができます。
規約に従うことを望まない場合、または規約に従うことができない場合は、
プロジェクトをカスタマイズすることができます。
実際、 Java プロジェクトのサポートはプラグインとして実装されているため、
プラグインを使わずに Java プロジェクトをビルドすることができます。

Java プラグイン、依存関係の管理、およびマルチプロジェクトビルドについては、
後の章で多くの例を取り上げて詳しく説明します。
本章では、 Java プロジェクトを構築するために
Java プラグインを使用する方法の最初のアイデアを提供したいと考えています。

47.2. Java プロジェクトの基礎

簡単な例を見てみましょう。
Java プラグインを使用するには、ビルドファイルに次の行を追加します。

build.gradle

apply plugin: 'java'

注: この例のコードは、 Gradle の '-all' ディストリビューションの
samples/java/quickstart に記載されています。

これが Java プロジェクトを定義するために必要なすべてです。
上記を記載することで Java プラグインがプロジェクトに適用され、
プロジェクトにいくつかのタスクが追加されます。

実行可能となるタスク

gradle tasks を使用すると、プロジェクトのタスクを一覧表示できます。
これにより Java プラグインがプロジェクトに追加したタスクが表示されます。

Gradleは src/main/java の下に本番用のソースコードを、
src/test/java の下にテストソースコードを見つけようとします。
さらに src/main/resources の下のファイルはすべて JAR ファイルにリソースとして含まれ、
src/test/resources の下のファイルはテストの実行に使用されるクラスパスに含まれます。
すべての出力ファイルは build ディレクトリの下に作成され、
JAR ファイルは build/libs ディレクトリに格納されます。

47.2.1. プロジェクトのビルド

Java プラグインは、ユーザのプロジェクトへ大量のタスクを追加します。
しかし、プロジェクトを構築するために必要なタスクはほんの一握りです。
最も一般的に使用されるタスクは、プロジェクトの完全なビルドを行う build タスクです。
gradle build を実行すると、 Gradle はコードをコンパイルしてテストし、
実行クラスとリソースを含む JAR ファイルを作成します。

例 47.2. Java プロジェクトのビルド

gradle build 実行時の出力

> gradle build
:compileJava
:processResources
:classes
:jar
:assemble
:compileTestJava
:processTestResources
:testClasses
:test
:check
:build

BUILD SUCCESSFUL in 0s
6 actionable tasks: 6 executed

便利なタスクをいくつか例示します。

clean

ビルドディレクトリを削除し、ビルドされたすべてのファイルを削除します。

assemble

コードをコンパイルして jar を生成しますが、単体テストは実行しません。
他のプラグインはこのタスクに要素を追加します。
たとえば War プラグインを使用する場合、
このタスクはプロジェクトの WAR ファイルも生成します。

check

コードをコンパイルしてテストします。
他のプラグインは、このタスクにさらに多くのチェックを追加します。
たとえば checkstyle プラグインを使用する場合、
このタスクはソースコードに対して Checkstyle も実行します。

47.2.2. 外部依存関係

通常 Java プロジェクトは外部の JAR ファイルへいくつかの依存関係を持ちます。
プロジェクトでこれらの JAR ファイルを参照するには、
Gradle へ JAR ファイルの取得元を通知する必要があります。
Gradle では JAR ファイルなどの成果物はリポジトリに格納されます。
リポジトリはプロジェクトの依存関係を取得するため、
またはプロジェクトの成果物を公開するため、
またはその両方に使用することができます。
この例では、パブリック Maven リポジトリを使用します。

例 47.3. Maven リポジトリの登録

build.gradle

repositories {
    mavenCentral()
}

いくつか依存関係を追加しましょう。
ここでは、プロダクションクラスが commons collection にコンパイル時に依存関係を持ち、
テストクラスがコンパイル時に junit に依存することを宣言します。

Example 47.4. 依存関係の登録

build.gradle

dependencies {
    compile group: 'commons-collections', name: 'commons-collections', version: '3.2.2'
    testCompile group: 'junit', name: 'junit', version: '4.+'
}

詳細は 第 8 章「依存関係管理の基礎」 を参照してください。

47.2.3. プロジェクトのカスタマイズ

Java プラグインは、プロジェクトにいくつかのプロパティを追加します。
これらのプロパティーには、通常は既定値が設定されています。
プロパティの既定値が適合しない場合は、値を簡単に変更することができます。
例を見てみましょう。
ここでは Java プロジェクトのバージョン番号と、
ソースを記述する Java のバージョンを指定します。
また JAR マニフェストにいくつかの属性を追加します。

例 47.5. MANIFEST.MF のカスタマイズ

build.gradle

sourceCompatibility = 1.7
version = '1.0'
jar {
    manifest {
        attributes 'Implementation-Title': 'Gradle Quickstart',
                   'Implementation-Version': version
    }
}

gradle properties を実行すると、プロジェクトのプロパティを一覧表示することができます。
これにより Java プラグインによって追加されたプロパティーと既定値が表示されます。

Java プラグインが追加するタスクは、ビルドファイルで宣言されたものとまったく同じ、
通常のタスクです。
これは、前の章で示した仕組みを使用してこれらのタスクをカスタマイズできることを意味します。
たとえば、タスクのプロパティを設定したり、ふるまいを追加したり、
タスクの依存関係を変更したり、タスクを完全に置き換えることができます。
サンプルでは、​​テストの実行時にシステムプロパティを追加するために　
Test タイプの test タスクを構成します。

例 47.6. test システムプロパティの登録

build.gradle

test {
    systemProperties 'property': 'value'
}

47.2.4. JAR ファイルの公開

通常 JAR ファイルはどこかに公開する必要があります。
これを行うには Gradle に JAR ファイルをどこに公開するかを通知する必要があります。
Gradle では JAR ファイルなどの成果物がリポジトリに公開されます。
サンプルでは、​​ローカルディレクトリに公開します。
リモートロケーションまたは複数のロケーションに公開することもできます。

例 47.7. JAR ファイルの公開

build.gradle

uploadArchives {
    repositories {
       flatDir {
           dirs 'repos'
       }
    }
}

JAR ファイルを公開するには、 gradle uploadArchives を実行します。

47.2.5. Eclipse プロジェクトの生成

.project のような Eclipse 固有の記述子ファイルを作成するには、
ビルドファイルに別のプラグインを追加する必要があります。

例 47.8. Eclipse プラグイン

build.gradle

apply plugin: 'eclipse'

Eclipse プロジェクトファイルを生成するために gradle eclipse コマンドを実行します。
eclipse タスクの詳細については、 第 67 章「Eclipse プラグイン」 を参照してください。

47.2.6. まとめ

サンプルの完全なビルドファイルを例示します。

例 47.9. Java の例 - 完全なビルドファイル

build.gradle

apply plugin: 'java'
apply plugin: 'eclipse'

sourceCompatibility = 1.7
version = '1.0'
jar {
    manifest {
        attributes 'Implementation-Title': 'Gradle Quickstart',
                   'Implementation-Version': version
    }
}

repositories {
    mavenCentral()
}

dependencies {
    compile group: 'commons-collections', name: 'commons-collections', version: '3.2.2'
    testCompile group: 'junit', name: 'junit', version: '4.+'
}

test {
    systemProperties 'property': 'value'
}

uploadArchives {
    repositories {
       flatDir {
           dirs 'repos'
       }
    }
}

47.3. マルチプロジェクト Java ビルド

次に、典型的なマルチプロジェクトビルドを見てみましょう。
プロジェクトの構成を例示します。

例 47.10. マルチプロジェクトビルド - 階層レイアウト

ビルド構成

multiproject/
  api/
  services/webservice/
  shared/
  services/shared/

注: このサンプルコードは Gradle の '-all' ディストリビューションの
samples/java/multiproject に記載されています。

ここには4つのプロジェクトがあります。
api プロジェクトは JAR ファイルを生成し、
クライアントへ XML Web サービス用の Java クライアントを提供します。
webservice プロジェクトは XML を返す web アプリケーションです。
shared プロジェクトには api と webservice の両方で使用されるコードが含まれています。
services/shared プロジェクトには shared プロジェクトに依存するコードがあります。

47.3.1. マルチプロジェクトの定義

マルチプロジェクトビルドを定義するには、設定ファイルを作成する必要があります。
設定ファイルはソースツリーのルートディレクトリにあり、
ビルドに含めるプロジェクトを指定します。
設定ファイルは必ず settings.gradle と命名する必要があります。
この例では、単純な階層レイアウトを使用しています。
対応する設定ファイルを以下に例示します。

例 47.11. マルチプロジェクトビルド - settings.gradle ファイル

settings.gradle

include "shared", "api", "services:webservice", "services:shared"

設定ファイルの詳細については、 第 26 章「マルチプロジェクトビルド」 を参照してください。

47.3.2. 共通設定

ほとんどのマルチプロジェクトビルドでは、
すべてのプロジェクトに共通の設定がいくつかあります。
サンプルでは、​​設定インジェクションと呼ばれる手法を使用して、
この共通の設定をルートプロジェクトで定義します。
ルートプロジェクトはコンテナのようなもので、
subproject メソッドはこのコンテナの要素(インスタンスのプロジェクト)を繰り返し処理し、
指定された設定を注入します。
このようにして、すべてのアーカイブといくつかの
共通の依存関係のマニフェストコンテンツを簡単に定義できます。

例 47.12. マルチプロジェクトビルド - 共通設定

build.gradle

subprojects {
    apply plugin: 'java'
    apply plugin: 'eclipse-wtp'
    repositories {
        mavenCentral()
    }
    dependencies {
        testCompile 'junit:junit:4.12'
    }
    version = '1.0'
    jar {
        manifest.attributes provider: 'gradle'
    }
}

このサンプルでは、​​各サブプロジェクトに Java プラグインが適用されています。
これは、前のセクションで見たタスクと構成プロパティが、
各サブプロジェクトで使用可能であることを意味します。
したがって、ルートプロジェクトディレクトリから gradle build を実行することによって、
すべてのプロジェクトをコンパイル、テスト、および JAR を生成することができます。
また、これらのプラグインはルートレベルではなく
サブプロジェクトセクションにのみ適用されるので、
ルートビルドは Java ソースファイルをルートプロジェクト内から検索しようとはせず、
サブプロジェクト内でのみ検索します。

47.3.3. プロジェクト間の依存関係

同じビルド内のプロジェクト間に依存関係を追加することができます。
たとえば、あるプロジェクトの JAR ファイルを使用して
別のプロジェクトをコンパイルすることができます。
api ビルドファイルでは shared プロジェクトに依存関係を追加します。
この依存関係のため Gradle は、常に API プロジェクトのビルド前に
shared プロジェクトをビルドします。

例 47.13. マルチプロジェクトビルド - プロジェクト間の依存関係

api/build.gradle

dependencies {
    compile project(':shared')
}

この機能を無効にする方法については、
第 26.7.1 項「依存プロジェクトのビルドを無効にする」 を参照してください。

47.3.4. 成果物の生成

クライアントに配布される成果物を追加します。

例 47.14. マルチプロジェクトビルド - 配布ファイル

api/build.gradle

task dist(type: Zip) {
    dependsOn spiJar
    from 'src/dist'
    into('libs') {
        from spiJar.archivePath
        from configurations.runtime
    }
}
artifacts {
    archives dist
}

47.4. 次に学ぶこと

本章では Java ベースのプロジェクトを構築するために必要な
タスクのいくつかを実行する方法を見てきました。
この章は網羅的ではありません。
Gradle の Java プロジェクトでは他にもたくさんのことができます。
第 48 章「Java プラグイン」 で Java プラグインについて詳しく知ることができます。
また Java プロジェクトのサンプルは、 Gradle ディストリビューションの
samples/java ディレクトリにあります。
それ以外の場合は、 第8章「依存関係管理の基礎」 に進みます。