الإصدار 7.0.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android (يوليو 2021)

الإصدار 7.0.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android هو إصدار رئيسي يتضمّن مجموعة متنوّعة من الميزات والتحسينات الجديدة.

التوافق

يجب توفُّر JDK 11 لتشغيل الإصدار 7.0 من "المكوّن الإضافي لنظام Gradle المتوافق مع Android"

عند استخدام الإصدار 7.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android لإنشاء تطبيقك، أصبح من الضروري استخدام الإصدار 11 من JDK لتشغيل Gradle. تتضمّن حزمة Android Studio Arctic Fox الإصدار 11 من JDK، كما أنّها تضبط Gradle لاستخدامه تلقائيًا، ما يعني أنّه ليس على معظم مستخدمي Android Studio إجراء أي تغييرات في إعدادات مشاريعهم.

إذا كنت بحاجة إلى ضبط إصدار JDK الذي يستخدمه المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP) يدويًا داخل "استوديو Android"، عليك استخدام الإصدار 11 من JDK أو إصدار أحدث.

عند استخدام المكوّن الإضافي لنظام Gradle المتوافق مع Android بشكل مستقل عن "استوديو Android"، عليك ترقية إصدار JDK من خلال ضبط متغيّر بيئة JAVA_HOME أو -Dorg.gradle.java.home خيار سطر الأوامر على دليل تثبيت JDK 11.

يُرجى العِلم أنّ "أداة إدارة حزمة تطوير البرامج" و"أداة إدارة الأجهزة الافتراضية لنظام Android" في حزمة "أدوات حزمة تطوير البرامج" المتوقّفة نهائيًا لا تعملان مع الإصدار 11 من JDK. لمواصلة استخدام "أداة إدارة حزمة تطوير البرامج" و"أداة إدارة المحاكي الافتراضي لنظام Android" مع الإصدار 7.0 من "مكوّن Android الإضافي لبرنامج Gradle" والإصدارات الأحدث، عليك التبديل إلى الإصدارات الجديدة من الأدوات في حزمة أدوات سطر الأوامر لحزمة تطوير البرامج (SDK) لنظام Android الحالية.

إصدار ثابت من Variant API

أصبحت واجهة Variant API الجديدة ثابتة الآن. يمكنك الاطّلاع على الواجهات الجديدة في حزمة com.android.build.api.variant، وعلى الأمثلة في مشروع gradle-recipes على GitHub. في إطار واجهة برمجة التطبيقات الجديدة الخاصة بحزمة APK المتغيرة، أتحنا عددًا من الملفات الوسيطة، تُعرف باسم العناصر، من خلال واجهة العناصر. ويمكن الحصول على هذه العناصر، مثل ملف البيان المدمج، بأمان وتخصيصها باستخدام مكوّنات إضافية ورموز برمجية تابعة لجهات خارجية.

سنواصل توسيع نطاق Variant API من خلال إضافة وظائف جديدة وزيادة عدد العناصر الوسيطة التي نتيحها للتخصيص.

تغييرات السلوك في Lint

يوضّح هذا القسم العديد من التغييرات في سلوك أداة Lint في الإصدار 7.0.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android.

تحسين أداة lint للعناصر التابعة للمكتبة

أصبحت عملية تشغيل lint باستخدام checkDependencies = true أسرع من ذي قبل. بالنسبة إلى مشاريع Android التي تتألف من تطبيق يتضمّن ملحقات مكتبة، يُنصح بضبط checkDependencies على true كما هو موضّح أدناه، وتشغيل Lint من خلال ./gradlew :app:lint، ما سيؤدي إلى تحليل جميع وحدات الملحقات بالتوازي وإنشاء تقرير واحد يتضمّن مشاكل من التطبيق وجميع ملحقاته.

// build.gradle
android {
  ...
  lintOptions {
    checkDependencies true
  }
}

// build.gradle.kts
android {
  ...
  lint {
    isCheckDependencies = true
  }
}

يمكن الآن أن تكون مهام Lint محدَّثة

إذا لم تتغيّر مصادر الوحدة ومواردها، لن تحتاج مهمة تحليل lint للوحدة إلى إعادة التشغيل. عند حدوث ذلك، سيظهر تنفيذ المهمة على أنّه "محدّث" في ناتج Gradle. نتيجةً لهذا التغيير، عند تشغيل أداة lint على وحدة تطبيق تتضمّن checkDependencies = true، لن تحتاج سوى الوحدات التي تم تغييرها إلى إجراء التحليل. نتيجةً لذلك، يمكن تشغيل Lint بشكل أسرع.

لا يلزم أيضًا تنفيذ مهمة تقرير Lint إذا لم تتغيّر مدخلاتها. المشكلة المعروفة ذات الصلة هي أنّه لا يتم عرض أي ناتج نصي لعملية التدقيق اللغوي في stdout عندما تكون مهمة التدقيق اللغوي UP-TO-DATE (المشكلة رقم 191897708).

