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

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

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

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

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

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

-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 تخزّن هذه السمة التعليقات التوضيحية التي تنطبق على استخدامات الأنواع بدلاً من التصريحات فقط. لا تظهر هذه السمة في وقت التشغيل.

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