إضافة خيارات عامة

توفّر الأداة R8 خيارات عامة تعدّل تحسينات R8 في جميع أنحاء التطبيق أو تؤثّر في كل قاعدة إبقاء. يتم الاحتفاظ بهذه الخيارات في ملف proguard-rules.pro، بالإضافة إلى قواعد الاحتفاظ بالبيانات. تتيح بعض هذه الخيارات العامة ضبط إعدادات تحسين إضافية، بينما توقف خيارات أخرى جوانب معيّنة من التحسين.

تقبل R8 أيضًا بعض الخيارات القديمة التي تم نقلها من ProGuard، ولكنها تتجاهلها. لمزيد من المعلومات، يُرجى الاطّلاع على إزالة خيارات ProGuard القديمة.

خيارات عامة للتحسين الإضافي

تتيح الخيارات العامة التالية تحسينًا إضافيًا:

  • ‫-repackageclasses [<optional-package-name>]: إعادة تجميع الفئات في حزمة واحدة لتقليل حجم التطبيق إذا لم تقدّم اسم الحزمة الاختياري، سيتم نقل الفئات إلى الحزمة التي ليس لها اسم (الحزمة التلقائية). هذا هو الإعداد المقترَح للتطبيقات لأنّه يؤدي إلى إنشاء ملفات DEX أصغر حجمًا من خلال حذف بادئة الحزمة من أسماء الفئات. منذ الإصدار 9.1 من المكوّن الإضافي لنظام Gradle المتوافق مع Android، أصبح هذا هو الإعداد التلقائي للتطبيقات. لإيقاف هذا التحسين، استخدِم -dontrepackage.
  • ‫-allowaccessmodification: يتيح هذا الخيار لبرنامج R8 تغيير مستوى ظهور الفئات والحقول والطُرق (عادةً ما يتم توسيعه) لإجراء تحسينات أكثر شمولاً. يتم تفعيلها عند استخدام proguard-android-optimize.txt. منذ الإصدار 8.2 من المكوّن الإضافي لنظام Gradle المتوافق مع Android، أصبح هذا الإعداد هو الإعداد التلقائي في حال تفعيل التحسين الكامل باستخدام R8.

  • ‫-processkotlinnullchecks [level]: يتيح هذا الخيار لبرنامج R8 تغيير عمليات التحقّق من قيمة Kotlin Intrinsics إلى إزالة رسالة الخطأ فقط أو إزالة عملية التحقّق من القيمة الفارغة بشكل كامل.

    تتضمّن قيم level، مرتّبة من الأضعف إلى الأقوى، التأثير التالي:

    • لا يؤدي keep إلى تغيير عمليات التحقّق.
    • تعيد remove_message كتابة كل طلب إجراء للتحقّق إلى استدعاء getClass() في الوسيطة الأولى للاستدعاء (مع الاحتفاظ بشكل فعّال بالتحقّق من القيمة الفارغة، ولكن بدون أي رسالة).
    • تؤدي remove إلى إزالة عمليات التحقّق بالكامل.

    يستخدم R8 remove_message تلقائيًا. ويتم تجاهل أي مواصفات -processkotlinnullchecks. في حال تحديدها عدة مرات، سيتم استخدام القيمة الأقوى.

    يتوفّر -processkotlinnullchecks من الإصدار 9.0.0 من Android Gradle Plugin.

في ما يلي مثال على عملية ضبط تم فيها تفعيل التحسين الإضافي:

-repackageclasses
-allowaccessmodification

خيارات عامة للحدّ من التحسين

تتيح لك الخيارات العامة التالية إيقاف جوانب معيّنة من تحسين التطبيق، وهي مفيدة عند تحسين قواعد الاحتفاظ أو تفعيل R8 لأول مرة.

  • ‫-dontoptimize: يمنع تحسين الرمز البرمجي، مثل تضمين الدوال البرمجية. يمكن استخدام هذا الخيار أثناء التطوير، ولكن لا يجب استخدامه في الإصدارات المخصّصة للإنتاج.
  • ‫-dontshrink: يمنع إزالة الرموز غير المرتبطة وتحسين الرموز. يمكن استخدام هذا الخيار أثناء التطوير، ولكن لا يجب استخدامه في إصدارات الإنتاج.
  • ‫-dontobfuscate: يمنع اختصار أسماء الفئات والطُرق. قد يكون من المفيد بشكل خاص إيقاف التشويش أثناء تصحيح الأخطاء لتسهيل قراءة عمليات تتبُّع تسلسل استدعاء الدوال البرمجية. يمكن استخدام هذا الخيار أثناء التطوير، ولكن لا يجب استخدامه في إصدارات الإنتاج.
  • ‫-keepattributes <attributes>: تقبل قائمة قيم مفصولة بفاصلة تتضمّن السمات التي يجب الحفاظ عليها. في حال عدم استخدام proguard-android-optimize.txt التلقائي، يزيل R8 جميع السمات، بما في ذلك RuntimeVisibleAnnotations وSignature، ولكن قد يكون من المفيد الاحتفاظ بهذه السمات إذا كانت مطلوبة في حالات مثل الانعكاس. للاطّلاع على قائمة بالسمات التي يمكنك تحديدها، راجِع الاحتفاظ بالسمات.