تشغيل أداة lint على وحدات العناصر الديناميكية

لم يعُد AGP يتيح تشغيل أداة lint من وحدات الميزات الديناميكية. سيؤدي تشغيل أداة lint من وحدة التطبيق المعنيّة إلى تشغيلها على وحدات الميزات الديناميكية، كما سيتم تضمين جميع المشاكل في تقرير lint الخاص بالتطبيق. مشكلة معروفة ذات صلة هي أنّه عند تشغيل lint باستخدام checkDependencies = true من وحدة تطبيق، لا يتم التحقّق من تبعيات مكتبة الميزات الديناميكية إلا إذا كانت أيضًا تبعيات تطبيق (المشكلة #191977888).

تشغيل أداة lint على المتغير التلقائي فقط

عند تشغيل ./gradlew :app:lint، يتم الآن تشغيل أداة lint للنوع التلقائي فقط. في الإصدارات السابقة من المكوّن الإضافي لنظام Gradle المتوافق مع Android، كان يتم تشغيل أداة Lint لجميع الأنواع.

تحذيرات بشأن الفئات غير المتوفّرة في أداة التصغير R8

يتعامل R8 بشكل أكثر دقة واتساقًا مع الفئات غير المتوفّرة والخيار -dontwarn. لذلك، عليك البدء في تقييم تحذيرات الفئات غير المتوفّرة التي يصدرها R8.

عندما يواجه R8 مرجع فئة غير محدّد في تطبيقك أو أحد التبعيات، سيصدر تحذيرًا يظهر في ناتج الإصدار. مثلاً:

R8: Missing class: java.lang.instrument.ClassFileTransformer

يعني هذا التحذير أنّه تعذّر العثور على تعريف الفئة java.lang.instrument.ClassFileTransformer عند تحليل رمز تطبيقك. على الرغم من أنّ هذا يعني عادةً حدوث خطأ، من المحتمل أنّك تريد تجاهل هذا التحذير. هناك سببان شائعان لتجاهل التحذير، وهما:

1. المكتبات التي تستهدف JVM والفئة غير المتوفّرة هي من نوع مكتبة JVM (كما في المثال أعلاه).

2. يستخدم أحد العناصر التابعة واجهة برمجة تطبيقات في وقت التجميع فقط.

يمكنك تجاهل تحذير بشأن فئة غير متوفّرة من خلال إضافة قاعدة -dontwarn إلى ملف proguard-rules.pro. مثلاً:

-dontwarn java.lang.instrument.ClassFileTransformer

لتسهيل الأمر، ستنشئ "إضافة Android Gradle" ملفًا يحتوي على جميع القواعد التي يُحتمَل أن تكون ناقصة، وستكتبها في مسار ملف مثل ما يلي: app/build/outputs/mapping/release/missing_rules.txt. أضِف القواعد إلى ملف proguard-rules.pro لتجاهل التحذيرات.

في الإصدار 7.0 من "مكوّن Android الإضافي في Gradle"، ستظهر رسائل الفئات غير المتوفّرة على شكل تحذيرات، ويمكنك تحويلها إلى أخطاء من خلال ضبط android.r8.failOnMissingClasses = true في gradle.properties. في الإصدار 8.0 من "مكوّن Android الإضافي لنظام Gradle"، ستتحوّل هذه التحذيرات إلى أخطاء تؤدي إلى إيقاف عملية الإنشاء. يمكنك الاحتفاظ بسلوك الإصدار 7.0 من "مكوّن Android الإضافي" من خلال إضافة الخيار -ignorewarnings إلى ملف proguard-rules.pro، ولكن لا يُنصح بذلك.

إزالة ذاكرة التخزين المؤقت لتصميم المكوّن الإضافي لنظام Gradle المتوافق مع Android

تمت إزالة ذاكرة التخزين المؤقت لعمليات الإنشاء في "مكوّن Android الإضافي في Gradle" (AGP) في الإصدار 4.1. تم طرح ذاكرة التخزين المؤقت لتصميم AGP في الإصدار 2.3 من AGP لتكمّل ذاكرة التخزين المؤقت لتصميم Gradle، وتم استبدالها بالكامل بذاكرة التخزين المؤقت لتصميم Gradle في الإصدار 4.1 من AGP. لا يؤثّر هذا التغيير في وقت الإنشاء.

في الإصدار 7.0 من AGP، تمت إزالة السمة android.enableBuildCache والسمة android.buildCacheDir والمهمة cleanBuildCache.

استخدام رمز المصدر Java 11 في مشروعك

يمكنك الآن تجميع ما يصل إلى رمز مصدر Java 11 في مشروع تطبيقك، ما يتيح لك استخدام ميزات لغة أحدث، مثل طرق الواجهة الخاصة، وعامل التشغيل الماسي للفئات المجهولة، وبنية المتغير المحلي لمعلمات lambda.

لتفعيل هذه الميزة، اضبط compileOptions على إصدار Java المطلوب واضبط compileSdkVersion على 30 أو أعلى:

// build.gradle
android {
  compileSdkVersion 30
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_11
    targetCompatibility JavaVersion.VERSION_11
  }
  // For Kotlin projects
  kotlinOptions {
    jvmTarget = "11"
  }
}

