گزینه های جهانی را اضافه کنید

R8 گزینه‌های جهانی را ارائه می‌کند که یا بهینه‌سازی‌های R8 را در سراسر برنامه تغییر می‌دهند یا بر هر قانون حفظ تأثیر می‌گذارند. این گزینه ها در فایل proguard-rules.pro همراه با قوانین حفظ نگهداری می شوند. تعدادی از این گزینه‌های کلی بهینه‌سازی اضافی را پیکربندی می‌کنند، در حالی که برخی دیگر جنبه‌های خاصی از بهینه‌سازی را خاموش می‌کنند.

گزینه های جهانی برای بهینه سازی اضافی

گزینه های جهانی زیر بهینه سازی اضافی را فعال می کنند:

• -repackageclasses [<optional-package-name>] : برای کاهش بیشتر اندازه برنامه، کلاس‌ها را در یک بسته مشخص شده مجدداً بسته‌بندی می‌کند. اگر نام بسته اختیاری را وارد نکنید، کلاس ها به بسته خالی و پیش فرض منتقل می شوند. این یک تنظیم توصیه شده برای برنامه ها است.
• -allowaccessmodification : به R8 اجازه می‌دهد تا دید کلاس‌ها، فیلدها و روش‌ها را تغییر دهد (معمولاً گسترده‌تر شود) تا بهینه‌سازی‌های گسترده‌تری انجام دهد. وقتی proguard-android-optimize.txt استفاده می شود فعال می شود. از آنجایی که Android Gradle Plugin (AGP) 8.2 است، اگر از R8 در حالت کامل استفاده می کنید، این پیکربندی پیش فرض است.

هشدار: اگر نویسنده کتابخانه هستید، هرگز نباید هیچ یک از گزینه های جهانی را برای بهینه سازی های اضافی در قوانین حفظ مصرف کننده اضافه کنید. برای جزئیات بیشتر در مورد بهینه سازی کتابخانه ها، به بهینه سازی برای نویسندگان کتابخانه مراجعه کنید.

در زیر نمونه ای از پیکربندی با بهینه سازی اضافی فعال شده است:

-repackageclasses
-allowaccessmodification

گزینه های جهانی برای محدود کردن بهینه سازی

گزینه‌های کلی زیر به شما امکان می‌دهند جنبه‌های خاصی از بهینه‌سازی برنامه را خاموش کنید، و زمانی که قوانین حفظ خود را اصلاح می‌کنید یا برای اولین بار R8 را روشن می‌کنید، مفید هستند.

• -dontoptimize : از بهینه‌سازی کد جلوگیری می‌کند، به‌عنوان مثال درون‌سازی روش. این گزینه را می توان در طول توسعه استفاده کرد اما نباید در ساخت های تولیدی استفاده شود.
• -dontshrink : از حذف کدهای ارجاع نشده و بهینه سازی کد جلوگیری می کند. این گزینه را می توان در طول توسعه استفاده کرد اما نباید در ساخت های تولیدی استفاده شود.
• -dontobfuscate : از کوتاه شدن نام کلاس ها و متدها جلوگیری می کند. خاموش کردن مبهم‌سازی در حین اشکال‌زدایی می‌تواند مفید باشد تا ردپای پشته‌ها راحت‌تر خوانده شوند. این گزینه را می توان در طول توسعه استفاده کرد اما نباید در ساخت های تولیدی استفاده شود.
• -keepattributes <attributes> : فهرستی از ویژگی‌های جدا شده با کاما را می‌پذیرد که باید حفظ شوند. اگر از پیش‌فرض proguard-android-optimize.txt استفاده نمی‌کنید ، R8 تمام ویژگی‌ها از جمله RuntimeVisibleAnnotations و Signature را حذف می‌کند، اما حفظ این ویژگی‌ها در صورت نیاز در مواردی مانند بازتاب می‌تواند مفید باشد. برای فهرستی از ویژگی‌هایی که می‌توانید مشخص کنید، ویژگی‌های Keep را ببینید.

هشدار: در حین اشکال زدایی یا توسعه فقط باید از گزینه های -dontoptimize ، -dontshrink و -dontobfuscate به طور موقت استفاده کنید. این گزینه‌ها را در ساخت‌های تولیدی حذف کنید، زیرا به طور قابل توجهی دامنه بهینه‌سازی را محدود می‌کنند.

صفات را حفظ کنید

