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

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

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

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

• ‫-repackageclasses [<optional-package-name>]: إعادة تجميع الفئات في حزمة واحدة لتقليل حجم التطبيق إذا لم تقدّم اسم الحزمة الاختياري، سيتم نقل الفئات إلى حزمة تلقائية بدون اسم. هذا هو الإعداد المقترَح للتطبيقات لأنّه يؤدي إلى إنشاء ملفات DEX أصغر حجمًا من خلال حذف بادئة الحزمة من أسماء الفئات.
• -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، ولكن قد يكون من المفيد الاحتفاظ بهذه السمات إذا كانت مطلوبة في حالات مثل الانعكاس. للحصول على قائمة بالسمات التي يمكنك تحديدها، اطّلِع على السمات التي يجب الاحتفاظ بها.

تحذير: يجب استخدام الخيارات -dontoptimize و-dontshrink و-dontobfuscate بشكل مؤقت فقط أثناء تصحيح الأخطاء أو التطوير. أزِل هذه الخيارات من إصدارات الإنتاج لأنّها تحدّ بشكل كبير من نطاق التحسينات.

إبقاء السمات

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

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

• عند الوصول إلى بنية الفئة الداخلية أو الخارجية باستخدام 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)، ويجب الاحتفاظ بها بشكل صريح فقط في التطبيقات التي تستخدم إصدارات أقدم من المكوّن الإضافي لنظام Gradle المتوافق مع Android.
RuntimeVisibleAnnotations	تخزِّن هذه السمة التعليقات التوضيحية التي يمكن رؤيتها في وقت التشغيل من خلال الانعكاس. عادةً، إذا تم استخدام التعليقات التوضيحية في وقت التشغيل، يكون هذا هو التعليق التوضيحي الوحيد من سمات *Annotation التي تحتاج إليها التطبيقات وفي قواعد مستخدمي المكتبة.
RuntimeVisibleParameterAnnotations	تخزِّن هذه السمة التعليقات التوضيحية التي تظهر في وقت التشغيل من خلال الانعكاس على مَعلمات إحدى الطرق.
RuntimeVisibleTypeAnnotations	تخزّن هذه السمة التعليقات التوضيحية التي تنطبق على استخدامات الأنواع بدلاً من التصريحات فقط. تظهر هذه السمة في وقت التشغيل.
Signature	تخزِّن هذه السمة توقيع نوع أكثر عمومية للفئات والطُرق والحقول، خاصةً عندما تستخدم الأنواع العامة (مثل List<String>).
SourceFile	يخزِّن هذا التصنيف اسم ملف المصدر (ملف .kt أو .java) الذي تم تجميع صف منه. يستخدمه مصحّحو الأخطاء بشكل أساسي لعرض أسطر رمز المصدر الأصلي عند تتبُّع رمز Java مجمَّع. ويساعد المطوّرين في تتبُّع التنفيذ وصولاً إلى الرمز البرمجي المكتوب. ملاحظة: يتم الاحتفاظ بهذه السمة تلقائيًا منذ الإصدار 8.2 من "مكوّن Android الإضافي في Gradle"، ولا يلزم الاحتفاظ بها بشكلٍ صريح إلا في التطبيقات التي تستخدم إصدارات أقدم من "مكوّن Android الإضافي في Gradle".

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

ملاحظة: يُنصح بالاحتفاظ بأقل عدد ممكن من السمات لأنّ كل سمة تحتفظ بها تحدّ من عملية تحسين شاملة.

ملاحظة: يتم التحكّم في السمات الإضافية التي تتضمّن معلومات تصحيح الأخطاء (مثل LocalVariableTable وLocalVariableTypeTable) من خلال تحديد ما إذا كان إصدار R8 في وضع الإصدار أو وضع تصحيح الأخطاء، ولا يؤثر تضمينها مع -keepattributes في ذلك.

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

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

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