Nâng cấp AGP

Android Gradle Plugin (AGP) là plugin chính để build Android apps. Google thường xuyên phát hành phiên bản mới với tính năng mới, cải thiện hiệu suất và sửa lỗi. Bài viết này hướng dẫn cách nâng cấp AGP một cách an toàn.

Quy trình nâng cấp AGP

flowchart LR
    A["1️⃣ Kiểm tra<br/>phiên bản"] --> B["2️⃣ Đọc<br/>Release Notes"]
    B --> C["3️⃣ Kiểm tra<br/>Compatibility"]
    C --> D["4️⃣ Sử dụng<br/>AGP Upgrade<br/>Assistant"]
    D --> E["5️⃣ Cập nhật<br/>Dependencies"]
    E --> F["6️⃣ Test &<br/>Verify"]

    style A fill:#e3f2fd
    style B fill:#e8f5e9
    style C fill:#fff3e0
    style D fill:#fce4ec
    style E fill:#f3e5f5
    style F fill:#c8e6c9

Bước 1: Kiểm tra phiên bản hiện tại

Xem phiên bản trong libs.versions.toml

gradle/libs.versions.toml

[versions]
agp = "8.5.0"  # Phiên bản hiện tại

Hoặc trong build.gradle.kts

// build.gradle.kts (Project-level)
plugins {
    id("com.android.application") version "8.5.0" apply false
}

---

Bước 2: Kiểm tra Release Notes

Trước khi nâng cấp, luôn đọc Release Notes để biết:

• Breaking changes
• Deprecated APIs
• Yêu cầu phiên bản Gradle mới
• Tính năng mới

Links quan trọng:

• AGP Release Notes
• AGP API Changes
• AGP Upgrade Notes

---

Bước 3: Kiểm tra Compatibility

AGP và Gradle Compatibility

AGP Version	Minimum Gradle	Recommended Gradle
8.7	8.9	8.10+
8.6	8.7	8.9+
8.5	8.7	8.9+
8.4	8.6	8.7+
8.3	8.4	8.6+
8.2	8.2	8.5+
8.1	8.0	8.4+
8.0	8.0	8.3+

AGP và Android Studio Compatibility

AGP Version	Minimum Android Studio
8.7	Ladybug (2024.2.1)
8.6	Koala (2024.1.1)
8.5	Jellyfish (2023.3.1)
8.4	Iguana (2023.2.1)
8.3	Hedgehog (2023.1.1)

Kotlin và AGP Compatibility

AGP Version	Minimum Kotlin
8.7+	1.9.20
8.5+	1.9.0
8.0+	1.8.0

⚠️ Quan trọng: Luôn kiểm tra compatibility matrix chính thức trước khi upgrade.

---

Bước 4: Sử dụng AGP Upgrade Assistant

Android Studio có công cụ để tự động upgrade AGP với các thay đổi cần thiết.

Mở AGP Upgrade Assistant

1. Tools → AGP Upgrade Assistant
2. Chọn phiên bản AGP muốn upgrade
3. Click Run selected steps
4. Review các thay đổi

Các thay đổi tự động

AGP Upgrade Assistant có thể:

• Cập nhật AGP version trong build files
• Cập nhật Gradle wrapper version
• Migrate deprecated APIs
• Thêm/xóa properties trong gradle.properties

---

Bước 5: Cập nhật thủ công

Nếu không dùng Assistant hoặc cần control nhiều hơn:

5.1. Cập nhật Gradle Wrapper

gradle/wrapper/gradle-wrapper.properties

distributionUrl=https\://services.gradle.org/distributions/gradle-8.10-bin.zip

Hoặc dùng command:

./gradlew wrapper --gradle-version=8.10

5.2. Cập nhật AGP trong Version Catalog

gradle/libs.versions.toml

[versions]
agp = "8.7.2"  # Cập nhật version

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
android-library = { id = "com.android.library", version.ref = "agp" }

5.3. Cập nhật Kotlin (nếu cần)

[versions]
kotlin = "2.0.21"  # Cập nhật nếu cần

