وقتی بهینه‌سازی برنامه را با تنظیمات پیش‌فرض فعال می‌کنید، R8 بهینه‌سازی‌های گسترده‌ای را برای به‌حداکثر رساندن مزایای عملکرد شما انجام می‌دهد. R8 تغییرات اساسی در کد ایجاد می‌کند، ازجمله تغییر نام، جابه‌جایی، و حذف کلاس‌ها، فیلدها، و روش‌ها. اگر متوجه شدید که این اصلاحات باعث بروز خطا می‌شود، باید مشخص کنید که R8 نباید کدام بخش‌های کد را با تعریف کردن آن‌ها در قوانین نگهداری اصلاح کند.
سناریوهای رایجی که به قوانین نگهداری نیاز دارند
R8 همه تماس‌های مستقیم را در کد شما شناسایی و حفظ می‌کند. بااین‌حال، R8 نمی‌تواند استفاده‌های غیرمستقیم از کد را ببیند، که می‌تواند باعث شود کدی را که برنامه‌تان نیاز دارد بردارد و درنتیجه برنامه ازکار بیفتد. از قوانین keep استفاده کنید تا به R8 بگویید چنین کدهایی را که به‌طور غیرمستقیم استفاده می‌شوند حفظ کند. چند موقعیت رایج که احتمالاً در آن‌ها به قوانین نگهداری نیاز دارید به شرح زیر است:
- دسترسی به کد ازطریق بازتاب: R8 نمی‌تواند تشخیص دهد که چه زمانی به کلاس‌ها، فیلدها، یا
روش‌ها ازطریق بازتاب دسترسی پیدا شده است. برای مثال، R8 نمی‌تواند روشی را که بااستفاده از نامش با
Class.getDeclaredMethod()جستجو شده است یا گزارمانی را که باClass.getAnnotation()بازیابی شده است شناسایی کند. در این موارد، R8 ممکن است نام این روش‌ها و حاشیه‌نویسی‌ها را تغییر دهد یا آن‌ها را به‌طور کامل حذف کند، که منجر بهClassNotFoundExceptionیاNoSuchMethodExceptionدر زمان اجرا می‌شود. - کد فراخوانده‌شده از «میانای بومی جاوا» (JNI): وقتی کد بومی (C یا C++) روش Java یا Kotlin را فرا می‌خواند، یا کد Java یا Kotlin کد C++ را با JNI فرا می‌خواند، فراخوانی براساس جستجوی رشته‌ای پویا برای نام روش است. R8 نمی‌تواند فراخوانی روش مبتنی بر رشته پویا را ببیند، بنابراین بهینه‌سازی‌های آن ممکن است کد شما را خراب کند.
این فهرست کاملی از سناریوهایی نیست که به قوانین نگهداری نیاز دارند، اما این سناریوها اکثر مواردی را که ممکن است به قوانین نگهداری نیاز داشته باشید پوشش می‌دهند.
اگر کد خودتان از انعکاس استفاده می‌کند یا از JNI فراخوانی می‌شود، می‌توانید آن کد را با حاشیه‌نویسی‌های Jetpack Keep حاشیه‌نویسی کنید و نیازی به نوشتن دستی قوانین نگهداری نداشته باشید. افزونه Gradle آن قوانین حفظ را از حاشیه‌نویسی‌ها در زمان ساخت تولید می‌کند.
نحوه افزودن قوانین نگهداری به برنامه
پیکربندی قوانین نگهداری شما به نسخه AGP که استفاده می‌کنید بستگی دارد.
برنامه‌های بزرگ‌تر معمولاً در چندین واحد کتابخانه کد دارند. در چنین مواردی، اغلب بهتر است قوانین نگهداری را در کنار کدی که در واحد کتابخانه خاص به آن اعمال می‌شود قرار دهید. تفاوت مهم در حفظ قوانین نگهداری برای کتابخانه‌ها در نحوه اعلام این قوانین در فایل build.gradle.kts (یا build.gradle) ماژول کتابخانه شما نهفته است. برای کسب اطلاعات بیشتر، به بهینه‌سازی برای نویسندگان کتابخانه مراجعه کنید.
برای AGP نسخه ۹.۳ و بالاتر
قوانینتان را به فایلی با پسوند .keep در
src/<variant>/keepRules دایرکتوری اضافه کنید. برای مثال،
src/main/keepRules/custom-rules.keep. توجه داشته باشید که استفاده از DSL به‌روزشده برای AGP نسخه ۹.۳ و بالاتر، هم بهینه‌سازی کد و هم بهینه‌سازی منبع را فعال می‌کند و نیازی ندارد که فایل قوانین حفظ پیش‌فرض Android (proguard-android-optimize.txt) را به‌طور صریح تعریف کنید، زیرا به‌طور پیش‌فرض گنجانده شده است، مگراینکه به‌طور صریح حذف شده باشد.
کاتلین
android {
buildTypes {
release {
optimization {
enable = true // Enables code and resource optimizations.
}
}
}
}
شیک
android {
buildTypes {
release {
optimization {
enable = true // Enables code and resource optimizations.
}
}
}
}
حذف قوانین نگهداری پلاتفرم پیش‌فرض Android (پیشرفته)
AGP مجموعه‌ای از قوانین پیش‌فرض پلاتفرم Android را ارائه می‌دهد. برای حذف این قوانین از
پیکربندی پروژه‌تان و مدیریت همه قوانین نگهداری توسط خودتان،
optimization.keepRules.includeDefault را روی false تنظیم کنید.
کاتلین
android {
buildTypes {
release {
optimization {
enable = true // Enables code and resource optimizations.
keepRules {
includeDefault = false // The file with optimization
// rules for the Android platform is included by
// default. To omit this file, set this option to false.
}
}
}
}
}
شیک
android {
buildTypes {
release {
optimization {
enable = true // Enables code and resource optimizations.
keepRules {
includeDefault = false // The file with optimization
// rules for the Android platform is included by
// default. To omit this file, set this option to false.
}
}
}
}
}
DSL قدیمی برای نسخه‌های AGP پایین‌تر از ۹.۳
قوانینتان را به فایل proguard-rules.pro واقع در دایرکتوری ریشه واحد برنامه اضافه کنید—ممکن است فایل ازقبل آنجا باشد، اما اگر نیست، آن را ایجاد کنید. برای اعمال کردن
قوانین در فایل، باید فایل را در فایل
build.gradle.kts (یا build.gradle) سطح واحدتان تعریف کنید.
به‌طور پیش‌فرض، فایل ساخت شما شامل فایل proguard-android-optimize.txt
نیز می‌شود. این فایل شامل قوانینی است که برای اکثر پروژه‌های Android لازم است، بنابراین
باید اجازه دهید در فایل ساخت باقی بماند. این فایل براساس فایل proguard-common.txt است و محتوای آن را هم‌رسانی می‌کند.
DSL قدیمی (Kotlin)
android {
buildTypes {
release {
isMinifyEnabled = true
isShrinkResources = true
proguardFiles(
// Default file with default optimization rules.
getDefaultProguardFile("proguard-android-optimize.txt"),
...
)
}
}
}
DSL قدیمی (Groovy)
android {
buildTypes {
release {
minifyEnabled = true
shrinkResources = true
// Default file with default optimization rules.
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt')
...
}
}
}
افزودن قانون نگهداری
وقتی قانون حفظ اضافه می‌کنید، می‌توانید گزینه‌های سراسری را اضافه کنید و همچنین قانون حفظ خودتان را تعریف کنید.
گزینه‌های سراسری: گزینه‌های سراسری دستورالعمل‌های کلی هستند که بر نحوه عملکرد R8 در کل پایگاه کد شما تأثیر می‌گذارند. برای کسب اطلاعات بیشتر، گزینه‌های جهانی را ببینید.
نگه داشتن قوانین: قوانین نگه داشتن باید با دقت طراحی شوند تا مطمئن شوید که بین به حداکثر رساندن بهینه‌سازی کد بدون شکستن ناخواسته برنامه خود، تعادل درستی برقرار کرده‌اید. برای آشنایی با نحوه نوشتن قوانین نگه داشتن، به افزودن قوانین نگه داشتن مراجعه کنید.
حفظ قوانین برای نویسندگان کتابخانه
پس‌از آشنایی با گزینه‌های سراسری و نحو قوانین نگهداری، برای جزئیات بیشتر به بهینه‌سازی برای نویسندگان کتابخانه مراجعه کنید.