Android Gradle プラグイン API のアップデート

このページでは、Android Gradle プラグイン(AGP)API の非推奨と削除に関する情報と、それに応じてコードを更新する方法に関する情報を掲載します。

API の非推奨化と削除の履歴

次の表は、AGP API の非推奨化と削除が行われた時期を AGP バージョンごとにまとめたものです。

API 非推奨になったときの AGP バージョン 削除されたときの AGP バージョン
Component.setAsmFramesComputationMode 7.2
Component.transformClassesWith 7.2
RenderScript 7.2
Transform 7.2 8.0

AGP 8.0

AGP 8.0 における API の重要な更新は次のとおりです。

Transform API が削除されました

AGP 8.0 以降、Transform API は削除されました。これは、パッケージ com.android.build.api.transform 内のすべてのクラスが削除されることを意味します。

Transform API が削除されたのは、ビルドのパフォーマンスを向上させるためです。Transform API を使用するプロジェクトでは、AGP は最適化レベルが低いフローをビルドに使用するよう強制されます。そのため、ビルド時間が大幅に退化する可能性があります。また、Transform API を使用する場合に、それを他の Gradle 機能と組み合わせることも困難です。後継 API は、パフォーマンスまたはビルドの正確性に関する問題を生じさせずに AGP を簡単に拡張できることを目的として設計されています。

後継 API

Transform API の後継 API は 1 つではありません。個別のユースケースをターゲットとする新しい API がいくつかあります。後継 API はすべて androidComponents {} ブロックにあります。これらの API はすべて AGP 7.2 で使用できます。

バイトコードの変換のサポート

バイトコードを変換するには、Instrumentation API を使用します。ライブラリの場合は、ローカル プロジェクト クラスについてのみ計測を登録できます。アプリとテストの場合は、ローカルクラスについてのみ計測を登録するか、ローカルとリモートの依存関係を含むすべてのクラスについて登録するかを選択できます。この API を使用する場合、計測は各クラスで独立して行われ、クラスパス内の他のクラスへのアクセスは制限されます(詳しくは、createClassVisitor() をご覧ください)。この制限により、フルビルドと増分ビルドの両方のパフォーマンスが向上し、API サーフェスはシンプルなままに保たれます。各ライブラリは、すべてのコンパイルの完了後ではなく、準備ができるとすぐに並行して計測可能になります。さらに、単一のクラス内の変更であれば、影響を受けるクラスのみを増分ビルドで再度計測可能にするだけで済みます。Instrumentation API の使用例については、以下をご覧ください。 ASM によるクラスの変換 AGP レシピ。

生成されたクラスのアプリへの追加のサポート

生成されたクラスをアプリに追加するには、Artifacts API を使用して、MultipleArtifact.ALL_CLASSES_DIRS を指定します。具体的には、

artifacts.use(TaskProvider)
  .wiredWith(...)
  .toAppend(Artifact.Multiple)

を使用し、MultipleArtifact.ALL_CLASSES_DIRS を指定して、生成された追加のディレクトリをプロジェクト クラスの末尾に付加します。Artifacts API は、カスタムタスクの出力先となる一意の場所を自動的に選択します。詳しくは、 addToAllClasses レシピ をご覧ください。

全体的なプログラム分析に基づく変換のサポート

全体的なプログラム分析に基づく変換を実装するには、すべてのクラスを単一のタスクにまとめて変換します。この手法を使用する場合は、Instrumentation API を使用する場合よりもビルド パフォーマンスのコストが大幅に高くなるため、注意が必要です。プラグインがこの API を使用している場合は、ビルドタイプごとに変換のオプトインを提供して、アプリ デベロッパーが開発用ビルドで無効にできるようにすることをおすすめします。

すべてのクラスをまとめて変換するタスクを登録するために、Android Gradle プラグイン 7.4 では Artifacts.forScope API が導入されました。現在のプロジェクト内のすべてのクラスを変換するには、Artifacts.forScope.PROJECT を使用します。現在のプロジェクト内のすべてのクラス、インポートされたプロジェクト、すべての外部依存関係を変換するには、Artifacts.forScope.ALL を使用します。次のコードは、すべてのクラスをまとめて変換するタスクを Artifacts.forScope.ALL を使用して登録する方法を示しています。

variant.artifacts.forScope(ScopedArtifacts.Scope.ALL)
    .use(taskProvider)
    .toTransform(
        ScopedArtifact.CLASSES,
        ModifyClassesTask::allJars,
        ModifyClassesTask::allDirectories,
        ModifyClassesTask::output,
    )

詳しくは、 modifyProjectClasses レシピ をご覧ください。また、 customAgpDsl レシピ をご覧ください。

いずれの AndroidComponents API もご自分のユースケースに対応していない場合は、バグを報告してください。

よく使用されるいくつかのプラグインは、新しい API を使用できるようにすでに移行されています。たとえば、Firebase Performance Monitoring プラグイン(1.4.1 が AGP 8.0 に対応)や、Hilt Gradle プラグイン(2.40.1 が AGP 8.0 に対応)などです。また、プロジェクト デベロッパーがよく使用されるプラグインを必要に応じてアップグレードする際は、AGP Upgrade Assistant が役に立ちます。

サードパーティのプラグインを介して Transform API を使用している場合は、プラグインの作成者に、AGP 8.0 の新しい API で動作させるにはプラグインの更新が必要であることを知らせてください。

AGP 7.2

AGP 7.2 の API の重要な更新は次のとおりです。

RenderScript が非推奨になりました

AGP 7.2 以降、RenderScript API は非推奨になります。それらの API は引き続き機能しますが、警告がトリガーされ、AGP の将来のバージョンで完全に削除される予定です。RenderScript からの移行方法については、RenderScript からの移行をご覧ください。

Component.transformClassesWithComponent.setAsmFramesComputationMode が非推奨になりました

AGP 7.2 以降、クラス バイトコード インストルメンテーション API の Component.transformClassesWithComponent.setAsmFramesComputationMode は非推奨になり、新しいブロック Component.instrumentation に移行しました。このブロックには、インストルメンテーション プロセスの構成に関する API がすべて含まれています。これらのインストルメンテーション機能を引き続き使用するには、新しいブロックの対応する API を代わりに使用してください(以下のコード スニペットを参照)。

androidComponents {
      onVariants(selector().all(), {
          instrumentation.transformClassesWith(AsmClassVisitorFactoryImpl.class,
                                               InstrumentationScope.Project) { params ->
              params.x = "value"
          }
          instrumentation.setAsmFramesComputationMode(
              COMPUTE_FRAMES_FOR_INSTRUMENTED_METHODS
          )
      })
  }