[plugins]
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }

5.4. Sync và Build

./gradlew --refresh-dependencies
./gradlew build

---

Xử lý Breaking Changes phổ biến

AGP 8.0 Breaking Changes

1. Default Java 17

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
    }
}

2. BuildConfig disabled by default

android {
    buildFeatures {
        buildConfig = true  // Bật nếu cần dùng
    }
}

3. Non-transitive R classes by default

gradle.properties

# Đã mặc định true từ AGP 8.0
android.nonTransitiveRClass=true

AGP 8.5+ Changes

Namespace required

android {
    namespace = "com.example.myapp"  // Bắt buộc
}

Compile SDK 34+ support

android {
    compileSdk = 35
}

AGP 8.7+ Changes

Kotlin 1.9.20+ required

[versions]
kotlin = "2.0.21"  # Cập nhật từ 1.9.x

---

Migration Script Example

Tạo script để automate upgrade process:

upgrade-agp.sh

#!/bin/bash
NEW_AGP_VERSION="8.7.2"
NEW_GRADLE_VERSION="8.10"
NEW_KOTLIN_VERSION="2.0.21"

echo "Upgrading AGP to $NEW_AGP_VERSION..."

# Update gradle wrapper
./gradlew wrapper --gradle-version=$NEW_GRADLE_VERSION

# Update libs.versions.toml (using sed)
sed -i '' "s/^agp = \".*\"/agp = \"$NEW_AGP_VERSION\"/" gradle/libs.versions.toml
sed -i '' "s/^kotlin = \".*\"/kotlin = \"$NEW_KOTLIN_VERSION\"/" gradle/libs.versions.toml

echo "Syncing project..."
./gradlew --refresh-dependencies

echo "Building project..."
./gradlew build

echo "Upgrade complete!"

---

Troubleshooting thường gặp

1. Gradle version mismatch

Error: Minimum supported Gradle version is X.X. Current version is Y.Y.

Giải pháp: Cập nhật gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.10-bin.zip

2. Kotlin version incompatible

Error: Module was compiled with an incompatible version of Kotlin

Giải pháp: Cập nhật Kotlin version trong libs.versions.toml

3. Deprecated API warnings

warning: API 'XXX' is deprecated

Giải pháp:

1. Check AGP release notes cho migration guide
2. Sử dụng AGP Upgrade Assistant
3. Search documentation cho API mới

4. BuildConfig not generated

Unresolved reference: BuildConfig

Giải pháp: Bật BuildConfig explicitly:

android {
    buildFeatures {
        buildConfig = true
    }
}

5. JVM target mismatch

Error: 'compileDebugJavaWithJavac' task (current target is 17) and
'compileDebugKotlin' task (current target is 11) jvm target compatibility

Giải pháp: Đồng bộ JVM target:

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
    }
}

---

Best Practices cho Upgrade

1. Upgrade thường xuyên

Upgrade định kỳ (mỗi minor version) dễ hơn upgrade nhảy nhiều versions.

2. Đọc Release Notes trước

Hiểu rõ breaking changes và deprecated APIs.

3. Test kỹ sau upgrade

# Build tất cả variants
./gradlew build

# Chạy tests
./gradlew test
./gradlew connectedAndroidTest

# Check lint
./gradlew lint

4. Commit changes riêng

git add -A
git commit -m "chore: upgrade AGP to 8.7.2, Gradle to 8.10"

5. Sử dụng feature branches

git checkout -b upgrade/agp-8.7
# ... thực hiện upgrade ...
git push origin upgrade/agp-8.7
# Tạo PR để review

---

Rollback nếu cần

Nếu upgrade gặp vấn đề nghiêm trọng:

# Revert changes
git checkout -- .

# Hoặc hard reset
git reset --hard HEAD~1

# Clear Gradle caches
./gradlew clean
rm -rf ~/.gradle/caches

---

📚 Tham khảo

• AGP Release Notes
• AGP Upgrade Assistant
• Gradle Version Compatibility
• Kotlin Compatibility