ویژگی ها قطعات اضافی اطلاعاتی هستند که به قسمت های مختلف کد شما متصل می شوند. ویژگی ها اطلاعاتی مانند حاشیه نویسی و امضاهای عمومی را از کد شما ذخیره می کنند.

برخی از عملیات بازتابی برای اجرای موفقیت آمیز نیاز به ویژگی های خاصی دارند. به عنوان مثال:

• هنگام دسترسی به ساختار کلاس داخلی یا خارجی با استفاده از getEnclosingMethod() یا getDeclaredClasses() ، ویژگی های EnclosingMethod و InnerClasses مورد نیاز است.
• هنگام دسترسی به امضاهای عمومی با استفاده از getTypeParameters() ، ویژگی Signature مورد نیاز است.

• هنگام دسترسی به حاشیه نویسی با استفاده از getAnnotation() ، ویژگی RuntimeVisibleAnnotations مورد نیاز است.

  توجه: هنگام کار بر روی یک قانون حفظ برای حاشیه نویسی، مطمئن شوید که حاشیه نویسی و کلاس هایی که حاشیه نویسی روی آنها اعمال می شود را حفظ کنید.

ویژگی های معمولا مورد نیاز

هنگام استفاده از فایل پیش‌فرض Proguard ( proguard-android-optimize.txt یا proguard-android.txt )، افزونه Android Gradle (AGP) ویژگی‌های زیر را حفظ می‌کند. توجه داشته باشید که برخی از این ویژگی ها به نسخه های جدیدتر AGP نیاز دارند:

صفت	توضیحات
AnnotationDefault	این ویژگی در خود انواع حاشیه‌نویسی یافت می‌شود و مقدار پیش‌فرض یک عنصر حاشیه‌نویسی را ذخیره می‌کند. توجه: این ویژگی به‌طور پیش‌فرض از AGP 7.1 حفظ می‌شود و فقط باید صریحاً در برنامه‌هایی که از نسخه‌های قبلی AGP استفاده می‌کنند نگهداری شود.
EnclosingMethod	این ویژگی در کلاس های داخلی وجود دارد که کلاس های محلی یا ناشناس نیستند. متد یا مقداردهی اولیه را که بلافاصله حاوی کلاس است را شناسایی می کند.
InnerClasses	این ویژگی اطلاعات مربوط به کلاس‌های تودرتو (کلاس‌های داخلی، کلاس‌های تودرتو ایستا، کلاس‌های محلی و کلاس‌های ناشناس) تعریف شده در کلاس دیگر را ثبت می‌کند.
LineNumberTable	این ویژگی دستورالعمل های بایت کد را به شماره خطوط مربوطه آنها در فایل منبع اصلی نگاشت می کند. توجه: این ویژگی به‌طور پیش‌فرض از پلاگین Gradle Android (AGP) 8.6 حفظ می‌شود و فقط باید صریحاً در برنامه‌هایی که از نسخه‌های قبلی AGP استفاده می‌کنند نگهداری شود.
RuntimeVisibleAnnotations	این ویژگی یادداشت هایی را ذخیره می کند که در زمان اجرا با بازتاب قابل مشاهده هستند. به طور معمول، اگر حاشیه نویسی در زمان اجرا استفاده می شود، این تنها حاشیه نویسی از ویژگی های *Annotation است که توسط برنامه ها و قوانین مصرف کننده کتابخانه مورد نیاز است.
RuntimeVisibleParameterAnnotations	این ویژگی حاشیه نویسی هایی را ذخیره می کند که در زمان اجرا با بازتاب پارامترهای یک متد قابل مشاهده هستند.
RuntimeVisibleTypeAnnotations	این ویژگی حاشیه نویسی هایی را ذخیره می کند که به جای اعلان ها، برای استفاده های نوع اعمال می شود. این ویژگی در زمان اجرا قابل مشاهده است.
Signature	این ویژگی یک نوع امضای عمومی‌تر را برای کلاس‌ها، متدها و فیلدها ذخیره می‌کند، به‌ویژه زمانی که از ژنریک استفاده می‌کنند (مانند List<String> ).
SourceFile	این ویژگی نام فایل منبع (فایل .kt یا .java ) را که یک کلاس از آن کامپایل شده است را ذخیره می کند. در درجه اول توسط دیباگرها برای نمایش خطوط کد منبع اصلی هنگام عبور از کد جاوا کامپایل شده استفاده می شود. این به توسعه دهندگان کمک می کند تا اجرا را به کد نوشته شده خود ردیابی کنند. توجه: این ویژگی به‌طور پیش‌فرض از AGP 8.2 حفظ می‌شود و فقط باید صریحاً در برنامه‌هایی که از نسخه‌های قبلی AGP استفاده می‌کنند نگهداری شود.

