jiakuan版Gradle-GWTプラグインマニュアル（前半）

2018年8月17日2019年7月31日

jiakuan版のGradle-GWTプラグインのマニュアルになる。

コード・ドキュメントは以下。

Table of Contents

概要

このプラグインはGWTを使ったプロジェクトのビルドを簡単にする。提供することは、開発のサポートとGWTを使ったプロジェクトの様々な側面を構成することである。これを自動的に行う。

何よりもまして特にこのプラグインが提供することは以下である。

GWTコンパイラを走らせ、その結果を*.warファイルに自動的に格納する。
GWT Dev Modeを開始する。
Super Dev Modeをサポートする（GWT 2.8以上）
異なるGWTモジュールを構成する、開発とリリースのために。
EclipseプロジェクトのためのGWT特有の構成を行う。

例

いくつかの例が/examplesにある。

使い方

このプラグインはMaven central repositoryにて提供されている。

※訳注：mvnrepositoryにて提供されている。https://mvnrepository.com/artifact/org.wisepersist/gwt-gradle-plugin

以下の例は、Maven/Gradleの標準的なレイアウトを使用してGWTウェブアプリケーションプロジェクトのために、gwt-gradle-plugin をセットアップする例である。

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'org.wisepersist:gwt-gradle-plugin:1.0.6'
    }
}

apply plugin: 'war'
apply plugin: 'gwt'

gwt {
    gwtVersion='2.8.1'
    modules '<YOUR-GWT-MODULE>'
}

これによって、GWTウェブプロジェクトが構成され、GWTコンパイラが実行され、その出力を*.warファイルに格納することができる。上に示したコードはまた、すべてのGWTのコアとなる依存もセットアップする(gwt-dev, gwt-user, gwt-servletなど）。

自身のコンパイルされたGWTモジュールを格納した*.warファイルをビルドするには、単純に「gradle build」を呼び出せばよい。GWT開発モードを開始したい場合には、単純に「gradle gwtDev」を実行すればよい。

異なるシナリオ、あるいはより具体的な構成の必要性については、このドキュメントを読み進めてほしい。

寄与の仕方

Pull Requestを歓迎する。

※訳注：要するに、寄与者による改良結果を本家にマージしてくださいということ。

通常のプロセスとしては以下だ。

議論すべきことについて新たなイシューを起こす。
変更についての議論の後、プロジェクトをフォークして変更して欲しい
プロジェクトをビルドしてエラーの無いことを確認すること
1. プロジェクトルート下でmake clean buildを行う
2. /exaamples下で./gradlew clean buildを行う
レビューとディスカッションのためのPullリクエストをしてほしい
確認の後、我々がpullリクエストをマスターにマージする。

セットアップとコンフィギュレーション

クイックスタート

この章では、ウェブアプリケーションプロジェクトのためのgwt-gradle-pluginの設定の最初のステップをガイドする。

プラグインの依存

これはgradleのコアプラグインではないため、gradleがこのプラグインを取得する方法を確実にしなければならない。これを行うために、次の行をbuild.gradleを追加すること。GWT Gradle PluginはMaven Central Repositoryにて提供されている。

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'org.wisepersist:gwt-gradle-plugin:1.0.6'
    }
}

もし直近のスナップショットバージョンを使いたければ、スナップショットのみを含む以下のリポジトリを使うこともできる。

buildscript {
    repositories {
        maven {
            url "https://oss.sonatype.org/content/repositories/snapshots/"
        }
        mavenCentral()
    }
    dependencies {
        classpath 'org.wisepersist:gwt-gradle-plugin:1.0.7-SNAPSHOT'
    }
}

基本的なウェブアプリケーションのセットアップ

既にwarプラグインがプロジェクトに適用されているものとし、gwtプラグインも適用する。

apply plugin: 'war'
apply plugin: 'gwt'

そうして、ウェブアプリの中に入れるGWTモジュールのコンパイルを設定する。

gwt {
    modules '君のGWTモジュール>'
}

GWTの依存

もし、自動的にGWTの依存（gwt-dev, gwt-user,…)を設定して欲しいのであれば、望みのGWTバージョンを指定すること。

gwt {
    gwtVersion='2.8.1'
    modules '<YOUR-GWT-MODULE>'
}

コンパイラ最適化を指定する

プラグインはデフォルトの最適化設定を適用するが、調整もできる。以下の例では、いくつかのフラグを調整している（これらのフラグが何をするかはドキュメントをあたって欲しい）。

gwt {
    compiler {
        disableClassMetadata = true; // activates -XdisableClassMetadata
        disableCastChecking = true; // activates -XdisableCastChecking
    }
}

Gradleのタスク

自身のGWTモジュールを含む*.warファイルをビルドするには、単純にgradle buildを呼び出す。もし、GWT開発モードを開始したいのであれば、単純にgradle gwtDevを呼ぶこと。

