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 lớn bao gồm nhiều tính năng và điểm cải thiệ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ài JDK 11 để chạy được Gradle. Android Studio Arctic Fox có sẵn JDK 11 và định cấu hình Gradle để sử dụng theo mặc định, nghĩa là hầu hết người dùng Android Studio không cần phải thay đổi 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 sử 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 thiết lập tuỳ chọn 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 không phù hợp 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 mới của công cụ 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 cùng 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. Chúng tôi đã cung cấp một số tệp trung gian là một phần của Variant API mới, 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 (tương tự như tệp kê khai sáp nhập) 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 trình 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 giờ đây đã nhanh hơn trước. Đối với các dự án Android bao gồm một ứng dụng có phần phụ thuộc vào thư viện, bạn nên thiết lập checkDependencies thành true như bên dưới rồi chạy trình tìm lỗi mã nguồn qua ./gradlew :app:lint. Thao tác này sẽ phân tích song song tất 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 và tất cả phần phụ thuộc.

// 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 trình 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, thao tác 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 sự thay đổi này, khi chạy trình tìm lỗi mã nguồn (lint) 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 liên kết không thay đổi. Một vấn đề đã biết liên quan là khi tác vụ tìm lỗi mã nguồn xuất hiện dưới dạng UP-TO-DATE, không có kết quả văn bản tìm lỗi mã nguồn được in ra stdout (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 trình tìm lỗi mã nguồn qua mô-đun ứng dụng tương ứng sẽ chạy trình tìm lỗi mã nguồn trên các mô-đun tính năng động của ứng dụng và đưa tất cả sự cố vào báo cáo tìm lỗi mã nguồn của ứng dụng. Có 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, 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 trình tìm lỗi mã nguồn trên 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 đối với 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 phải 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 đó, công cụ này 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ó hai 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 kiểu thư viện JVM (như 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ả quy tắc có thể bị thiếu, ghi các quy tắc này 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 thiết lập 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 bổ sung tuỳ chọn -ignorewarnings vào tệp proguard-rules.pro. Tuy nhiên, bạn không nên thực hiện thao tác nà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 tạo bản dựng.

Trong AGP 7.0, thuộc tính android.enableBuildCache, thuộc tính android.buildCacheDir và thao tác 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 ứ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 các 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, những cấu hình sau (hoặc phạm vi phụ thuộc) đã bị xoá:

• compile
  Tuỳ vào trường hợp sử dụng, thành phần này đã được thay thế bằng api hoặc implementation.
  Ngoài ra, còn á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.
  Ngoài ra, còn á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 cần phần phụ thuộc AGP tại thời điểm biên dịch, hãy nhớ bổ sung phần phụ thuộc trên làm 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 sao cho 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òn đượ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 nội dung cách định cấu hình nhóm tài nguyên.

Vấn đề đã biết

Phần này mô tả các vấn đề đã biết còn 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 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

Khi tác vụ tìm lỗi mã nguồn đã cập nhật, không có đầu ra văn bản tìm lỗi mã nguồn nào được in tại stdout (vấn đề #191897708). Để biết thêm thông tin, hãy xem nội dung 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 thông tin, hãy xem phần Thay đổi về hành vi đối với trình tìm lỗi mã nguồn.