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

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

التوافق

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

عند استخدام الإصدار 7.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android لإنشاء تطبيقك، أصبح الإصدار 11 من JDK مطلوبًا الآن لتشغيل 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)" و"أداة إدارة أجهزة المحاكاة لنظام التشغيل Android (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، وفّرنا عددًا من الملفات الوسيطة، التي تُعرف باسم العناصر، من خلال واجهة العناصر. يمكن الحصول على هذه العناصر، مثل البيان المدمج، بأمان وتخصيصها باستخدام المكوّنات الإضافية والرموز البرمجية التابعة لجهات خارجية.

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

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

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

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

أصبح تشغيل 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).

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

لم يعُد "أداة تطوير التطبيقات لنظام التشغيل Android" (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 والصفّة غير المتوفّرة هي من نوع مكتبة JVM (كما هو موضّح في المثال أعلاه).

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

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

-dontwarn java.lang.instrument.ClassFileTransformer

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

في AGP 7.0، ستظهر رسائل الصفوف غير المتوفّرة كتحذيرات، ويمكنك تحويلها إلى أخطاء من خلال ضبط 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 في مشروع تطبيقك، ما يتيح لك استخدام ميزات اللغة الأحدث، مثل طرق الواجهات الخاصة وعامل العلامة الماسية للفئات المجهولة وبنية المتغيّر المحلي لمَعلمات لامدا.

لتفعيل هذه الميزة، اضبط 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 Plugin، تمت إزالة الإعدادات التالية (أو نطاقات التبعية):

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

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

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

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

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

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

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

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

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

يتوافق المكوّن الإضافي لنظام Gradle المتوافق مع Android 7.0.0 مع المكوّن الإضافي لنظام Kotlin المتوافق مع أنظمة التشغيل المتعددة 1.5.0 والإصدارات الأحدث. يجب تحديث المشاريع التي تستخدم Kotlin Multiplatform إلى الإصدار 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 من ملف APK لوحدة تطبيق، لا يتم التحقّق من تبعيات مكتبة الميزات الديناميكية ما لم تكن أيضًا تبعيات للتطبيق (المشكلة رقم 191977888). كحل بديل، يمكن تنفيذ مهمة فحص الأخطاء على هذه المكتبات. لمزيد من السياق، اطّلِع على التغييرات في سلوك أداة lint.