開発モードでのデバッグはどのように？

gwtDevタスクを起動するときに、-gwtDev.debug=trueフラグを指定してデバッグを有効にすることができる。これにより、開発モード開始の際にビルドがストップし、ポート5005にデバッガがアタッチされるのを待つ。そして、このデバッグポートにIDEを接続するようにすればよい。

プロジェクトタイプ

ここでは、gwt-gradle-pluginの扱うことのできる様々なプロジェクトタイプを説明している。

ウェブアプリケーション

ウェブアプリケーションを構成するためにgwt-gradle-pluginを使うのが最もありふれたユースケースだ。「クイックスタート」では、GWTベースにウェブアプリケーションの構成方法を示した。

ライブラリプロジェクト

もし、自身のGWTライブラリ（ウィジェットライブラリなど）を作るのであれば、このプラグインが提供するいくつかの機能のみが必要となる。この種のプロジェクトに必要なものとしては、基本的にGWTの依存である。こういったプロジェクトでは、エントリポイントは不要であり、コンパイルしたり実行したりすべきものはない。

ライブラリプロジェクトを構成するには、gwtやwarではなく、単純にgwt-baseプラグインを使う。加えて、いかなるGWTモジュールも指定する必要がない。

buildscript {
    [...]
}

apply plugin: 'gwt-base'

gwt {
    gwtVersion='2.8.1'
}

コンパイルのみ

もし、アプリケーションを*.warとして配布せずにGWTを使いたいというプロジェクトのためのものだ。このケースでは、典型的には、warプラグインが使われないが、しかしGWTコンパイラが必要だ。この種のプロジェクトを設定するためには、gwt-compilerプラグインを使う。

buildscript {
    [...]
}

apply plugin: 'gwt-compiler'

gwt {
    gwtVersion='2.8.1'
    modules '<君のGWTモジュール>'
}

GWTコンパイラの出力で何をしたいかは、君以外の誰も知らないので、プラグインはcompileGwtタスクを構成する以外の他に何もしない。適切なタスク依存を設定して、このタスクが呼ばれるようにしなければならない。

これについての典型的なユースケースとしては、

GWTコンパイラの出力をmavenリポジトリ等に上げて、他のプロジェクトで使用する
GWTコンパイラの出力を別のプロジェクトに入れ、マルチモジュールビルドとする。

前者のユースケースは、以下のように設定できるかもしれない。

buildscript {
    [...]
}

apply plugin: 'gwt-compiler'
apply plugin: 'maven-publish'

gwt {
    gwtVersion='2.8.1'
    modules '<君のGWTモジュール>'
}

task gwtZip(type: Zip) {
    from tasks.compileGwt.outputs
}

group='<YOUR-GROUP-ID>'
version='<YOUR-VERSION>'
publishing {
    publications {
        mavenJava(MavenPublication) {
            artifact gwtZip {
                extension = 'zip'
                classifier = 'gwt'
            }
        }
    }
    repositories {
        maven {
            url project.file('repo').toURI()
        }
    }
}

後者の例の場合は次のように設定できるかもしれない、もしこれを使うプロジェクトがウェブプロジェクトの場合だ。

apply plugin: 'war'

war {
    from project(':compile-only').tasks.compileGwt.outputs
}

