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

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

التوافق

يجب توفّر JDK 11 لتشغيل الإصدار 7.0 من AGP

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

إذا أردت ضبط إصدار JDK يدويًا داخل AGP داخل "استوديو Android"، عليك استخدام JDK 11 أو الإصدارات الأحدث.

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

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

الإصدار الثابت من واجهة برمجة التطبيقات لخيار المنتج

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

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

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

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

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

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

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

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

يمكن تحديث مهام الوبر الآن

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

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

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

لم يعُد تطبيق AGP يدعم تشغيل برنامج Lit من وحدات الميزات الديناميكية. سيؤدي تشغيل أداة 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

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

في الإصدار 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"
  }
}

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

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

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

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

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

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

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

في السابق، كان بإمكانك إضافة مكتبة أصلية في مجلد موارد Java وتسجيل المجلد باستخدام android.sourceSets.main.resources.srcDirs لكي يتم استخراج المكتبة الأصلية وإضافتها إلى حزمة APK النهائية. بدءًا من الإصدار 7.0 من AGP، لا يتم توفير هذه الميزة ويتم تجاهل المكتبات الأصلية في مجلد موارد 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 والإصدارات الأحدث من المكوِّن الإضافي لنظام Gradle المتعدد على نظام التشغيل Kootlin والإصدارات الأحدث. ويجب تحديث المشاريع التي تستخدم لغة البرمجة Kotlin متعددة الأنظمة إلى الإصدار 1.5.0 من Kotlin 1.5.0 لاستخدام المكوّن الإضافي لنظام Gradle المتوافق مع Android الإصدار 7.0.0. وكحل بديل، يمكنك الرجوع إلى إصدار 4.2.x من المكوّن الإضافي لنظام Gradle المتوافق مع Android، إلا أنّه لا ننصح بذلك.

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

ناتج الوبر غير متوفّر

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

لا يتم التحقّق من ليس كل تبعيات مكتبة الميزات الديناميكية.

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