Thêm các lựa chọn chung

R8 cung cấp các lựa chọn chung để sửa đổi các hoạt động tối ưu hoá của R8 trong toàn bộ ứng dụng hoặc ảnh hưởng đến mọi quy tắc giữ lại. Các lựa chọn này được duy trì trong tệp proguard-rules.pro, cùng với các quy tắc giữ lại. Một số lựa chọn trong số này sẽ định cấu hình chế độ tối ưu hoá bổ sung, trong khi những lựa chọn khác sẽ tắt một số khía cạnh của chế độ tối ưu hoá.

Các lựa chọn chung để tối ưu hoá thêm

Các lựa chọn chung sau đây cho phép tối ưu hoá thêm:

  • -repackageclasses [<optional-package-name>]: Đóng gói lại các lớp vào một gói duy nhất, được chỉ định để giảm thêm kích thước ứng dụng. Nếu bạn không cung cấp tên gói không bắt buộc, các lớp sẽ được chuyển vào gói mặc định trống. Đây là chế độ cài đặt được đề xuất cho các ứng dụng.
  • -allowaccessmodification: Cho phép R8 thay đổi (thường là mở rộng) khả năng hiển thị của các lớp, trường và phương thức để thực hiện các hoạt động tối ưu hoá rộng rãi hơn. Được bật khi bạn sử dụng proguard-android-optimize.txt. Kể từ Trình bổ trợ Android cho Gradle (AGP) 8.2, đây là cấu hình mặc định nếu bạn sử dụng R8 ở chế độ đầy đủ.

Sau đây là ví dụ về cấu hình có bật tính năng tối ưu hoá bổ sung:

-repackageclasses
-allowaccessmodification

Các lựa chọn chung để giới hạn việc tối ưu hoá

Các lựa chọn chung sau đây cho phép bạn tắt một số khía cạnh của hoạt động tối ưu hoá ứng dụng và rất hữu ích khi bạn tinh chỉnh các quy tắc giữ lại hoặc bật R8 lần đầu tiên.

  • -dontoptimize: Ngăn chặn việc tối ưu hoá mã, chẳng hạn như phương thức nội tuyến. Bạn có thể sử dụng lựa chọn này trong quá trình phát triển nhưng không nên sử dụng trong các bản dựng phát hành công khai.
  • -dontshrink: Ngăn chặn việc xoá mã không được tham chiếu và tối ưu hoá mã. Bạn có thể sử dụng lựa chọn này trong quá trình phát triển nhưng không nên dùng trong các bản dựng phát hành công khai.
  • -dontobfuscate: Ngăn việc rút ngắn tên của các lớp và phương thức. Việc tắt tính năng làm rối mã nguồn có thể đặc biệt hữu ích trong quá trình gỡ lỗi để dễ dàng đọc các dấu vết ngăn xếp. Bạn có thể sử dụng lựa chọn này trong quá trình phát triển nhưng không nên sử dụng trong các bản dựng phát hành chính thức.
  • -keepattributes <attributes>: Chấp nhận danh sách các thuộc tính được phân tách bằng dấu phẩy cần được giữ lại. Nếu bạn không sử dụng proguard-android-optimize.txt mặc định, R8 sẽ loại bỏ tất cả các thuộc tính, bao gồm cả RuntimeVisibleAnnotations và Signature. Tuy nhiên, bạn nên giữ lại các thuộc tính này nếu cần trong các trường hợp như phản chiếu. Để biết danh sách các thuộc tính mà bạn có thể chỉ định, hãy xem phần Giữ lại thuộc tính.

Giữ lại các thuộc tính

Thuộc tính là những phần thông tin bổ sung được đính kèm vào các phần khác nhau trong mã của bạn. Các thuộc tính lưu trữ thông tin như chú thích và chữ ký chung từ mã của bạn.

Một số thao tác phản chiếu yêu cầu bạn phải giữ lại các thuộc tính cụ thể để thực thi thành công. Ví dụ:

  • Khi truy cập vào cấu trúc lớp bên trong hoặc bên ngoài bằng getEnclosingMethod() hoặc getDeclaredClasses(), bạn cần có các thuộc tính EnclosingMethod và InnerClasses.
  • Khi truy cập vào chữ ký chung bằng getTypeParameters(), bạn cần có thuộc tính Signature.

  • Khi truy cập vào chú giải bằng getAnnotation(), bạn cần có thuộc tính RuntimeVisibleAnnotations.

Các thuộc tính thường bắt buộc

Khi sử dụng tệp Proguard mặc định (proguard-android-optimize.txt hoặc proguard-android.txt), trình bổ trợ Android cho Gradle (AGP) sẽ giữ lại các thuộc tính sau. Xin lưu ý rằng một số thuộc tính này yêu cầu phiên bản AGP mới hơn:

Thuộc tính Mô tả
AnnotationDefault Thuộc tính này nằm trên chính các loại chú thích và lưu trữ giá trị mặc định cho một phần tử chú thích.

Lưu ý: Thuộc tính này được giữ theo mặc định kể từ AGP 7.1 và chỉ cần được giữ một cách rõ ràng trong các ứng dụng sử dụng phiên bản AGP cũ hơn.
EnclosingMethod Thuộc tính này có trong các lớp bên trong không phải là lớp cục bộ hoặc lớp ẩn danh. Nó xác định phương thức hoặc trình khởi tạo chứa ngay lớp.
InnerClasses Thuộc tính này ghi lại thông tin về các lớp lồng nhau (lớp bên trong, lớp lồng nhau tĩnh, lớp cục bộ và lớp ẩn danh) được xác định trong một lớp khác.
LineNumberTable Thuộc tính này ánh xạ các chỉ dẫn mã byte với số dòng tương ứng trong tệp nguồn ban đầu.

