Android Gradle プラグイン Upgrade Assistant を使用する

Android Gradle プラグイン(AGP)Upgrade Assistant は、プロジェクトで使用する AGP のバージョンをアップグレードするために役立つ Android Studio のツールです。

Google は、ビルド設定の新機能、他の Gradle プラグインで使用する新しい API、プロジェクト ビルドと Android Studio との統合の改善に関連する AGP の変更を定期的にリリースしています。プロジェクトで使用する AGP のバージョンをアップグレードすると、最新の機能を利用できます。

AGP Upgrade Assistant の使用目的

AGP Upgrade Assistant は、AGP バージョンをアップグレードするために必要な変更をガイドします。Upgrade Assistant の一般的なユースケースを次に示します。

  • 構文の変更: Upgrade Assistant は、古い AGP バージョンのビルドファイルを新しい AGP バージョンに必要なビルドファイルに変換しようと試みます。Google は、AGP の開発に伴ってビルドファイルを更新し、時間の経過とともに置き換え、非推奨、サポート終了の対象となるインターフェースをサポートします。

  • AGP と Gradle の互換性要件: Upgrade Assistant は、AGP と Gradle の互換性要件を認識し、お使いの AGP バージョンに必要な Gradle バージョンを確実に使用できるようにします。

  • AGP とサードパーティの Gradle プラグインの互換性要件: Upgrade Assistant は、AGP とサードパーティの Gradle プラグインの互換性要件を認識し、お使いの AGP バージョンに必要なサードパーティの Gradle プラグイン バージョンを確実に使用できるようにします。

Upgrade Assistant は、通常、ビルドファイルを変更するために試行錯誤する手間やアップグレード後のエラー メッセージの意味を推測する手間を減らすとともに、Upgrade Assistant が提案する変更がなぜ必要なのかを説明します。

AGP Upgrade Assistant の使用方法

Upgrade Assistant を使用するには、お使いのプロジェクトの構造が Upgrade Assistant に対応していることを確認したうえで、下記の手順に沿って Android Studio から Upgrade Assistant を実行します。

セットアップ

Upgrade Assistant を実行する前に、プロジェクトが適切に構造化され、バックアップされていることを確認します。

Gradle ビルドファイルとドメイン固有の言語でプロジェクトを構造化する

AGP Upgrade Assistant は、次のことを行うと最大限に機能する可能性があります。

  • Gradle ビルドファイルでビルドを設定する: Upgrade Assistant は、Gradle ビルドファイルの静的分析に依存します。Gradle ビルドファイルでビルドを設定すると、Upgrade Assistant を最大限に活用できます。Upgrade Assistant は、ビルドファイルで使用する定数と変数を定義するために buildSrc を使用するプロジェクトはサポートしていません。一般的に、buildSrc を使用したプロジェクトの構造化は非効率的であるため、おすすめしません。buildSrc の定数と変数を変更すると、どんなに些細な変更であっても、プロジェクトの完全な再ビルドがトリガーされます。
  • 宣言型のビルドドメイン固有の言語を使用する: Gradle ビルドファイルは完全なプログラミング言語(Groovy や Kotlin)で表現されます。ただし、プロジェクト構成の表現が宣言的であればあるほど、アップグレードのための調整が必要になるすべての箇所を Upgrade Assistant が検出する可能性が高くなります。

これらの制限を守ってプロジェクトを実行した場合でも、Upgrade Assistant がクリーンなアップグレードに失敗することがあります。バグの解決方法と報告方法については、トラブルシューティングをご覧ください。

プロジェクトをバックアップする

Upgrade Assistant の使用を開始する前に、バージョン管理システムで見つかる未登録の変更をプロジェクトに残さないようにすることをおすすめします。バージョン管理システムを使用していない場合は、その時点で確認済みの最新の正常なバージョンをバックアップすることをおすすめします。

