افزایه Android Gradle 7.0.0 (ژوئیه ۲۰۲۱)

افزایه Android Gradle نسخه ۷.۰.۰ نسخهٔ پخش اصلی است که شامل ویژگی‌های جدید متنوع و بهبودها است.

سازگاری

برای اجرای AGP 7.0، به JDK 11 نیاز است

هنگام استفاده از افزایه Android Gradle 7.0 برای ساختن برنامه، اکنون برای اجرای Gradle به JDK 11 نیاز است. ‫Android Studio Arctic Fox‏ JDK 11 را دسته‌بندی می‌کند و ‫Gradle را پیکربندی می‌کند تا به‌طور پیش‌فرض از آن استفاده کند، که یعنی اکثر کاربران Android Studio نیازی ندارند هیچ تغییری در پیکربندی پروژه‌هایشان ایجاد کنند.

اگر نیاز دارید نسخه JDK مورد استفاده AGP را به‌صورت دستی در Android Studio تنظیم کنید، باید از JDK 11 یا بالاتر استفاده کنید.

هنگام استفاده از AGP مستقل از Android Studio، نسخه JDK را با تنظیم متغیر محیط JAVA_HOME یا -Dorg.gradle.java.home گزینه خط فرمان به دایرکتوری نصب JDK 11 ارتقا دهید.

توجه داشته باشید که «مدیر کیت توسعه نرم‌افزار» و «مدیر دستگاه مجازی Android» در بسته «ابزارهای کیت توسعه نرم‌افزار» منسوخ‌شده با JDK 11 کار نمی‌کنند. برای ادامه استفاده از «مدیر کیت توسعه نرم‌افزار» و «مدیر دستگاه مجازی Android» با AGP 7.0 و بالاتر، باید به نسخه‌های جدید ابزارها در بسته ابزارهای خط فرمان کیت توسعه نرم‌افزار Android فعلی بروید.

میانای برنامه‌سازی کاربردی گونه پایدار

«میانای برنامه‌سازی کاربردی متغیر» جدید اکنون پایدار است. واسط‌های جدید را در بسته com.android.build.api.variant و نمونه‌ها را در پروژه GitHub gradle-recipes ببینید. به‌عنوان بخشی از «میانای برنامه‌سازی کاربردی» جدید «گونه»، تعدادی فایل واسطه به نام «آرتیفکت» ازطریق واسط آرتیفکت‌ها دردسترس قرار داده‌ایم. این آرتیفکت‌ها، مانند مانیفست ادغام‌شده، را می‌توان بااستفاده از افزایه‌ها و کد طرف سوم به‌طور ایمن دریافت و سفارشی‌سازی کرد.

با افزودن کارکردهای جدید و افزایش تعداد آرتیفکت‌های واسطه‌ای که برای سفارشی‌سازی دردسترس قرار می‌دهیم، به گسترش «میانای برنامه کاربردی گونه» ادامه خواهیم داد.

تغییرات رفتار برای Lint

این بخش چندین تغییر رفتار Lint در افزایه Android Gradle نسخه ۷.۰.۰ را شرح می‌دهد.

‫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 تغییر نکرده باشد، این تکلیف نیز نیازی به اجرا ندارد. مشکل شناخته‌شده مرتبط این است که وقتی تکلیف lint «به‌روز» است، برونداد نوشتاری lint در stdout چاپ نمی‌شود (مشکل شماره ۱۹۱۸۹۷۷۰۸).

اجرای lint روی واحدهای ویژگی پویا

‫AGP دیگر از اجرای lint از واحدهای ویژگی پویا پشتیبانی نمی‌کند. اجرای lint از واحد برنامه مربوطه، lint را روی واحدهای ویژگی پویا اجرا می‌کند و همه مشکلات را در گزارش lint برنامه لحاظ می‌کند. مشکل شناخته‌شده مرتبط این است که هنگام اجرای lint با checkDependencies = true از واحد برنامه، وابستگی‌های کتابخانه ویژگی پویا بررسی نمی‌شوند، مگر اینکه وابستگی‌های برنامه نیز باشند (مشکل شماره ۱۹۱۹۷۷۸۸۸).

‫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 اضافه کنید.

در AGP 7.0، پیام‌های کلاس ازدست‌رفته به‌عنوان هشدار نمایش داده می‌شود و می‌توانید با تنظیم android.r8.failOnMissingClasses = true در gradle.properties، آن‌ها را به خطا تبدیل کنید. در AGP 8.0، این هشدارها به خطاهایی تبدیل می‌شوند که ساخت شما را متوقف می‌کنند. با افزودن گزینه -ignorewarnings به فایل proguard-rules.pro می‌توانید رفتار AGP 7.0 را حفظ کنید، اما این کار توصیه نمی‌شود.

حافظه نهان ساخت افزایه Android Gradle برداشته شد

