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

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

التوافق

يجب توفّر 11 JDK لتشغيل AGP 7.0

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

إذا كنت بحاجة إلى ضبط إصدار JDK يدويًا المستخدَم من قِبل AGP داخل Android Studio، عليك استخدام JDK 11 أو إصدار أحدث.

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

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

إصدار Variant API الثابت

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

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

تغييرات في سلوك أداة Lint

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

أداة 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 محدّثة

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

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

تشغيل أداة التدقيق على وحدات الميزات الديناميكية

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

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

يؤدي تشغيل ./gradlew :app:lint الآن إلى فحص الأخطاء في الخيار التلقائي فقط. في الإصدارات السابقة من AGP، كان يشغّل أداة Lint لجميع مختلفة.

تحذيرات الفئة مفقودة في جهاز تقليص R8

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

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

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

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

1. المكتبات التي تستهدف آلة متجه الدعم والفئة الناقصة هم من مكتبات JVM. نوع المكتبة (كما في المثال أعلاه).

2. تستخدم إحدى تبعياتك واجهة برمجة تطبيقات وقت التجميع فقط.

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

-dontwarn java.lang.instrument.ClassFileTransformer

للتيسير عليك، سيقوم AGP بإنشاء ملف يحتوي على جميع قواعد مفقودة، كتابتها في مسار ملف مثل ما يلي: app/build/outputs/mapping/release/missing_rules.txt إضافة إلى ملف proguard-rules.pro لتجاهل التحذيرات.

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

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

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

في AGP 7.0، تُستخدم السمة 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"
  }
}

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

في AGP 7.0، تم ضبط الإعدادات (أو نطاقات التبعية) التالية تمت إزالتها:

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

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

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

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

إضافة المكتبات الأصلية في موارد Java المجلد غير متاح.

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

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

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

عدم التوافق مع المكوّن الإضافي 1.4.x Kotlin Multiplatform

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

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

ناتج أداة Lint غير متوفّر.

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

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

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