Trình bổ trợ Android cho Gradle 7.0.0 (tháng 7 năm 2021)

Trình bổ trợ Android cho Gradle 7.0.0 là một bản phát hành chính có nhiều tính năng và điểm cải tiến mới.

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

Cần có JDK 11 để chạy AGP 7.0

Khi sử dụng trình bổ trợ Android cho Gradle 7.0 để xây dựng ứng dụng, giờ đây, bạn bắt buộc phải có JDK 11 để chạy Gradle. Android Studio Arctic Fox có sẵn JDK 11 và định cấu hình Gradle để sử dụng theo mặc định, tức là hầu hết người dùng Android Studio không cần phải thực hiện bất kỳ thay đổi nào về cấu hình cho dự án.

Nếu cần thiết lập phiên bản JDK mà AGP sử dụng trong Android Studio theo cách thủ công, bạn cần dùng JDK 11 trở lên.

Khi sử dụng AGP độc lập với Android Studio, hãy nâng cấp phiên bản JDK bằng cách đặt biến môi trường JAVA_HOME hoặc tuỳ chọn dòng lệnh -Dorg.gradle.java.home vào thư mục cài đặt JDK 11.

Xin lưu ý rằng Trình quản lý SDK và Trình quản lý thiết bị ảo Android trong gói Công cụ SDK không dùng nữa sẽ không hoạt động với JDK 11. Để tiếp tục sử dụng Trình quản lý SDK và Trình quản lý thiết bị ảo Android với AGP 7.0 trở lên, bạn cần chuyển sang phiên bản công cụ mới trong gói Công cụ dòng lệnh SDK Android hiện tại.

Variant API đã ổn định

Variant API mới hiện đã ổn định. Hãy xem các giao diện mới trong gói com.android.build.api.variant và các ví dụ trong dự án GitHub gradle-recipes. Trong Variant API mới, chúng tôi đã cung cấp một số tệp trung gian, gọi là cấu phần phần mềm, thông qua giao diện Artifacts (Cấu phần phần mềm). Bạn có thể lấy và tuỳ chỉnh các cấu phần phần mềm này, giống như tệp kê khai sáp nhập, một cách an toàn bằng cách sử dụng trình bổ trợ và mã của bên thứ ba.

Chúng tôi sẽ tiếp tục mở rộng Variant API bằng cách bổ sung các chức năng mới và tăng cường số lượng cấu phần phần mềm trung gian mà chúng tôi cung cấp cho hoạt động tuỳ chỉnh.

Thay đổi về hành vi của trình tìm lỗi mã nguồn

Phần này mô tả nhiều thay đổi về hành vi của công cụ tìm lỗi mã nguồn trong trình bổ trợ Android cho Gradle 7.0.0.

Cải thiện trình tìm lỗi mã nguồn cho phần phụ thuộc của thư viện

Quá trình chạy trình tìm lỗi mã nguồn bằng checkDependencies = true hiện đã nhanh hơn trước. Đối với các dự án Android chứa một ứng dụng có các phần phụ thuộc của thư viện, bạn nên đặt checkDependencies thành true như trình bày bên dưới và chạy công cụ tìm lỗi mã nguồn thông qua ./gradlew :app:lint. Thao tác này sẽ phân tích song song tất cả các mô-đun phần phụ thuộc và tạo một báo cáo duy nhất bao gồm các vấn đề từ ứng dụng cũng như tất cả các phần phụ thuộc của ứng dụng đó.

// build.gradle
android {
  ...
  lintOptions {
    checkDependencies true
  }
}

// build.gradle.kts
android {
  ...
  lint {
    isCheckDependencies = true
  }
}

Giờ đây tác vụ của trình tìm lỗi mã nguồn có thể được CẬP NHẬT

Nếu các nguồn và tài nguyên của một mô-đun không thay đổi, thì tác vụ phân tích tìm lỗi mã nguồn cho mô-đun đó không cần phải chạy lại. Khi điều này xảy ra, quá trình thực thi tác vụ sẽ xuất hiện dưới dạng "UP-TO-DATE" (cập nhật) trong đầu ra của Gradle. Với thay đổi này, khi chạy công cụ tìm lỗi mã nguồn trên một mô-đun ứng dụng có checkDependencies = true, chỉ những mô-đun đã thay đổi mới cần chạy bản phân tích. Do đó, trình tìm lỗi mã nguồn có thể chạy nhanh hơn nữa.