// build.gradle.kts
android {
  compileSdkVersion(30)
  compileOptions {
    sourceCompatibility(JavaVersion.VERSION_11)
    targetCompatibility(JavaVersion.VERSION_11)
  }
  kotlinOptions {
    jvmTarget = "11"
  }
}

إزالة إعدادات التبعية

في الإصدار 7.0 من "مكوّن Android الإضافي في Gradle"، تمت إزالة الإعدادات التالية (أو نطاقات التبعية):

• compile
  استنادًا إلى حالة الاستخدام، تم استبدال هذا الحدث بالحدث api أو implementation.
  ينطبق ذلك أيضًا على صيغ *Compile، مثل: debugCompile.
• provided
  تم استبدال هذا الإجراء بـ compileOnly.
  ينطبق ذلك أيضًا على خيارات المنتجات *المقدَّمة، مثل: releaseProvided.
• apk
  تم استبدال هذا الإجراء بـ runtimeOnly.
• publish
  تم استبدال هذا الإجراء بـ runtimeOnly.

في معظم الحالات، سيقوم مساعد ترقية AGP تلقائيًا بنقل مشروعك إلى الإعدادات الجديدة.

تغيير مسار الفئة عند التجميع باستخدام المكوّن الإضافي لنظام Gradle المتوافق مع Android

إذا كنت تُجري عملية تجميع باستخدام الإصدار 3.0.0 أو إصدار أحدث من Android Gradle Plugin، قد يتغيّر مسار الفئة المجمّعة. بما أنّ "مكوّن Android الإضافي" يستخدم الآن إعدادات api/implementation داخليًا، قد تتم إزالة بعض العناصر من مسار فئة وقت الترجمة. إذا كنت تعتمد على تبعية AGP في وقت الترجمة، احرص على إضافتها كعنصر تابع صريح.

لا تتوفّر إمكانية إضافة مكتبات مجمَّعة من رموز برمجية أصلية في مجلد موارد Java

في السابق، كان بإمكانك إضافة مكتبة مجمّعة من رموز برمجية أصلية في مجلد موارد Java، وتسجيل المجلد باستخدام android.sourceSets.main.resources.srcDirs ليتم استخراج المكتبة المجمّعة من رموز برمجية أصلية وإضافتها إلى حزمة APK النهائية. بدءًا من الإصدار 7.0 من "مكوّن Android الإضافي لنظام Gradle"، لن يكون ذلك متاحًا وسيتم تجاهل المكتبات الأصلية في مجلد موارد Java. يمكنك بدلاً من ذلك استخدام طريقة DSL المخصّصة للمكتبات المجمّعة من الرموز البرمجية الأصلية، android.sourceSets.main.jniLibs.srcDirs. لمزيد من المعلومات، اطّلِع على مقالة كيفية ضبط مجموعات رموز المصدر.

المشاكل المعروفة

يوضّح هذا القسم المشاكل المعروفة في الإصدار 7.0.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android.

عدم التوافق مع الإصدار 1.4.x من إضافة Kotlin Multiplatform

يتوافق الإصدار 7.0.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android مع الإصدار 1.5.0 من المكوّن الإضافي لمنصّة Kotlin المتعدّدة والإصدارات الأحدث. يجب تعديل المشاريع التي تستخدم ميزة Kotlin Multiplatform إلى الإصدار 1.5.0 من Kotlin لاستخدام الإصدار 7.0.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android. كحلّ بديل، يمكنك الرجوع إلى الإصدار 4.2.x من المكوّن الإضافي لنظام Gradle المتوافق مع Android، ولكن لا ننصح بذلك.

لمزيد من المعلومات، يُرجى الاطّلاع على KT-43944.

إخراج Lint غير متوفّر

لا يتم عرض أي ناتج نصي لعملية التدقيق اللغوي في stdout عندما تكون مهمة التدقيق اللغوي محدّثة (المشكلة رقم 191897708). لمزيد من المعلومات، راجِع تغييرات السلوك في أداة Lint. سيتم حلّ هذه المشكلة في الإصدار 7.1 من المكوّن الإضافي لنظام Gradle المتوافق مع Android.

لا يتم فحص جميع التبعيات في مكتبة الوحدات الديناميكية باستخدام أداة Lint

عند تشغيل أداة lint باستخدام checkDependencies = true من وحدة تطبيق، لا يتم التحقّق من تبعيات مكتبة الميزات الديناميكية إلا إذا كانت أيضًا من تبعيات التطبيق (المشكلة رقم 191977888). كحلّ بديل، يمكن تشغيل مهمة Lint على هذه المكتبات. لمزيد من السياق، اطّلِع على تغييرات السلوك في أداة Lint.