Lưu ý: Thuộc tính này được giữ theo mặc định kể từ Trình bổ trợ Android cho Gradle (AGP) 8.6 và chỉ cần được giữ một cách rõ ràng trong các ứng dụng sử dụng các phiên bản AGP cũ hơn.
RuntimeVisibleAnnotations Thuộc tính này lưu trữ các chú thích có thể nhìn thấy trong thời gian chạy bằng cách phản chiếu.

Thông thường, nếu chú thích được dùng trong thời gian chạy, thì đây là chú thích duy nhất trong số các thuộc tính *Annotation mà ứng dụng cần và trong các quy tắc của người dùng thư viện.
RuntimeVisibleParameterAnnotations Thuộc tính này lưu trữ các chú thích có thể nhìn thấy trong thời gian chạy bằng cách phản ánh các tham số của một phương thức.
RuntimeVisibleTypeAnnotations Thuộc tính này lưu trữ các chú thích áp dụng cho việc sử dụng kiểu thay vì chỉ khai báo. Thuộc tính này hiển thị trong thời gian chạy.
Signature Thuộc tính này lưu trữ chữ ký kiểu chung chung hơn cho các lớp, phương thức và trường, đặc biệt là khi chúng sử dụng các thành phần chung (chẳng hạn như List<String>).
SourceFile Thuộc tính này lưu trữ tên của tệp nguồn (tệp .kt hoặc .java) mà từ đó một lớp được biên dịch. Trình gỡ lỗi chủ yếu dùng thông tin này để hiển thị các dòng mã nguồn ban đầu khi từng bước thực hiện mã Java đã biên dịch. Điều này giúp nhà phát triển theo dõi quá trình thực thi trở lại mã mà họ đã viết.

Lưu ý: Thuộc tính này được giữ theo mặc định kể từ AGP 8.2 và chỉ cần được giữ rõ ràng trong các ứng dụng sử dụng các phiên bản AGP cũ hơn.

Đối với các ứng dụng sử dụng proguard-android-optimize.txt, các quy tắc giữ lại do AGP xác định là đủ trong hầu hết các trường hợp. Tuy nhiên, nếu đang viết mã cho một thư viện, bạn nên chỉ định tất cả các thuộc tính mà thư viện của bạn yêu cầu trong các quy tắc giữ lại người dùng, ngay cả khi các thuộc tính đó được xác định trong danh sách này. Điều này đảm bảo thư viện của bạn hoạt động ổn định nếu nhà phát triển quyết định không thêm proguard-android-optimize.txt.

Các thuộc tính bổ sung cần giữ lại

Bạn có thể chỉ định các thuộc tính bổ sung cần giữ lại, tuy nhiên, bạn không cần các thuộc tính này cho phần lớn các trường hợp truy cập phản chiếu hoặc JNI. Tuy nhiên, một số trong số này vẫn có thể thường xuyên được sử dụng trong khi tối ưu hoá các thư viện.

Thuộc tính Mô tả
MethodParameters Thuộc tính này cung cấp thông tin về các tham số của một phương thức, cụ thể là tên và cờ truy cập của phương thức đó.
Exceptions Thuộc tính này liệt kê các ngoại lệ đã kiểm tra mà một phương thức được khai báo để ném.

Thuộc tính này thường không được dùng cho ứng dụng. Đối với các tác giả thư viện, thường thì bạn không dùng quy tắc giữ lại này trong các quy tắc giữ lại của người dùng, nhưng thường dùng khi tạo thư viện. Để biết thông tin chi tiết về cách tối ưu hoá thư viện, hãy xem phần Tối ưu hoá cho tác giả thư viện.
RuntimeInvisibleAnnotations Thuộc tính này lưu trữ các chú thích không hiển thị bằng cơ chế phản chiếu tại thời gian chạy trên một lớp, trường hoặc phương thức.

Nhà phát triển ứng dụng không nên giữ lại thuộc tính này. Đối với tác giả thư viện, thuộc tính này không liên quan đến các quy tắc giữ lại người dùng, nhưng thường được dùng khi tạo thư viện. Để biết thông tin chi tiết về cách tối ưu hoá thư viện, hãy xem phần Tối ưu hoá cho tác giả thư viện.
RuntimeInvisibleParameterAnnotations Thuộc tính này lưu trữ các chú thích không hiển thị khi phản chiếu trong thời gian chạy trên các tham số của một phương thức.

Nhà phát triển ứng dụng không nên giữ lại thuộc tính này. Đối với tác giả thư viện, thuộc tính này không liên quan đến các quy tắc giữ lại người dùng, nhưng thường được dùng khi tạo thư viện. Để biết thông tin chi tiết về cách tối ưu hoá thư viện, hãy xem phần Tối ưu hoá cho tác giả thư viện.
RuntimeInvisibleTypeAnnotations Thuộc tính này lưu trữ các chú thích áp dụng cho việc sử dụng kiểu thay vì chỉ khai báo. Thuộc tính này không xuất hiện trong thời gian chạy.

Nhà phát triển ứng dụng không nên giữ lại thuộc tính này. Đối với tác giả thư viện, thuộc tính này không liên quan đến các quy tắc giữ lại người dùng, nhưng thường được dùng khi tạo thư viện. Để biết thông tin chi tiết về cách tối ưu hoá thư viện, hãy xem phần Tối ưu hoá cho tác giả thư viện.