Asakusa Gradle Plugin マイグレーションガイド

ここでは、Asakusa Gradle Plugin で構築した開発環境のバージョンアップ手順や、 従来のAsakusa Frameworkが提供するMavenベースのビルドシステムからAsakusa Gradle Pluginを使ったビルドシステムに移行するための手順を説明します。

Asakusa Frameworkの各バージョン固有のマイグレーション情報については 開発環境マイグレーションガイド に説明があるので、こちらも必ず確認してください。

Gradleプロジェクトのマイグレーション

ここではAsakusa Gradle Pluginを利用したアプリケーションプロジェクトをマイグレーションする手順例を説明します。

Attention

Asakusa Framework バージョン 0.6.0 ～ 0.10.3 からマイグレーションを行う場合、本書の手順を実施する前に Maven Centralとgradle.orgのHTTP接続無効化の影響について の内容を確認してください。

Note

以降ではコマンドライン上での手順を説明しますが、Shafuを利用している場合も手順は同様です。 利用するメニューなどについては、 Shafuのドキュメント を参照してください。

マイグレーション前のビルドの確認

マイグレーション以前の状態でプロジェクトのフルビルドを行い、ビルドが成功することを確認します。

./gradlew clean build

Attention

Maven Centralとgradle.orgのHTTP接続無効化の影響について で説明している「Maven CentralへのHTTPアクセスによるビルドエラー」の問題が発生している環境ではここの手順のフルビルドは失敗しますが、そのまま次の手順に進んでください。

Attention

Maven Centralとgradle.orgのHTTP接続無効化の影響について で説明している「gradle.orgへのHTTPアクセスによるビルドエラー」の問題が発生している環境では、同ページの「gradle.orgへのHTTPアクセスによるビルドエラーが発生した場合の対応」の手順を実施してビルドエラーを回避してください。

また、ビルドが成功した状態のプロジェクトをバックアップするなど、マイグレーション作業で問題が発生した場合にすぐに元の状態に戻れるようにしておきます。

Hint

この手順は必須ではありませんが、マイグレーション作業時に問題が発生した場合に備えて実施しておくことを推奨します。

Asakusa Gradle Pluginのバージョン変更

ビルドスクリプト内の buildscript ブロック内に定義しているAsakusa Gradle Pluginのバージョンの値を、アップデートするAsakusa Gradle Pluginのバージョンに変更します。

build.gradle
buildscript {
    repositories {
        maven { url 'https://asakusafw.s3.amazonaws.com/maven/releases' }
    }
    dependencies {
        classpath group: 'com.asakusafw.gradle', name: 'asakusa-distribution', version: '0.10.4'
    }
}

Attention

バージョン 0.8系以前のバージョンからマイグレーションする場合、 利用するプラグインをディストリビューションプラグインに変更してください。

詳しくは、 Asakusa Gradle Plugin バージョン 0.9系 の変更点 を参照してください。

バージョン固有のビルドスクリプト設定の変更

Asakusa Frameworkの各バージョンで、ビルドスクリプトに関するバージョン固有のマイグレーション手順が示されている場合、ここでビルドスクリプトの内容を編集します。

Gradleラッパーのアップデート

アプリケーションプロジェクトで利用するGradleラッパーをAsakusa Gradle Pluginが推奨するバージョンにアップデートします。

プロジェクトディレクトリに移動し、 asakusaUpgrade タスクを実行します。

./gradlew asakusaUpgrade

asakusaUpgrade タスクを実行後、 help タスクを実行するとGradleラッパーのバージョンを確認できます。

./gradlew help

:help

Welcome to Gradle 4.7.
...

Attention

Shafuを利用している場合、ShafuはプロジェクトのGradleラッパーを使用せず、Shafu側で設定されているGradleを使用します。 Shafuが利用するGradleのバージョンをアップデートするにはShafu側の設定を変更する必要があります。

Shafuの設定については Shafuのドキュメント を参照してください。

Asakusa Frameworkの再インストール

開発環境のAsakusa Frameworkを再インストールします。

./gradlew installAsakusafw

マイグレーションしたビルド設定の確認

マイグレーション後の状態でプロジェクトのフルビルドを行い、ビルドが成功することを確認します。

./gradlew clean build

Eclipse定義ファイルの更新

Eclipseを利用している場合は、Eclipse用定義ファイルを更新します。

./gradlew cleanEclipse eclipse

Mavenプロジェクトのマイグレーション

ここでは、 Mavenアーキタイプ利用ガイド や Asakusa Framework バージョン 0.5.3 以前の Asakusa Framework スタートガイド 及び Jinrikisha (人力車) - Asakusa Framework Starter Package - で記載されている手順に従って構築した開発環境やMavenベースのアプリケーションプロジェクト(以下「Mavenプロジェクト」と表記)をAsakusa Gradle Pluginを使った環境にマイグレーションする手順を説明します。

Attention

プロジェクトのソースディレクトリに含まれるアプリケーションのソースコード(Asakusa DSL, DMDL, テストコードなど)についてのマイグレーション作業は不要で、そのまま利用することが出来ます。