Upgrade Assistant を実行し、プロジェクトが正常にビルドされてテストが成功した後で、プロジェクトの新しいバージョンをバージョン管理システムに登録できます。

Upgrade Assistant を実行する

Upgrade Assistant を実行する手順は次のとおりです。

  1. 通知プロンプトから、または [Tools] > [AGP Upgrade Assistant...] から、Upgrade Assistant を起動します。ツール ウィンドウが開き、プロジェクトの現在の AGP バージョンから、お使いの Android Studio バージョンでサポートされている最新バージョンへのデフォルトのアップグレードの詳細が表示されます。
起動された AGP Upgrade Assistant のツール ウィンドウと通知プロンプト。
図 1. 起動された AGP Upgrade Assistant のツール ウィンドウと通知プロンプト。
  1. 必須のステップと推奨されるステップを確認します。左側のパネルには、アップグレードの個別のステップの詳細を示すチェックボックスを含むツリーが表示されます。これらのステップは、アップグレードするための必須のステップか推奨されるステップか、他のステップの前提条件かそうでないかによって分類されています。ツリー内の個々のアイテムを選択すると、メインパネルに各ステップの詳細が表示されます。

  2. 必要なステップまたは希望するステップを選択し、[Run selected steps] をクリックして、アップグレードを実行します。Upgrade Assistant は、プロジェクト ビルドファイルに変更を加え、新しいプロジェクト ビルドを Android Studio と同期しようと試みます。この処理は、モジュールが多数ある場合、プラグインとライブラリの新しいバージョンのダウンロードが必要になるために、時間がかかることがあります。

  3. プロジェクトが Android Studio と正常に同期されたら、プロジェクトをビルドしてテストスイートを実行し、アップグレード オペレーションによって機能が変更されていないことを確認します。

  4. プロジェクトが良好な状態にあることを確認したら、バージョン管理システムにプロジェクトの新しいバージョンを登録します。

トラブルシューティング

Upgrade Assistant でアップグレードを実行したがアップグレードが失敗する場合(失敗でよくあるのはビルドファイルに加えた変更が原因で同期が失敗する場合です)、エラーを分離して解決するために役立つ手順があります。

  • まず、同期が失敗する原因となったエラーを検査します。エラーの原因が明確で、プロジェクトのビルドファイル内で特定できる場合もあります。

  • エラー メッセージが不明確な場合や問題の原因が不明な場合は、プロジェクトを元の状態に戻し、アップグレードを小さなステップに分割する方法が効果的です。バージョン管理システムまたはバックアップから元の状態を復元し、元の状態のプロジェクトが Android Studio と再び同期されていることを確認します。その後、次の 2 種類の段階的なアップグレードの方法を使用して、問題を調査できます。

    • 最新でない AGP バージョンにアップグレードする。失敗したアップグレードが多数のバージョンを含むアップグレードであった場合、アップグレードを進めて問題を分離するための最良の方法は、バージョンごとの小規模なアップグレードを順次実行して、問題を引き起こす最初のアップグレードを見つけることです。
    • 1 つのアップグレードに含まれる個別のステップを一度に 1 つずつ実行する。連続する AGP バージョンの中で問題を引き起こすアップグレードが見つかったら、そのアップグレードに含まれる個別のステップを分離できる場合があります。分離できたら、個別のステップを一度に 1 つずつ試して、どのステップが問題の原因になっているかを確認します。問題の原因になっているステップが見つからない場合は、お使いの他の Gradle プラグインのリリースノートで、Gradle または AGP の互換性に関する問題を確認することをおすすめします。場合によっては、非推奨になった API や内部 API の使用に関する新しいリリースが提供されていることもあります。
  • バグを報告します。すべての準備ステップと同期が成功したにもかかわらず、最後のアップグレード ステップが失敗することがあります。この場合は、バグを報告してください。

自力でエラーを解決できる場合でも、開発チームが問題を解決できるように、バグトラッカーに問題を報告してください。