الاحتفاظ بالسمات

السمات هي معلومات إضافية مرتبطة بأجزاء مختلفة من الرمز البرمجي. تخزّن السمات معلومات مثل التعليقات التوضيحية والتوقيعات العامة من الرمز البرمجي.

تتطلّب بعض العمليات الانعكاسية الاحتفاظ بسمات معيّنة لتنفيذها بنجاح. على سبيل المثال:

  • عند الوصول إلى بنية الفئة الداخلية أو الخارجية باستخدام getEnclosingMethod() أو getDeclaredClasses()، يجب توفُّر السمتَين EnclosingMethod وInnerClasses.
  • عند الوصول إلى التواقيع العامة باستخدام getTypeParameters()، يجب تضمين السمة Signature.

  • عند الوصول إلى التعليقات التوضيحية باستخدام getAnnotation()، يجب توفير السمة RuntimeVisibleAnnotations.

السمات المطلوبة بشكل شائع

عند استخدام ملف Proguard التلقائي (proguard-android-optimize.txt أو proguard-android.txt)، يحتفظ المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP) بالسمات التالية. يُرجى العِلم أنّ بعض هذه السمات تتطلّب إصدارات أحدث من "مكوّن Android الإضافي لبرنامج Gradle":

السمة الوصف
AnnotationDefault تتوفّر هذه السمة في أنواع التعليقات التوضيحية نفسها وتخزِّن القيمة التلقائية لعنصر التعليق التوضيحي.

ملاحظة: يتم الاحتفاظ بهذه السمة تلقائيًا منذ الإصدار 7.1 من "مكوّن Android الإضافي في Gradle"، ولا يلزم الاحتفاظ بها بشكل صريح إلا في التطبيقات التي تستخدم إصدارات أقدم من "مكوّن Android الإضافي في Gradle".
EnclosingMethod تظهر هذه السمة في الفئات الداخلية التي ليست فئات محلية أو مجهولة الاسم. تحدّد هذه السمة الطريقة أو أداة التهيئة التي تحتوي على الفئة مباشرةً.
InnerClasses تسجّل هذه السمة معلومات عن الفئات المتداخلة (الفئات الداخلية والفئات المتداخلة الثابتة والفئات المحلية والفئات المجهولة الهوية) المحدّدة ضمن فئة أخرى.
LineNumberTable تربط هذه السمة تعليمات رمز البايت بأرقام الأسطر المقابلة لها في ملف المصدر الأصلي.

ملاحظة: يتم الاحتفاظ بهذه السمة تلقائيًا منذ الإصدار 8.6 من المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP)، ولا يلزم الاحتفاظ بها بشكل صريح إلا في التطبيقات التي تستخدم إصدارات أقدم من المكوّن الإضافي.
RuntimeVisibleAnnotations تخزِّن هذه السمة التعليقات التوضيحية التي يمكن رؤيتها في وقت التشغيل من خلال الانعكاس.

في العادة، إذا تم استخدام التعليقات التوضيحية في وقت التشغيل، يكون هذا هو التعليق التوضيحي الوحيد من سمات *Annotation الذي تحتاجه التطبيقات وفي قواعد مستهلكي المكتبة.
RuntimeVisibleParameterAnnotations تخزِّن هذه السمة التعليقات التوضيحية التي تكون مرئية في وقت التشغيل من خلال الانعكاس على مَعلمات إحدى الطرق.
RuntimeVisibleTypeAnnotations تخزّن هذه السمة التعليقات التوضيحية التي تنطبق على استخدامات الأنواع بدلاً من التصريحات فقط. تظهر هذه السمة في وقت التشغيل.
Signature تخزِّن هذه السمة توقيع نوع أكثر عمومية للفئات والطرق والحقول، لا سيما عندما تستخدم الأنواع العامة (مثل List<String>).
SourceFile يخزِّن هذا التصنيف اسم ملف المصدر (ملف .kt أو .java) الذي تم تجميع فئة منه. يستخدمه مصحّحو الأخطاء بشكل أساسي لعرض أسطر رمز المصدر الأصلي عند التنقّل بين أسطر رمز Java المجمَّع. ويساعد المطوّرين في تتبُّع التنفيذ وصولاً إلى الرمز البرمجي المكتوب.

ملاحظة: يتم الاحتفاظ بهذه السمة تلقائيًا منذ الإصدار 8.2 من "مكوّن Android الإضافي في Gradle"، ويجب الاحتفاظ بها بشكلٍ صريح في التطبيقات التي تستخدم إصدارات أقدم من "مكوّن Android الإضافي في Gradle".

