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

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

التوافق

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

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

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

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

يُرجى العِلم أنّ "أداة إدارة حزمة تطوير البرامج" و"أداة إدارة الأجهزة الافتراضية لنظام Android" في حزمة "أدوات حزمة تطوير البرامج" المتوقّفة نهائيًا لا تعملان مع الإصدار 11 من JDK. لمواصلة استخدام "أداة إدارة حزمة تطوير البرامج (SDK)" و"أداة إدارة الأجهزة الافتراضية لنظام 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 إذا لم تتغيّر مدخلاتها. المشكلة المعروفة ذات الصلة هي أنّه لا يتم عرض أي نص lint في stdout عندما تكون مهمة lint في حالة UP-TO-DATE (المشكلة رقم 191897708).

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

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

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

عند تشغيل ./gradlew :app:lint، يتم الآن تشغيل أداة lint للنوع التلقائي فقط. في الإصدارات السابقة من AGP، كان يتم تشغيل أداة 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

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

في الإصدار 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 إلى الإصدار 1.5.0 من Kotlin لاستخدام الإصدار 7.0.0 من "المكوّن الإضافي لنظام Gradle المتوافق مع Android". كحلّ بديل، يمكنك الرجوع إلى الإصدار 4.2.x من المكوّن الإضافي لنظام Gradle المتوافق مع Android، ولكن لا يُنصح بذلك.

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

لم يتم إدخال نتائج فحص الأخطاء

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

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

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