در AGP 4.1، حافظه نهان ساخت AGP برداشته شد. حافظه نهان ساخت AGP که قبلاً در AGP 2.3 برای تکمیل حافظه نهان ساخت Gradle معرفی شده بود، در AGP 4.1 به‌طور کامل با حافظه نهان ساخت Gradle جایگزین شد. این تغییر بر زمان ساخت تأثیر نمی‌گذارد.

در AGP 7.0، ویژگی android.enableBuildCache، ویژگی android.buildCacheDir، و تکلیف cleanBuildCache برداشته شده است.

استفاده از کد منبع Java 11 در پروژه

اکنون می‌توانید کد منبع تا جاوا ۱۱ را در پروژه برنامه‌تان گردآوری کنید و به شما امکان می‌دهد از ویژگی‌های زبان جدیدتر مثل روش‌های واسط خصوصی، عامل الماس برای کلاس‌های ناشناس، و دستورگان متغیر محلی برای پارامترهای لامبدا استفاده کنید.

برای فعال کردن این ویژگی، compileOptions را روی نسخه Java انتخابی‌تان تنظیم کنید و compileSdkVersion را روی ۳۰ یا بالاتر تنظیم کنید:

// 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 جایگزین شده است.
  همچنین برای گونه‌های *Compile، برای مثال: debugCompile اعمال می‌شود.
• provided
  این مورد با compileOnly جایگزین شده است.
  برای گونه‌های *ارائه‌شده نیز اعمال می‌شود، برای مثال: releaseProvided.
• apk
  این مورد با runtimeOnly جایگزین شده است.
• publish
  این مورد با runtimeOnly جایگزین شده است.

در اکثر موارد، دستیار ارتقا AGP به‌طور خودکار پروژه شما را به پیکربندی‌های جدید منتقل می‌کند.

تغییر مسیر کلاس هنگام کامپایل کردن دربرابر افزایه Android Gradle

اگر دربرابر افزایه Android Gradle کامپایل می‌کنید، مسیر کلاس کامپایل شما ممکن است تغییر کند. ازآنجایی‌که AGP اکنون از پیکربندی‌های api/implementation داخلی استفاده می‌کند، ممکن است برخی‌از آرتیفکت‌ها از مسیر کلاس کامپایل شما برداشته شوند. اگر در زمان کامپایل به وابستگی AGP متکی هستید، حتماً آن را به‌عنوان وابستگی صریح اضافه کنید.

افزودن کتابخانه‌های JNI در پوشه منابع Java پشتیبانی نمی‌شود

قبلاً می‌توانستید کتابخانه JNI را در پوشه منابع Java اضافه کنید و پوشه را بااستفاده از android.sourceSets.main.resources.srcDirs ثبت کنید تا کتابخانه JNI استخراج شود و به APK نهایی اضافه شود. از AGP 7.0، این مورد پشتیبانی نمی‌شود و کتابخانه‌های JNI در پوشه منابع Java نادیده گرفته می‌شوند. درعوض، از روش DSL که برای کتابخانه‌های JNI درنظر گرفته شده است، android.sourceSets.main.jniLibs.srcDirs، استفاده کنید. برای اطلاعات بیشتر، نحوه پیکربندی مجموعه‌های منبع را ببینید.

مشکلات شناخته‌شده

این بخش مشکلات شناخته‌شده موجود در افزایه Android Gradle نسخه ۷.۰.۰ را شرح می‌دهد.

ناسازگاری با افزایه Kotlin Multiplatform نسخه ۱.۴.x

«افزایه Android Gradle» نسخه ۷.۰.۰ با Kotlin افزایه چندسکویی نسخه ۱.۵.۰ و بالاتر سازگار است. پروژه‌هایی که از پشتیبانی Kotlin Multiplatform استفاده می‌کنند برای استفاده از Android Gradle Plugin 7.0.0 باید به Kotlin 1.5.0 به‌روزرسانی کنند. به‌عنوان راهکار موقت، می‌توانید افزایه Android Gradle را به نسخه ۴.۲.x تنزل دهید، اگرچه این کار توصیه نمی‌شود.

برای اطلاعات بیشتر، KT-43944 را ببینید.

برونداد lint وجود ندارد

وقتی تکلیف lint به‌روز باشد، هیچ برونداد نوشتاری lint در stdout چاپ نمی‌شود (مسئله شماره ۱۹۱۸۹۷۷۰۸). برای زمینه‌های بیشتر، تغییرات رفتار برای lint را ببینید. این مشکل در افزایه Android Gradle نسخه ۷.۱ برطرف خواهد شد.

همه وابستگی‌های کتابخانه ویژگی پویا بررسی lint نمی‌شوند

وقتی lint را با checkDependencies = true از یک واحد برنامه اجرا می‌کنید، وابستگی‌های کتابخانه ویژگی پویا بررسی نمی‌شوند، مگر اینکه آن‌ها همچنین وابستگی‌های برنامه باشند (مسئله ‎#191977888). به‌عنوان راهکار موقت، تکلیف lint را می‌توان روی آن کتابخانه‌ها اجرا کرد. برای زمینه‌های بیشتر، تغییرات رفتار برای lint را ببینید.