یادداشت های انتشار پلاگین Android Gradle 8.6

مخزن JCenter در 31 مارس 2021 فقط خواندنی شد. برای اطلاعات بیشتر، به‌روزرسانی سرویس JCenter را ببینید.

سیستم ساخت اندروید استودیو مبتنی بر Gradle است و افزونه Android Gradle چندین ویژگی را اضافه می کند که مخصوص ساخت برنامه های اندروید هستند. اگرچه پلاگین Android Gradle (AGP) معمولاً به صورت قفل شده با Android Studio به روز می شود، این افزونه (و بقیه سیستم Gradle) می تواند مستقل از Android Studio اجرا شود و به طور جداگانه به روز شود.

این صفحه نحوه به روز نگه داشتن ابزار Gradle و آنچه در به روز رسانی های اخیر وجود دارد را توضیح می دهد. برای یادداشت‌های انتشار نسخه‌های گذشته پلاگین Android Gradle، به یادداشت‌های انتشار قبلی مراجعه کنید.

برای مشاهده مواردی که در این نسخه از افزونه Android Gradle رفع شده است، به مسائل بسته مراجعه کنید.

برای یک خلاصه سطح بالا از تغییرات نهایی آتی در افزونه Android Gradle، نقشه راه پلاگین Android Gradle را ببینید.

برای جزئیات در مورد نحوه پیکربندی بیلدهای اندرویدی خود با Gradle، به صفحات زیر مراجعه کنید:

برای اطلاعات بیشتر در مورد سیستم ساخت Gradle، به راهنمای کاربر Gradle مراجعه کنید.

افزونه اندروید Gradle را به روز کنید

وقتی Android Studio را به‌روزرسانی می‌کنید، ممکن است درخواستی برای به‌روزرسانی خودکار افزونه Android Gradle به آخرین نسخه موجود دریافت کنید. شما می توانید انتخاب کنید که به روز رسانی را بپذیرید یا به صورت دستی نسخه ای را بر اساس نیازهای ساخت پروژه خود مشخص کنید.

می‌توانید نسخه پلاگین را در منوی File > Project Structure > Project در Android Studio یا در فایل build.gradle.kts سطح بالا مشخص کنید. نسخه پلاگین برای همه ماژول های ساخته شده در آن پروژه Android Studio اعمال می شود. مثال زیر پلاگین را روی نسخه 8.6.0 از فایل build.gradle.kts تنظیم می کند:

کاتلین

plugins {
    id("com.android.application") version "8.6.0" apply false
    id("com.android.library") version "8.6.0" apply false
    id("org.jetbrains.kotlin.android") version "2.0.20" apply false
}

شیار

plugins {
    id 'com.android.application' version '8.6.0' apply false
    id 'com.android.library' version '8.6.0' apply false
    id 'org.jetbrains.kotlin.android' version '2.0.20' apply false
}

احتیاط: نباید از وابستگی‌های پویا در شماره‌های نسخه مانند 'com.android.tools.build:gradle:8.6.+' استفاده کنید. استفاده از این ویژگی می تواند باعث بروز رسانی های غیرمنتظره نسخه و مشکل در حل تفاوت های نسخه شود.

اگر نسخه پلاگین مشخص شده دانلود نشده است، Gradle دفعه بعد که پروژه خود را می سازید آن را دانلود می کند یا روی File > Sync Project with Gradle Files از نوار منوی Android Studio کلیک کنید.

Gradle را به روز کنید

وقتی Android Studio را به‌روزرسانی می‌کنید، ممکن است درخواستی برای به‌روزرسانی Gradle به آخرین نسخه موجود دریافت کنید. شما می توانید انتخاب کنید که به روز رسانی را بپذیرید یا به صورت دستی نسخه ای را بر اساس نیازهای ساخت پروژه خود مشخص کنید.

در جدول زیر فهرست شده است که کدام نسخه از Gradle برای هر نسخه از افزونه Android Gradle مورد نیاز است. برای بهترین عملکرد، باید از آخرین نسخه ممکن Gradle و افزونه استفاده کنید.

نسخه پلاگین حداقل نسخه Gradle مورد نیاز
8.5 8.7
8.4 8.6
8.3 8.4
8.2 8.2
8.1 8.0
8.0 8.0
7.4 7.5

نسخه های قدیمی تر

نسخه پلاگین نسخه Gradle مورد نیاز
7.3 7.4
7.2 7.3.3
7.1 7.2
7.0 7.0
4.2.0+ 6.7.1
4.1.0+ 6.5+
4.0.0+ 6.1.1+
3.6.0 - 3.6.4 5.6.4+
3.5.0 - 3.5.4 5.4.1+
3.4.0 - 3.4.3 5.1.1+
3.3.0 - 3.3.3 4.10.1+
3.2.0 - 3.2.1 4.6+
3.1.0+ 4.4+
3.0.0+ 4.1+
2.3.0+ 3.3+
2.1.3 - 2.2.3 2.14.1 - 3.5
2.0.0 - 2.1.2 2.10 - 2.13
1.5.0 2.2.1 - 2.13
1.2.0 - 1.3.1 2.2.1 - 2.9
1.0.0 - 1.1.3 2.2.1 - 2.3

