Ghi chú phát hành cho bản xem trước trình bổ trợ Android cho Gradle

Trang này chứa ghi chú phát hành cho các bản phát hành dùng thử của trình bổ trợ Android cho Gradle (AGP).

Trình bổ trợ Android cho Gradle 9.0

Trình bổ trợ Android cho Gradle 9.0 là một bản phát hành chính mới của AGP, đồng thời mang đến những thay đổi về API và hành vi.

Để cập nhật lên trình bổ trợ Android cho Gradle 9.0.0-alpha05, hãy sử dụng Trợ lý nâng cấp trình bổ trợ Android cho Gradle trong Android Studio Narwhal 4 Feature Drop | 2025.1.4.

Trợ lý nâng cấp AGP giúp duy trì các hành vi hiện có khi nâng cấp dự án của bạn (nếu thích hợp), cho phép bạn nâng cấp dự án để sử dụng AGP 9.0, ngay cả khi bạn chưa sẵn sàng áp dụng tất cả các giá trị mặc định mới trong AGP 9.0.

Khả năng tương thích

Cấp độ API Android tối đa mà trình bổ trợ Android cho Gradle 9.0.0-alpha05 hỗ trợ là cấp độ API 36.

Trình bổ trợ Android cho Gradle 9.0.0-alpha05 yêu cầu Gradle 9.0.0.

Các lớp DSL android hiện chỉ triển khai các giao diện công khai mới

Trong vài năm qua, chúng tôi đã giới thiệu các giao diện mới cho DSL và API của mình để kiểm soát tốt hơn những API nào là công khai. Các phiên bản AGP 7.x và 8.x vẫn dùng các loại DSL cũ (ví dụ: BaseExtension) cũng triển khai các giao diện công khai mới để duy trì khả năng tương thích khi công việc tiến triển trên các giao diện.

AGP 9.0 chỉ sử dụng các giao diện DSL mới của chúng tôi và các cách triển khai đã thay đổi thành các loại mới hoàn toàn bị ẩn. Thay đổi này cũng xoá quyền truy cập vào API biến thể cũ, không dùng nữa.

Để cập nhật lên AGP 9.0, bạn có thể cần làm những việc sau:

• Chuyển sang Kotlin tích hợp: Trình bổ trợ org.jetbrains.kotlin.android không tương thích với DSL mới.

• Chuyển các dự án KMP sang Trình bổ trợ thư viện Android cho Gradle cho KMP: Việc sử dụng trình bổ trợ org.jetbrains.kotlin.multiplatform trong cùng một dự án con Gradle như trình bổ trợ com.android.library và com.android.application không tương thích với DSL mới.

• Cập nhật tệp bản dựng: Mặc dù việc thay đổi giao diện nhằm mục đích giữ cho DSL giống nhau nhất có thể, nhưng có thể sẽ có một số thay đổi nhỏ.

• Cập nhật logic bản dựng tuỳ chỉnh để tham chiếu đến DSL và API mới: Thay thế mọi tham chiếu đến DSL nội bộ bằng các giao diện DSL công khai. Trong hầu hết các trường hợp, đây sẽ là một thay thế tương đương. Thay thế mọi hoạt động sử dụng applicationVariants và các API tương tự bằng API androidComponents mới. Điều này có thể phức tạp hơn vì API androidComponents được thiết kế để ổn định hơn nhằm duy trì khả năng tương thích của các trình bổ trợ lâu hơn. Hãy xem Công thức Gradle của chúng tôi để biết các ví dụ.

• Cập nhật trình bổ trợ bên thứ ba: Một số trình bổ trợ bên thứ ba có thể vẫn phụ thuộc vào các giao diện hoặc API không còn được hiển thị. Di chuyển sang các phiên bản của những trình bổ trợ tương thích với AGP 9.0.

Nếu bạn cập nhật lên AGP 9.0 và thấy thông báo lỗi sau, thì có nghĩa là dự án của bạn vẫn đang tham chiếu một số loại cũ:

java.lang.ClassCastException: class com.android.build.gradle.internal.dsl.ApplicationExtensionImpl$AgpDecorated_Decorated
cannot be cast to class com.android.build.gradle.BaseExtension

Nếu bị chặn bởi các trình bổ trợ không tương thích của bên thứ ba, bạn có thể chọn không sử dụng và khôi phục các phương thức triển khai cũ cho DSL, cũng như API biến thể cũ. Trong quá trình này, các giao diện mới cũng có sẵn và bạn vẫn có thể cập nhật logic bản dựng của riêng mình lên API mới. Để chọn không sử dụng, hãy thêm dòng này vào tệp gradle.properties:

android.newDsl=false

Bạn cũng có thể bắt đầu nâng cấp lên các API mới trước khi nâng cấp lên AGP 9.0. Các giao diện mới đã xuất hiện trong nhiều phiên bản AGP, vì vậy bạn có thể kết hợp giữa giao diện mới và cũ. Tài liệu tham khảo về API AGP cho biết giao diện API cho từng phiên bản AGP, cũng như thời điểm từng lớp, phương thức và trường được thêm vào.

Trong giai đoạn alpha 9.0, chúng tôi sẽ liên hệ với các tác giả trình bổ trợ để giúp họ điều chỉnh và phát hành các trình bổ trợ tương thích hoàn toàn với các chế độ mới, đồng thời cải thiện Trợ lý nâng cấp AGP trong Android Studio để hướng dẫn bạn trong quá trình di chuyển.

Nếu bạn nhận thấy DSL hoặc Variant API mới thiếu các chức năng hoặc tính năng, vui lòng gửi vấn đề càng sớm càng tốt.

Được tích hợp sẵn trong Kotlin

Trình bổ trợ Android cho Gradle 9.0 có tính năng hỗ trợ tích hợp để biên dịch Kotlin, thay thế cho trình bổ trợ Kotlin được áp dụng riêng. Điều này giúp đơn giản hoá quy trình tích hợp với AGP, tránh sử dụng các API không dùng nữa và cải thiện hiệu suất trong một số trường hợp.

Trình bổ trợ Android cho Gradle 9.0 có một phần phụ thuộc thời gian chạy trên trình bổ trợ Kotlin cho Gradle 2.2.10. Đây là phiên bản tối thiểu cần thiết để hỗ trợ Kotlin tích hợp.

Bạn có thể chọn không sử dụng Kotlin tích hợp bằng cách thiết lập android.builtInKotlin=false.

Nếu đã chọn không sử dụng Kotlin tích hợp và cũng cần dùng phiên bản cũ hơn của trình bổ trợ Kotlin cho Gradle, bạn có thể buộc hạ cấp:

buildscript {
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("2.0.0") } // or another version that you want to use
        }
    }
}

Thay đổi về hành vi

Trình bổ trợ Android cho Gradle 9.0 có những hành vi mới sau đây:

AGP 9.0 có các nội dung cập nhật cho chế độ cài đặt mặc định của các thuộc tính Gradle sau đây. Nhờ đó, bạn có thể chọn giữ nguyên hành vi của AGP 8.13 khi nâng cấp:

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

Các tính năng đã bị xoá

Trình bổ trợ Android cho Gradle 9.0 sẽ loại bỏ chức năng sau:

• Hỗ trợ ứng dụng Wear OS được nhúng
  AGP 9.0 loại bỏ tính năng hỗ trợ nhúng ứng dụng Wear OS. Tính năng này không còn được hỗ trợ trong Play nữa. Điều này bao gồm việc xoá các cấu hình wearApp và DSL AndroidSourceSet.wearAppConfigurationName. Hãy xem phần Phân phối cho Wear OS để biết cách xuất bản ứng dụng của bạn trên Wear OS.
• androidDependencies và sourceSets báo cáo nhiệm vụ

Đã thay đổi DSL

Trình bổ trợ Android cho Gradle 9.0 có những thay đổi DSL có thể gây lỗi sau đây:

• Đã xoá tham số hoá của CommonExtension.

  Bản thân thay đổi này chỉ là một thay đổi mang tính đột phá ở cấp nguồn để giúp tránh các thay đổi mang tính đột phá ở cấp nguồn trong tương lai, nhưng điều này cũng có nghĩa là các phương thức chặn cần chuyển từ CommonExtension sang ApplicationExtension, LibraryExension, DynamicFeatureExtension và TestExtension.

  Khi nâng cấp dự án lên AGP 9.0, hãy tái cấu trúc mã trình bổ trợ Gradle sử dụng các tham số hoặc phương thức khối đó. Ví dụ: trình bổ trợ sau đây được cập nhật để xoá tham số loại và không dựa vào các phương thức khối đã xoá:

  AGP 8.13

  val commonExtension: CommonExtension<*, *, *, *, *, *> =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig {
          minSdk {
              version = release(28)
          }
      }
  }
  

  AGP 9.0

  val commonExtension: CommonExtension =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig.apply {
          minSdk {
              version = release(28)
          }
      }
  }
  

  Đối với các trình bổ trợ nhắm đến một dải phiên bản AGP, việc sử dụng trực tiếp phương thức getter tương thích nhị phân với các phiên bản AGP thấp hơn 9.0.