بالنسبة إلى التطبيقات التي تستخدم proguard-android-optimize.txt، تكون قواعد الحفاظ على البيانات التي يحدّدها AGP كافية في معظم السيناريوهات. ومع ذلك، إذا كنت تكتب رمزًا برمجيًا لمكتبة، عليك تحديد جميع السمات التي تتطلّبها مكتبتك في قواعد الاحتفاظ الخاصة بالمستهلك، حتى إذا تم تحديدها في هذه القائمة. يضمن ذلك أن تكون مكتبتك قوية في حال قرّر المطوّرون عدم تضمين proguard-android-optimize.txt.

سمات إضافية يجب الاحتفاظ بها

يمكنك تحديد سمات إضافية ليتم الاحتفاظ بها، ولكنّها غير مطلوبة في معظم حالات الوصول إلى JNI أو حالات الانعكاس. ومع ذلك، قد يظل يتم استخدام بعض هذه الملفات بشكل متكرر أثناء تحسين المكتبات.

السمة الوصف
MethodParameters توفّر هذه السمة معلومات عن مَعلمات إحدى الطرق، وتحديدًا أسماؤها وعلامات الوصول إليها.
Exceptions تسرد هذه السمة الاستثناءات التي تم التحقّق منها والتي تم الإعلان عن أنّ إحدى الطرق ستطرحها.

لا تُستخدَم هذه السمة عادةً للتطبيقات. بالنسبة إلى مؤلفي المكتبات، لا يتم استخدامها عادةً في قواعد الاحتفاظ بالمستهلكين، ولكن يتم استخدامها غالبًا عند إنشاء المكتبات. لمزيد من التفاصيل حول تحسين المكتبات، يُرجى الاطّلاع على التحسين لمؤلفي المكتبات.
RuntimeInvisibleAnnotations تخزّن هذه السمة التعليقات التوضيحية التي لا تظهر مع الانعكاس في وقت التشغيل على فئة أو حقل أو طريقة.

يجب ألّا يحتفظ مطوّرو التطبيقات بهذه السمة. بالنسبة إلى مطوّري المكتبات، لا تكون هذه السمة ذات صلة بقواعد الاحتفاظ بالمستهلكين، ولكن يتم استخدامها غالبًا عند إنشاء المكتبات. لمزيد من التفاصيل حول تحسين المكتبات، يُرجى الاطّلاع على التحسين لمؤلفي المكتبات.
RuntimeInvisibleParameterAnnotations تخزِّن هذه السمة التعليقات التوضيحية التي لا تظهر مع الانعكاس في وقت التشغيل على مَعلمات إحدى الطرق.

يجب ألّا يحتفظ مطوّرو التطبيقات بهذه السمة. بالنسبة إلى مطوّري المكتبات، لا تكون هذه السمة ذات صلة بقواعد الاحتفاظ بالمستهلكين، ولكن يتم استخدامها غالبًا عند إنشاء المكتبات. لمزيد من التفاصيل حول تحسين المكتبات، يُرجى الاطّلاع على التحسين لمؤلفي المكتبات.
RuntimeInvisibleTypeAnnotations تخزّن هذه السمة التعليقات التوضيحية التي تنطبق على استخدامات الأنواع بدلاً من التصريحات فقط. لا تظهر هذه السمة في وقت التشغيل.

يجب ألّا يحتفظ مطوّرو التطبيقات بهذه السمة. بالنسبة إلى مطوّري المكتبات، لا تكون هذه السمة ذات صلة بقواعد الاحتفاظ بالمستهلكين، ولكن يتم استخدامها غالبًا عند إنشاء المكتبات. لمزيد من التفاصيل حول تحسين المكتبات، يُرجى الاطّلاع على التحسين لمؤلفي المكتبات.

إزالة خيارات ProGuard القديمة

يقبل R8 بعض الخيارات التي كان لها تأثير في ProGuard فقط، ولكنه يتجاهلها. وغالبًا ما تبقى هذه الخيارات في عمليات الإعداد التي تم نقلها من ProGuard أو نسخها من مشاريع قديمة. وبما أنّها لا تؤثر في ناتج R8، عليك إزالتها من ملف proguard-rules.pro لتسهيل فهم إعداداتك وصيانتها.

يتجاهل R8 الخيارات التالية بدون عرض تحذير:

  • -adaptkotlinmetadata
  • -android
  • -dontpreverify
  • -dontskipnonpubliclibraryclasses
  • -dontskipnonpubliclibraryclassmembers
  • -dontusemixedcaseclassnames
  • -forceprocessing
  • -mergeinterfacesaggressively
  • -optimizationpasses
  • -optimizations
  • -overloadaggressively
  • -target
  • -verbose

يتجاهل R8 الخيارات التالية ويُبلغ عن تحذير أثناء عملية الإنشاء:

لا يتوافق R8 مع -skipnonpubliclibraryclasses، ويُبلغ عن حدوث خطأ إذا كان الإعداد يتضمّن.