می‌توانید نسخه Gradle را در منوی File > Project Structure > Project در Android Studio مشخص کنید، یا نسخه Gradle خود را با استفاده از خط فرمان به‌روزرسانی کنید. روش ترجیحی استفاده از ابزار خط فرمان Gradle Wrapper است که اسکریپت های gradlew را به روز می کند. مثال زیر با استفاده از Gradle Wrapper نسخه Gradle را روی 8.6 تنظیم می کند. توجه داشته باشید، باید این دستور را دو بار اجرا کنید تا هم Gradle و هم خود Gradle Wrapper را ارتقا دهید (برای اطلاعات بیشتر، به ارتقای Gradle Wrapper مراجعه کنید).

gradle wrapper --gradle-version 8.6

با این حال، ممکن است در برخی موارد شکست بخورد، برای مثال اگر AGP را به‌تازگی به‌روزرسانی کرده‌اید و دیگر با نسخه فعلی Gradle سازگار نیست. در این مورد، باید مرجع توزیع Gradle را در فایل gradle/wrapper/gradle-wrapper.properties ویرایش کنید. مثال زیر نسخه Gradle را روی 8.6 در فایل gradle-wrapper.properties تنظیم می کند.

...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.6-bin.zip
...

پلاگین Android Gradle و سازگاری Android Studio

سیستم ساخت اندروید استودیو مبتنی بر Gradle است و افزونه Android Gradle (AGP) چندین ویژگی را اضافه می کند که مخصوص ساخت برنامه های اندروید است. جدول زیر لیست می کند که کدام نسخه AGP برای هر نسخه از Android Studio مورد نیاز است.

نسخه اندروید استودیو نسخه AGP مورد نیاز
لیدی باگ | 2024.2.1 3.2-8.7
افت ویژگی کوالا | 2024.1.2 3.2-8.6
کوالا | 2024.1.1 3.2-8.5
چتر دریایی | 2023.3.1 3.2-8.4
ایگوانا | 2023.2.1 3.2-8.3
جوجه تیغی | 2023.1.1 3.2-8.2
زرافه | 2022.3.1 3.2-8.1
فلامینگو | 2022.2.1 3.2-8.0

نسخه های قدیمی تر

نسخه اندروید استودیو نسخه AGP مورد نیاز
مارماهی برقی | 2022.1.1 3.2-7.4
دلفین | 2021.3.1 3.2-7.3
سنجاب | 2021.2.1 3.2-7.2
زنبور عسل | 2021.1.1 3.2-7.1
روباه قطبی | 2020.3.1 3.1-7.0

برای کسب اطلاعات در مورد آنچه در افزونه Android Gradle جدید است، به یادداشت‌های انتشار افزونه Android Gradle مراجعه کنید.

حداقل نسخه ابزارها برای سطح API Android

حداقل نسخه‌های Android Studio و AGP وجود دارد که از سطح API خاصی پشتیبانی می‌کنند. استفاده از نسخه‌های پایین‌تر از Android Studio یا AGP نسبت به آنچه که targetSdk پروژه یا compileSdk مورد نیاز است، می‌تواند منجر به مشکلات غیرمنتظره شود. توصیه می‌کنیم از آخرین نسخه پیش‌نمایش Android Studio و AGP برای کار روی پروژه‌هایی که نسخه‌های پیش‌نمایش سیستم‌عامل Android را هدف می‌گیرند، استفاده کنید. می‌توانید نسخه‌های پیش‌نمایش Android Studio را در کنار یک نسخه پایدار نصب کنید .

حداقل نسخه های اندروید استودیو و AGP به شرح زیر است:

سطح API حداقل نسخه اندروید استودیو حداقل نسخه AGP
پیش نمایش VanillaIceCream چتر دریایی | 2023.3.1 8.4
34 جوجه تیغی | 2023.1.1 8.1.1
33 فلامینگو | 2022.2.1 7.2

تغییرات نسخه (نوامبر 2020)

ما در حال به‌روزرسانی شماره‌گذاری نسخه برای افزونه Android Gradle (AGP) هستیم تا با ابزار ساخت Gradle بیشتر مطابقت داشته باشد.

این تغییرات قابل توجه است:

  • AGP اکنون از نسخه‌سازی معنایی استفاده می‌کند و تغییرات شکسته برای نسخه‌های اصلی هدف قرار خواهند گرفت.

  • هر سال یک نسخه اصلی از AGP منتشر خواهد شد که با نسخه اصلی Gradle هماهنگ است.

  • انتشار بعد از AGP 4.2 نسخه 7.0 خواهد بود و نیاز به ارتقا به Gradle نسخه 7.x دارد. هر نسخه اصلی AGP به ارتقاء نسخه اصلی در ابزار Gradle نیاز دارد.

  • APIها تقریباً یک سال قبل منسوخ خواهند شد و قابلیت جایگزینی به طور همزمان در دسترس خواهد بود. APIهای منسوخ تقریباً یک سال بعد در طول به روز رسانی اصلی بعدی حذف خواهند شد.