ライブラリプロジェクト(gwt-base）とコンパイルのみ(gwt-compiler)の比較

以下は、gwt-baseとgwt-compilerの違いである。

gwt-baseプラグインは、GWTに関連する設定のみである。例えば、必要な依存だ。これは、通常ライブラリプロジェクトで利用される。ライブラリプロジェクトは通常、GWTのエントリポイントクラスを持たないが、再利用可能なクライアント側コードはある。Guava-gwtがライブラリプロジェクトとして良い例である。
gwt-compilerプラグインはgwt-baseプラグインを拡張しており、実際のgwtCompile、gwtDraftCompile、gwtCheckといったgradleタスクを含んでいる。エントリポイント付きのgwtモジュールが構成されると、このプラグ銀は実際にGWTモジュールをコンパイルする。このプラグインは、ウェブアプリには使わないがGWTモジュールをコンパイルしたいときに有用だ。典型的な例としては、GWTを使ったJavaScriptライブラリを開発したいときなどだ。
gwtプラグインは、単純にgwt-compilerプラグインとwarプラグインの組み合わせである。

GWTの依存

GWTに特有のコンフィギュレーション

このプラグインは二つのカスタムgradleコンフィギュレーションを定義している。

gwtSdk：このコンフィギュレーションはGWT SDKそれ自身に使用されるが、ただし、gwt-servlet(gwt-dev, gwt-user)を除く。
gwt：このコンフィギュレーションが、GWTクライアント特有の依存に使用されるべきである（つまり、GXT等のウィジェットライブラリ）。

“gwt-servlet”はサーバサイドで使用されるため、典型的にはこれはgradleのruntimeコンフィギュレーションに追加する。

自動依存マネージメント

このプラグインは自動的に必要なGWT依存(gwt-dev, gwt-servlet, …)を追加してくれる。必要なこととしては、

GWTアーティファクトが置かれているホストのリポジトリを指定すること。もし、リポジトリを構成しておらず、Maven Central Repositoryを使いたいのであれば、以下をbuild.gradleに記述すること。

repositories { mavenCentral() }

GWTのバージョンを”major.minor.patch-xxx”の形で指定する（つまり、”2.8.1″とか”2.8.20rc3″など）。このためにbuild.gradleに以下を入れる。

gwt { gwtVersion='2.8.1' }

もし、gwtVersionを適切に指定しない場合、自身で適切な依存を追加することが求められる。

ライブラリの追加

以前に言及したように、特定のGWT用クライアントライブラリは、gwtコンフィギュレーションに追加されなければならない。ライブラリにソースコードが提供されていない場合には、ソース依存もまた宣言しなければならない。

dependencies {
    gwt 'foo:bar:1.2.3'
    gwt group: 'foo', name: 'bar', version: '1.2.3', classifier: 'sources'
}

コンフィギュレーションのリファレンス

プラグインのコンフィギュレーション

このプラグインは、GwtPluginExtensionタイプのgwtという名前の拡張をGradleモデルに登録する。この拡張が、すべてのGWT関連タスクにとってのコンベンションとデフォルトを定義している。コンフィギュレーションを行うために、この拡張を利用する場合には、このプラグインは、コンフィギュレーションのプロパティが、すべての関連タスクのデフォルト値と一貫性を持つことを確実にする。すべてのGWT関連タスクのすべてのプロパティは、拡張それ自身において定義されている（例えば、使用されるGWTモジュール）。ある種の特定のタスクのプロパティは、特定のサブオブジェクトで定義されている。

両方の種類のプロパティの例としては以下のようなものだ。

gwt {
    gwtVersion='2.8.1'

    modules 'org.wisepersist.gradle.plugins.gwt.example.Example'

    compiler {
        strict = true
        disableClassMetadata = true
        disableCastChecking = true
    }

    dev {
        noserver = true
        port = 1337
    }
}

プラグイン内部でのプロパティの指定に加え、特定のタスクのデフォルトを上書きすることが可能である。

compileGwtタスクの設定例で異なるGWTモジュールを使う場合としては、以下のようになる。

compileGwt {
    modules = ['org.wisepersist.different.ModuleName']
}

利用可能なコンフィギュレーションパラメータ

以下のリストには、特定のタスクを定義するインターフェース・クラスがあり、また、プラグイン拡張の中での関連するコンフィギュレーションがある。

compileGwt (GwtCompile)
- Extension object: compiler (GwtCompileOptions)
gwtDev (GwtDev)
- Extension object: dev (GwtDevOptions)
gwtSuperDev (GwtSuperDev)
- Extension object: dev (GwtSuperDevOptions)

テスト用コンフィギュレーション

このプラグインのテストサポートとしては、カスタムタスクによるものではなく、GradleのTestタスクを拡張することによる。

これを行うため、GradleのすべてのTestタスクは動的にGwtTestExtensionタイプのgwtプロパティを持つように拡張される。このプラグインの拡張オブジェクトに、GwtTestOptionsのインスタンスがtestプロパティとして加えられる。これを使うことにより、サイドTestタスクのすべてのインスタンスに対するデフォルトを指定することができる。

GWTのテストをサポートするための、Testタスクに対するこの操作を行うため、build.gradleに以下を追加しなければならない。

gwt {
    test {
        hasGwtTests = true
    }
}

共通のケース

メモリ設定

すべてのGWT関連タスク（compileGwt, gwtDev, …）を以下で変更できる。

gwt {
    minHeapSize = "512M"
    maxHeapSize = "1024M"
}

単一のタスクにのみ、これらの設定変更する場合には以下とする。

compileGwt {
    minHeapSize = "512M";
    maxHeapSize = "1024M";
}

両者のデフォルト値は”256M”である。

ログレベル

GWTタスクのログレベルは、Gradleのログレベルに従って自動的に決められる。だから、デフォルトでは”ERROR”である。

Gradleのログレベルを変更するなら（つまり、”–info”や”–debug”をコマンドラインにつける）、これもGWT関連タスクに影響を及ぼす。

Gradleのログレベルとは独立してログレベルを変更する場合はこうする。

gwt {
    logLevel = 'INFO'
}

可能なログレベルとしては、LogLevelに記述されている。

翻訳gradle, GWT

Posted by ysugimura

GWTデベロッパガイド、イントロ