Back to Details

agp-9-upgrade

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Migration guide

迁移指南

See the AGP 9 migration guide for the major changes, many breaking, in AGP 9 compared to AGP 8.
请查看AGP 9迁移指南，了解AGP 9相较于AGP 8的重大变更（其中包含许多破坏性变更）。

Requirements

要求

If the user requests to update or migrate to AGP 9, first check the AGP version used in the project. If it is lower than 9, stop and ask the user to run the AGP Upgrade Assistant in Android Studio to update to the latest stable version of AGP, and confirm when done. The user may also request that this requirement be skipped; if this is the case, you should update the version of AGP to the latest stable version as part of the AGP 9 migration. See the AGP 9 migration guide for how to do this.
Each version of AGP has its own set of compatibilities with other tools, such as Gradle, JDK, and Kotlin. The release notes for each of these versions will include a Compatibility table indicating the minimum versions for these tools.
Do not use this skill for KMP projects, as they are unsupported.
如果用户请求更新或迁移至AGP 9，请首先检查项目中使用的AGP版本。若版本低于9，请停止操作并要求用户在Android Studio中运行AGP升级助手，将其更新至AGP的最新稳定版本，完成后请确认。用户也可能要求跳过此要求；若出现这种情况，你应在AGP 9迁移过程中将AGP版本更新至最新稳定版本。有关操作方法，请查看AGP 9迁移指南。
每个AGP版本都与Gradle、JDK和Kotlin等其他工具存在特定的兼容性。各版本的发布说明中会包含一个兼容性表格，标明这些工具的最低版本要求。
请勿将此技能用于KMP项目，此类项目暂不支持。

Steps

步骤

If AGP is already at 9 or higher, then do the following:
如果AGP版本已为9或更高版本，请执行以下操作：

Step 1: Update dependencies

步骤1：更新依赖项

If KSP (
com.google.devtools.ksp
) is used in the project, ensure it is on version 2.3.6 or higher.
If Hilt is used in the project, ensure it is on version 2.59.2 or higher.
如果项目中使用了KSP（
com.google.devtools.ksp
），请确保其版本为2.3.6或更高。
如果项目中使用了Hilt，请确保其版本为2.59.2或更高。

Step 2: Migrate to built-in Kotlin

步骤2：迁移至内置Kotlin

See the guide for detailed information.
有关详细信息，请查看指南。

Step 3. Migrate to the new AGP DSL

步骤3：迁移至新的AGP DSL

See the guide for detailed information.
See also gradle-recipes for examples on how to migrate old code to code that is compatible with AGP 9 and the new DSL.
有关详细信息，请查看指南。
另请查看gradle-recipes，获取将旧代码迁移至兼容AGP 9和新DSL的代码示例。

Step 4. Migrate kapt to KSP or legacy-kapt

步骤4：将kapt迁移至KSP或legacy-kapt

If KSP (
com.google.devtools.ksp
) or kapt (
org.jetbrains.kotlin.kapt
) are used in the project, see KSP, kapt, and legacy-kapt for detailed migration steps.
如果项目中使用了KSP（
com.google.devtools.ksp
）或kapt（
org.jetbrains.kotlin.kapt
），请查看KSP、kapt与legacy-kapt获取详细迁移步骤。

Step 5. BuildConfig

步骤5：BuildConfig

If any Android module contains custom BuildConfig fields, see BuildConfig for detailed information.
如果任何Android模块包含自定义BuildConfig字段，请查看BuildConfig获取详细信息。

Step 6. Update gradle.properties

步骤6：更新gradle.properties

After the migration, check gradle.properties. Remove the following flags:
  1. android.builtInKotlin
  2. android.newDsl
  3. android.uniquePackageNames
  4. android.enableAppCompileTimeRClass
Additionally, delete all temporary files you've created.
迁移完成后，请检查gradle.properties文件。移除以下标志：
  1. android.builtInKotlin
  2. android.newDsl
  3. android.uniquePackageNames
  4. android.enableAppCompileTimeRClass
此外，请删除所有你创建的临时文件。

Guidelines

指南

  • Never write or run python scripts.
  • Only search the Gradle dependency cache when inspecting external dependencies, and only as a last resort.
  • Never add 
    android.disallowKotlinSourceSets=false
    to 
    gradle.properties
    .
  • When verifying changes, don't run the 
    clean
    task. This is a waste of time.
  • 切勿编写或运行Python脚本。
  • 检查外部依赖项时，仅作为最后手段才搜索Gradle依赖缓存。
  • 切勿在
    gradle.properties
    中添加
    android.disallowKotlinSourceSets=false
    。
  • 验证变更时，请勿运行
    clean
    任务，这会浪费时间。

Verification

验证

After migration, verify the following:
  1. Gradle IDE sync succeeds.
  2. ./gradlew help
    succeeds.
  3. ./gradlew build --dry-run
    succeeds.
迁移完成后，请验证以下内容：
  1. Gradle IDE同步成功。
  2. ./gradlew help
    执行成功。
  3. ./gradlew build --dry-run
    执行成功。

Troubleshooting

故障排除

Paparazzi v2.0.0-alpha04 and lower versions have issues with AGP 9. See references/paparazzi-gradle-9.md for details.
Paparazzi v2.0.0-alpha04及更低版本与AGP 9存在兼容问题。详情请查看references/paparazzi-gradle-9.md。