マイグレーション前のビルドの確認

Hint

この手順は必須ではありませんが、マイグレーション作業時に問題が発生した場合に備えて実施しておくことを推奨します。

マイグレーション以前の状態でプロジェクトのフルビルドを行い、ビルドが成功することを確認します。

mvn clean package

また、ビルドが成功した状態のプロジェクトをバックアップするなど、マイグレーション作業で問題が発生した場合にすぐに元の状態に戻れるようにしておきます。

プロジェクトテンプレートの適用

Asakusa Gradle Pluginのプロジェクトテンプレートに含まれるファイル一式をMavenプロジェクトに適用します。

以下は、ダウンロードしたプロジェクトテンプレートを $HOME/workspace/migrate-app に適用する例です。

cd ~/Downloads
tar xf asakusa-*-template-*.tar.gz
cd asakusa-*-template
cp -a build.gradle gradlew gradlew.bat .buildtools ~/workspace/migrate-app

プロジェクト初期設定ファイルの適用

MavenプロジェクトとAsakusa Gradle Pluginのプロジェクトテンプレートの両方に含まれるプロジェクトの初期設定ファイルに対しては、以下のファイル内容を確認し、必要に応じてMavenプロジェクトに適用します。

MavenプロジェクトとAsakusa Gradle Pluginのプロジェクトテンプレートの両方に含まれるファイルの一覧を以下に示します。

ファイル 説明
src/test/resources/logback-test.xml ビルド/テスト実行時に使用されるログ定義ファイル

Tip

Mavenプロジェクトで上記の設定ファイルをデフォルト設定のまま利用している場合は、Asakusa Gradle Pluginのプロジェクトテンプレートの内容で上書きすることを推奨します。

プロジェクト定義のマイグレーション

Mavenプロジェクトのプロジェクト定義( pom.xml )の内容をGradleのビルドスクリプト( build.gradle )に反映します。

pom.xml の代表的なカスタマイズ内容として、アプリケーションで利用するライブラリ追加による依存関係の設定があります。これは pom.xml 上では dependencies 配下に定義していました。

Gradle、およびAsakusa Gradle Pluginでは従来のMavenベースの依存関係の管理から一部機能が変更になっているため、 Asakusa Gradle Plugin ユーザーガイド - 依存ライブラリの管理 や Asakusa Gradle Plugin リファレンス などの内容を確認してアプリケーションに対して適切な設定を行ってください。

その他に確認すべき点は、標準プロジェクトプロパティの内容です。 これに相当する内容はMavenアーキタイプからプロジェクトを作成する際に入力した内容が pom.xml のトップレベルの階層に定義されています。

以下、この箇所に該当する pom.xml の設定例です。

pom.xml
    <name>Example Application</name>
    <groupId>com.example</groupId>
    <artifactId>migrate-app</artifactId>
    <version>1.0-SNAPSHOT</version>

Gradleではこれらのプロパティについてビルドスクリプト上の定義は必須ではありませんが、必要に応じて pom.xml の設定を反映するとよいでしょう。

ビルド定義ファイルのマイグレーション

従来のMavenのビルド定義ファイル( build.properties )の内容をGradleのビルドスクリプト( build.gradle )に反映します。 ビルド定義ファイルの内容は、移行後の build.gradle では Batch Application Plugin 上の規約プロパティとして定義します。

ここで必ず確認すべき項目は、Mavenアーキタイプでプロジェクトを作成した内容が反映される以下のプロパティです。

プロパティ 対応するbuild.gradle上の設定項目 説明
asakusa.modelgen.package asakusafw.modelgen.modelgenSourcePackage データモデルクラスに使用されるパッケージ名

その他の項目については、 build.properties をデフォルト値のまま利用している場合は移行作業は不要です。 変更しているものがある場合は Asakusa Gradle Plugin ユーザーガイド - ビルド設定のカスタマイズ や Asakusa Gradle Plugin リファレンス 上の規約プロパティを確認し、設定を反映してください。

Asakusa Frameworkの再インストール

開発環境のAsakusa Frameworkを再インストールします。

./gradlew installAsakusafw

マイグレーションしたビルド設定の確認

マイグレーション後の状態でプロジェクトのフルビルドを行い、ビルドが成功することを確認します。

./gradlew clean build

Eclipse定義ファイルの更新

Eclipseを利用している場合は、Eclipse用定義ファイルを更新します。

./gradlew cleanEclipse eclipse

Mavenビルド用ファイルの削除

Mavenプロジェクトのビルドで利用していた以下のファイル、ディレクトリを削除します。

  • pom.xml
  • build.properties
  • target

Maven Framework Organizerのマイグレーション

従来の Maven Framework Organizer [1] で提供していた機能は、Asakusa Gradle Plugin によって提供されます。 詳しくは Asakusa Gradle Plugin ユーザーガイド や Asakusa Gradle Plugin リファレンス の内容を確認してください。

[1]Maven Framework Organizer利用ガイド