Đã xoá DSL

Trình bổ trợ Android cho Gradle 9.0 sẽ xoá:

• AndroidComponentsExtension.finalizeDSl. Tính năng này được thay thế bằng finalizeDsl

• AndroidSourceSet.jni vì không hoạt động.

• AndroidSourceSet.wearAppConfigurationName, vì có liên quan đến việc xoá tính năng hỗ trợ ứng dụng Wear OS được nhúng.

• BuildType.isRenderscriptDebuggable vì không hoạt động.

• Component.transformClassesWith. Tính năng này được thay thế bằng Instrumentation.transformClassesWith

• Component.setAsmFramesComputationMode. Tính năng này được thay thế bằng Instrumentation.setAsmFramesComputationMode

• DependenciesInfoBuilder.includedInApk. Is is replaced by includeInApk

• DependenciesInfoBuilder.includedInBundle. Is is replaced by includeInBundle

• ComponentBuilder.enabled. Tính năng này được thay thế bằng ComponentBuilder.enable.

• DependencyVariantSelection. Nó được thay thế bằng DependencySelection, được hiển thị dưới dạng kotlin.android

• GeneratesApk.targetSdkVersion. Được thay thế bằng targetSdk

• Installation.installOptions(String). Thuộc tính này được thay thế bằng thuộc tính có thể thay đổi của Installation.installOptions.

• Variant.minSdkVersion. Được thay thế bằng minSdk

• Variant.maxSdkVersion. Được thay thế bằng maxSdk

• Variant.targetSdkVersion. Được thay thế bằng targetSdk

• VariantBuilder.targetSdk và targetSdkPreview, vì chúng không có ý nghĩa trong các thư viện. Thay vào đó, hãy sử dụng GeneratesApkBuilder.targetSdk hoặc GeneratesApkBuilder.targetSdkPreview.

• VariantOutput.enable. Được thay thế bằng enabled

• Khối PostProcessing thử nghiệm nhưng chưa bao giờ ổn định.

• ProductFlavor.setDimension, được thay thế bằng thuộc tính dimension

• LanguageSplitOptions, chỉ hữu ích cho Google Play Instant (đã ngừng hoạt động).

• Variant.unitTest vì không áp dụng cho trình bổ trợ com.android.test. unitTest có sẵn trên các kiểu phụ VariantBuilder mở rộng HasUnitTest.

• VariantBuilder.enableUnitTest vì không áp dụng cho trình bổ trợ com.android.test. enableUnitTest có sẵn trên các kiểu phụ VariantBuilder mở rộng HasUnitTestBuilder.

• VariantBuilder.unitTestEnabled sẽ bị xoá để thay thế bằng enableUnitTest có tên nhất quán hơn trên các kiểu phụ VariantBuilder mở rộng HasUnitTestBuilder.

Đã xoá các thuộc tính Gradle

Ban đầu, các thuộc tính Gradle sau đây được thêm vào để tắt các tính năng được bật theo mặc định trên toàn cầu.

Theo mặc định, các tính năng này đã bị tắt kể từ AGP 8.0 trở xuống. Chỉ bật các tính năng này trong những dự án phụ sử dụng chúng để tạo bản dựng hiệu quả hơn.

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

Các API đã bị xoá

Trình bổ trợ Android cho Gradle 9.0 sẽ xoá:

• Các API BaseExtension.registerTransform đã ngừng hoạt động và bị vô hiệu hoá, chỉ còn lại để cho phép biên dịch dựa trên phiên bản AGP mới nhất trong khi nhắm đến việc chạy trên AGP 4.2 trở xuống.

• FeaturePlugin và FeatureExtension đã ngừng hoạt động và bị vô hiệu hoá.

Các thuộc tính Gradle bắt buộc

AGP 9.0 sẽ phát sinh lỗi nếu bạn đặt các thuộc tính Gradle sau đây.

Trợ lý nâng cấp trình bổ trợ Android cho Gradle sẽ không nâng cấp các dự án lên AGP 9.0 sử dụng những thuộc tính này.