الإصدار 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" في حزمة "أدوات حِزم تطوير البرامج (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 بدقة أكبر وبصورة systématique الصفوف غير المتوفّرة وخيار -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

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