Tác vụ báo cáo tìm lỗi mã nguồn cũng không cần chạy nếu dữ liệu đầu vào của nhiệm vụ đó không thay đổi. Một vấn đề đã biết liên quan là không có kết quả văn bản tìm lỗi mã nguồn nào được in ra stdout khi tác vụ tìm lỗi mã nguồn là UP-TO-DATE (vấn đề #191897708).

Chạy trình tìm lỗi mã nguồn trên mô-đun có tính năng động

AGP không còn hỗ trợ việc chạy trình tìm lỗi mã nguồn qua các mô-đun tính năng động. Việc chạy công cụ tìm lỗi mã nguồn qua mô-đun ứng dụng tương ứng sẽ chạy công cụ tìm lỗi mã nguồn trên các mô-đun tính năng động của mô-đun đó và đưa tất cả vấn đề vào báo cáo tìm lỗi mã nguồn của ứng dụng. Một vấn đề đã biết liên quan là khi chạy trình tìm lỗi mã nguồn với checkDependencies = true qua một mô-đun ứng dụng, các phần phụ thuộc của thư viện có tính năng động sẽ không được kiểm tra trừ phi đó cũng là phần phụ thuộc của ứng dụng (vấn đề #191977888).

Chỉ chạy trình tìm lỗi mã nguồn trên biến thể mặc định

Hiện tại, việc chạy ./gradlew :app:lint chỉ chạy trình tìm lỗi mã nguồn cho biến thể mặc định. Trong các phiên bản AGP trước đây, thuộc tính này sẽ chạy công cụ tìm lỗi mã nguồn cho tất cả biến thể.

Thiếu cảnh báo lớp trong trình rút gọn mã R8

R8 xử lý nhất quán và chính xác hơn các lớp bị thiếu cũng như tuỳ chọn -dontwarn. Do đó, bạn nên bắt đầu đánh giá các cảnh báo về lớp bị thiếu mà R8 đưa ra.

Khi R8 gặp một tham chiếu lớp không được xác định trong ứng dụng hoặc một trong các phần phụ thuộc của ứng dụng, R8 sẽ phát ra cảnh báo xuất hiện trong đầu ra của bản dựng. Ví dụ:

R8: Missing class: java.lang.instrument.ClassFileTransformer

Cảnh báo này có nghĩa là bạn không thể tìm thấy định nghĩa lớp java.lang.instrument.ClassFileTransformer khi phân tích mã của ứng dụng. Mặc dù điều này thường có nghĩa là đã xảy ra lỗi, nhưng bạn có thể bỏ qua cảnh báo này. Có 2 lý do phổ biến khiến bạn bỏ qua cảnh báo:

1. Các thư viện nhắm mục tiêu JVM và lớp bị thiếu đều thuộc loại thư viện JVM (như trong ví dụ trên).

2. Một trong các phần phụ thuộc sử dụng API chỉ có thời gian biên dịch.

Bạn có thể bỏ qua cảnh báo về lớp bị thiếu bằng cách thêm quy tắc -dontwarn vào tệp proguard-rules.pro. Ví dụ:

-dontwarn java.lang.instrument.ClassFileTransformer

Để thuận tiện, AGP sẽ tạo một tệp chứa tất cả các quy tắc có thể bị thiếu, ghi các quy tắc đó vào một đường dẫn tệp như sau: app/build/outputs/mapping/release/missing_rules.txt. Thêm các quy tắc vào tệp proguard-rules.pro để bỏ qua cảnh báo.

Trong AGP 7.0, các thông báo về lớp bị thiếu sẽ xuất hiện dưới dạng cảnh báo và bạn có thể chuyển các thông báo đó thành lỗi bằng cách đặt android.r8.failOnMissingClasses = true trong gradle.properties. Trong AGP 8.0, các cảnh báo này sẽ trở thành lỗi phá vỡ bản dựng. Bạn có thể giữ nguyên hành vi AGP 7.0 bằng cách thêm tuỳ chọn -ignorewarnings vào tệp proguard-rules.pro. Tuy nhiên, bạn không nên làm như vậy.

Xoá bộ nhớ đệm bản dựng trình bổ trợ Android cho Gradle

Bộ nhớ đệm bản dựng AGP đã bị xoá trong AGP 4.1. Ra mắt trong AGP 2.3 trước đây để bổ sung cho bộ nhớ đệm bản dựng Gradle, bộ nhớ đệm bản dựng AGP đã được thay thế hoàn toàn bằng bộ nhớ đệm bản dựng Gradle trong AGP 4.1. Thay đổi này không ảnh hưởng đến thời gian xây dựng.

Trong AGP 7.0, thuộc tính android.enableBuildCache, thuộc tính android.buildCacheDir và tác vụ cleanBuildCache đã bị xoá.

Dùng mã nguồn Java 11 trong dự án

Giờ đây, bạn có thể biên dịch đến mã nguồn Java 11 trong dự án của ứng dụng, cho phép bạn sử dụng các tính năng ngôn ngữ mới hơn như phương thức giao diện riêng tư, toán tử kim cương cho các lớp ẩn danh và cú pháp biến cục bộ cho tham số lambda.

Để bật tính năng này, hãy đặt compileOptions thành phiên bản Java mong muốn và đặt compileSdkVersion thành 30 trở lên:

// build.gradle
android {
  compileSdkVersion 30
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_11
    targetCompatibility JavaVersion.VERSION_11
  }
  // For Kotlin projects
  kotlinOptions {
    jvmTarget = "11"
  }
}

// build.gradle.kts
android {
  compileSdkVersion(30)
  compileOptions {
    sourceCompatibility(JavaVersion.VERSION_11)
    targetCompatibility(JavaVersion.VERSION_11)
  }
  kotlinOptions {
    jvmTarget = "11"
  }
}

Xoá cấu hình phần phụ thuộc

Trong AGP 7.0, các cấu hình sau (hoặc phạm vi phần phụ thuộc) đã bị xoá:

• compile
  Tuỳ thuộc vào trường hợp sử dụng, phương thức này đã được thay thế bằng api hoặc implementation.
  Cũng áp dụng cho các biến thể *Compile (*Biên dịch), ví dụ: debugCompile.
• provided
  Tính năng này đã được thay thế bằng compileOnly.
  Cũng áp dụng cho các biến thể *Provided (*Được cung cấp), ví dụ: releaseProvided.
• apk
  Tính năng này đã được thay thế bằng runtimeOnly.
• publish
  Tính năng này đã được thay thế bằng runtimeOnly.

Trợ lý nâng cấp AGP sẽ tự động di chuyển dự án sang cấu hình mới trong hầu hết trường hợp.

Classpath thay đổi khi biên dịch bằng trình bổ trợ Android cho Gradle

Nếu bạn đang biên dịch bằng trình bổ trợ Android cho Gradle, thì classpath biên dịch có thể thay đổi. Vì AGP hiện sử dụng nội bộ các cấu hình api/implementation, nên một số cấu phần phần mềm có thể bị xoá khỏi classpath biên dịch. Nếu bạn phụ thuộc vào một phần phụ thuộc AGP tại thời điểm biên dịch, hãy nhớ thêm phần phụ thuộc đó dưới dạng một phần phụ thuộc rõ ràng.

Không hỗ trợ bổ sung thư viện gốc trong thư mục tài nguyên Java

Trước đây, bạn có thể thêm thư viện gốc vào thư mục tài nguyên Java và đăng ký thư mục đó bằng android.sourceSets.main.resources.srcDirs để thư viện gốc sẽ được trích xuất và thêm vào tệp APK cuối cùng. Kể từ AGP 7.0, định dạng này không được hỗ trợ và các thư viện gốc trong thư mục tài nguyên Java sẽ bị bỏ qua. Thay vào đó, hãy sử dụng phương thức DSL dành cho thư viện gốc android.sourceSets.main.jniLibs.srcDirs. Để biết thêm thông tin, hãy xem cách định cấu hình các nhóm tài nguyên.

Vấn đề đã biết

Phần này mô tả các vấn đề đã biết tồn tại trong trình bổ trợ Android cho Gradle 7.0.0.

Tình trạng không tương thích với trình bổ trợ đa nền tảng Kotlin 1.4.x

Trình bổ trợ Android cho Gradle 7.0.0 tương thích với trình bổ trợ đa nền tảng Kotlin phiên bản 1.5.0 trở lên. Các dự án sử dụng tính năng hỗ trợ Đa nền tảng Kotlin cần cập nhật lên Kotlin 1.5.0 để sử dụng được trình bổ trợ Android cho Gradle 7.0.0. Để khắc phục, bạn có thể hạ cấp trình bổ trợ Android cho Gradle xuống 4.2.x, mặc dù bạn không nên thực hiện việc này.

Để biết thêm thông tin, hãy xem nội dung KT-43944.

Thiếu đầu ra trình tìm lỗi mã nguồn

Không có đầu ra văn bản tìm lỗi mã nguồn nào được in ra stdout khi tác vụ tìm lỗi mã nguồn đã được cập nhật (vấn đề #191897708). Để biết thêm ngữ cảnh, hãy xem Thay đổi về hành vi đối với trình tìm lỗi mã nguồn. Vấn đề này sẽ được khắc phục trong trình bổ trợ Android cho Gradle 7.1.

Trình tìm lỗi mã nguồn không kiểm tra toàn bộ phần phụ thuộc của thư viện có tính năng động

Khi chạy trình tìm lỗi mã nguồn với checkDependencies = true qua một mô-đun ứng dụng, phần phụ thuộc của thư viện có tính năng động sẽ không được kiểm tra trừ phi đó cũng là phần phụ thuộc của ứng dụng (vấn đề #191977888). Để khắc phục vấn đề này, bạn có thể chạy tác vụ tìm lỗi mã nguồn trên các thư viện đó. Để biết thêm ngữ cảnh, hãy xem bài viết Thay đổi về hành vi đối với trình tìm lỗi mã nguồn.