سازگاری

حداکثر سطح API که افزونه Android Gradle 8.6 پشتیبانی می‌کند، سطح API 34 است. در اینجا سایر اطلاعات سازگاری وجود دارد:

حداقل نسخه نسخه پیش فرض یادداشت ها
گریدل 8.7 8.7 برای کسب اطلاعات بیشتر، به روز رسانی Gradle را ببینید.
ابزارهای ساخت SDK 34.0.0 34.0.0 ابزارهای ساخت SDK را نصب یا پیکربندی کنید .
NDK N/A 26.1.10909125 نسخه دیگری از NDK را نصب یا پیکربندی کنید .
JDK 17 17 برای کسب اطلاعات بیشتر، به تنظیم نسخه JDK مراجعه کنید.

مسائل رفع شد

پلاگین اندروید Gradle 8.6.0

مسائل ثابت
افزونه Gradle اندروید
رگرسیون AGP 7.0.0-alpha10: هنگامی که Databinding فعال است، افزونه "com.android.internal.library" اعمال نشد
خطا در اجرای لینت با و بدون K2 UAST
مانیفست برای پیکربندی AndroidTest Variant ایجاد نشده است
AGP 8.4 سعی می‌کند تا Startup Profiles را روی بیلدهای اشکال‌زدایی تنظیم کند
[Koala 2024.1.2 Canary 2] خطا در اجرای ماژول نمایه خط پایه در یک APK تقسیم شده
پاک کردن / حذف ProjectInfo
kdoc قدیمی را برای «isIncludeAndroidResources» در AGP DSL به‌روزرسانی کنید
Lint از دایرکتوری res بدون افزودن وابستگی به کار استفاده می کند
AGP 8.5: بسیاری دیگر از وظایف "mergeDebugResources" اجرا می شوند و سرعت ساخت ها را کاهش می دهند.
افزودن srcs dir از طریق Variant API همانطور که انتظار می رود کار نمی کند
دکسر (D8)
به‌روزرسانی پایگاه داده API به Android 15 (سطح API 35)
java.lang.VerifyError: تأییدکننده کلاس را رد کرد com.pax.log.LogUtils: java.lang.StackTraceElement com.pax.log.LogUtils.getCaller(com.pax.log.b، java.lang.StackTraceElement[]، int موفق به تأیید نشد
لینت
Lint برای استفاده از حاشیه نویسی، visitAnnotationUsage را صدا نمی کند
خطای UnknownNullness پرز هنگام استفاده از حاشیه نویسی استفاده از نوع
پرز [کتابخانه desugar] اخطار مثبت کاذب را نشان می دهد هشدارهای NewApi با فعال کردن قندزدایی
هشدار Lint Manager Credential Manager در Wear نادرست است
Lint: SetTextI18n از اختصاص یک رشته خالی شکایت دارد.
ادغام لینت
وظایف Lint با ساخت همراه با شکست مواجه می شوند
کوچک کننده (R8)
[r8 8.5]r8 ادغام کلاس افقی باعث خطای تأیید در Android5 هنگام غیرفعال کردن مدل سازی api می شود
نسخه Wear OS ساخته شده با پلاگین Gradle 8.4.0/8.5.0 ممکن است باعث ایجاد خطای java.lang.IllegalAccess شود
R8 به طور ضمنی یک بند عضو خالی را با یک مطابقت جایگزین می‌کند ()
[r8 8.5] ادغام کلاس عمودی باعث NPE زمان اجرا می شود
خطای پردازش R8 احتمالاً به دلیل عملگر Shift راست است
R8 (AGP 8.5.0+) با خطای "بازنویسی غیرمنتظره مورد: ... به دو مورد متمایز:..." خراب می شود.
فایل dex تولید شده توسط R8 نشان می دهد که "نمی توان اصلی (رشته[]) استاتیک را در "تست" پیدا کرد" در هنگام اجرا
رفتار متفاوت بین برنامه های بسته بندی شده توسط R8 و D8
R8 NullPointer پس از به روز رسانی به Kotlin 2.0

پلاگین اندروید Gradle 8.6.1

مسائل ثابت
دکسر (D8)
Dexing task/transform محتویات classes.dex غیر قطعی تولید می کند
کوچک کننده (R8)
R8 8.5.x StackOverflowError در SimpleInliningConstraintAnalysis
وظیفه :xxxx:minifyXXXReleaseWithR8 ERROR: R8: java.util.ConcurrentModificationException
java.lang.NullPointerException: نمی توان "com.android.tools.r8.ir.analysis.type.TypeElement.asClassType()" را فراخوانی کرد.