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

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

التوافق

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

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

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

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

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

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

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

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

عند تشغيل ./gradlew :app:lint، يتم الآن تشغيل أداة lint لمتغير الإصدار التلقائي فقط. في الإصدارات السابقة من "مكوّن Android الإضافي لنظام Gradle"، كان يتم تشغيل أداة 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 من "استوديو Android"، ستظهر رسائل الفئات غير المتوفّرة كتنبيهات، ويمكنك تحويلها إلى أخطاء من خلال ضبط android.r8.failOnMissingClasses = true في gradle.properties. في الإصدار 8.0 من "مكوّن Android الإضافي لنظام Gradle"، ستتحوّل هذه التحذيرات إلى أخطاء تؤدي إلى إيقاف عملية الإنشاء. يمكنك الحفاظ على سلوك الإصدار 7.0 من AGP من خلال إضافة الخيار -ignorewarnings إلى ملف proguard-rules.pro، ولكن لا يُنصح بذلك.

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

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

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

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

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

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

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

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

في السابق، كان بإمكانك إضافة مكتبة JNI في مجلد موارد Java، وتسجيل المجلد باستخدام android.sourceSets.main.resources.srcDirs ليتم استخراج مكتبة JNI وإضافتها إلى حزمة APK النهائية. واعتبارًا من الإصدار 7.0 من "مكوّن Android الإضافي في Gradle"، لن يكون ذلك متاحًا وسيتم تجاهل مكتبات JNI في مجلد موارد Java. بدلاً من ذلك، استخدِم طريقة DSL المخصّصة لمكتبات JNI، وهي 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 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 من وحدة تطبيق، لا يتم التحقّق من تبعيات مكتبة الميزات الديناميكية إلا إذا كانت أيضًا من تبعيات التطبيق (المشكلة رقم 191977888). كحلّ بديل، يمكن تشغيل مهمة Lint على هذه المكتبات. لمزيد من السياق، راجِع التغييرات في سلوك أداة Lint.