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

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

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

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

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

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

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

-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 من "مكوّن Android الإضافي في Gradle" (AGP)، ولا يلزم الاحتفاظ بها بشكل صريح إلا في التطبيقات التي تستخدم إصدارات أقدم من "مكوّن Android الإضافي في Gradle".
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.

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

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

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

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

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