برای برنامه هایی که از proguard-android-optimize.txt استفاده می کنند، قوانین حفظ تعریف شده توسط AGP در اکثر سناریوها کافی است. با این حال، اگر در حال نوشتن کد برای یک کتابخانه هستید، باید تمام ویژگی های مورد نیاز کتابخانه خود را در قوانین نگهداری مصرف کننده آن مشخص کنید، حتی اگر در این لیست تعریف شده باشند. اگر توسعه‌دهندگان تصمیم بگیرند که proguard-android-optimize.txt را اضافه نکنند، این اطمینان حاصل می‌کند که کتابخانه شما قوی است.

نکته: توصیه می شود تا حد امکان کمترین ویژگی را حفظ کنید زیرا هر ویژگی که نگه می دارید یک بهینه سازی جهانی را محدود می کند.

توجه: ویژگی‌های اضافی با اطلاعات اشکال‌زدایی (مانند LocalVariableTable و LocalVariableTypeTable ) توسط این که ساخت R8 در حالت انتشار یا اشکال‌زدایی است کنترل می‌شوند- از جمله آنها با -keepattributes هیچ تأثیری ندارد.

ویژگی های اضافی نگهداری

می‌توانید ویژگی‌های اضافی را برای نگهداری مشخص کنید، اما برای اکثریت قریب به اتفاق سناریوهای دسترسی بازتابی یا JNI مورد نیاز نیستند. با این حال، برخی از این موارد ممکن است اغلب در حین بهینه سازی کتابخانه ها استفاده شوند.

صفت	توضیحات
MethodParameters	این ویژگی اطلاعاتی در مورد پارامترهای یک متد، به ویژه نام و پرچم دسترسی آنها را ارائه می دهد.
Exceptions	این ویژگی استثناهای علامت‌گذاری شده‌ای را که یک متد برای پرتاب کردن آنها اعلام شده است فهرست می‌کند. این ویژگی معمولاً برای برنامه ها استفاده نمی شود. برای نویسندگان کتابخانه، معمولاً در قوانین نگهداری مصرف کننده استفاده نمی شود، اما اغلب هنگام ساخت کتابخانه ها استفاده می شود. برای جزئیات در مورد بهینه سازی کتابخانه ها، به بهینه سازی برای نویسندگان کتابخانه مراجعه کنید.
RuntimeInvisibleAnnotations	این ویژگی حاشیه نویسی هایی را ذخیره می کند که با بازتاب در زمان اجرا روی یک کلاس، فیلد یا متد قابل مشاهده نیستند. توسعه دهندگان برنامه نباید این ویژگی را حفظ کنند. برای نویسندگان کتابخانه، این ویژگی در قوانین نگهداری مصرف کننده مرتبط نیست، اما اغلب هنگام ساخت کتابخانه استفاده می شود. برای جزئیات در مورد بهینه سازی کتابخانه ها، به بهینه سازی برای نویسندگان کتابخانه مراجعه کنید.
RuntimeInvisibleParameterAnnotations	این ویژگی حاشیه نویسی هایی را ذخیره می کند که با بازتاب در زمان اجرا روی پارامترهای یک متد قابل مشاهده نیستند. توسعه دهندگان برنامه نباید این ویژگی را حفظ کنند. برای نویسندگان کتابخانه، این ویژگی در قوانین نگهداری مصرف کننده مرتبط نیست، اما اغلب هنگام ساخت کتابخانه استفاده می شود. برای جزئیات در مورد بهینه سازی کتابخانه ها، به بهینه سازی برای نویسندگان کتابخانه مراجعه کنید.
RuntimeInvisibleTypeAnnotations	این ویژگی حاشیه نویسی هایی را ذخیره می کند که به جای اعلان ها، برای استفاده های نوع اعمال می شود. این ویژگی در زمان اجرا قابل مشاهده نیست. توسعه دهندگان برنامه نباید این ویژگی را حفظ کنند. برای نویسندگان کتابخانه، این ویژگی در قوانین نگهداری مصرف کننده مرتبط نیست، اما اغلب هنگام ساخت کتابخانه استفاده می شود. برای جزئیات در مورد بهینه سازی کتابخانه ها، به بهینه سازی برای نویسندگان کتابخانه مراجعه کنید.