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

مخزن 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.9.0 از فایل build.gradle.kts تنظیم می کند:

plugins {
    id("com.android.application") version "8.9.0" apply false
    id("com.android.library") version "8.9.0" apply false
    id("org.jetbrains.kotlin.android") version "2.1.10" apply false
}
plugins {
    id 'com.android.application' version '8.9.0' apply false
    id 'com.android.library' version '8.9.0' apply false
    id 'org.jetbrains.kotlin.android' version '2.1.10' apply false
}

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

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

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

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

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

نسخه پلاگین حداقل نسخه Gradle مورد نیاز
8.9 8.11.1
8.8 8.10.2
8.7 8.9
8.6 8.7
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 را با استفاده از Gradle Wrapper روی 8.9 تنظیم می کند. توجه داشته باشید، باید این دستور را دو بار اجرا کنید تا هم Gradle و هم خود Gradle Wrapper را ارتقا دهید (برای اطلاعات بیشتر، به ارتقای Gradle Wrapper مراجعه کنید).

gradle wrapper --gradle-version 8.9

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

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

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

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

نسخه اندروید استودیو نسخه AGP مورد نیاز
میرکات | 2024.3.1 3.2-8.9
قطره ویژگی لیدی باگ | 2024.2.2 3.2-8.8
لیدی باگ | 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
پیش نمایش باقلوا میرکات | 2024.3.1 8.9.0
35 افت ویژگی کوالا | 2024.2.1 8.6.0
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.9 پشتیبانی می کند، سطح API 35 است. در اینجا سایر اطلاعات سازگاری وجود دارد:

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

مسائل رفع شد

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

مسائل ثابت شده
پلاگین اندروید Gradle
هنگامی که وظیفه راه‌اندازی GMD با فضای دیسک ناکافی با شکست مواجه می‌شود، یک پیام خطای عملی ارائه دهید
افزونه com.android.settings targetSdk را نمی شناسد
خطای غیر مفید ''compileSdkVersion مشخص نشده است. لطفا آن را به build.gradle اضافه کنید"
"Clean build" در منوی Build وجود ندارد
شاید اجازه دهید Kotlin داخلی AGP از افزودن خودکار وابستگی kotlin stdlib پشتیبانی کند
برای مدیریت پشتیبانی داخلی kotlin، shouldConfigureKotlinPlatformAttribute را به روز کنید
برای «checkTestedAppObfuscationRelease»، نحو gradle کاتلین را در پیام خطا بدهید.
خطای Fused Library هنگامی که وابستگی حل نشده می تواند بهبود یابد
ویژگی های سیستم از gradle.properties در فرآیندهای جداگانه به R8 Gradle Workers منتقل نمی شود
BuiltArtifact.outputFile را به عنوان نوع فایل تبدیل کنید
عدم ارائه فضای نام در کتابخانه ذوب شده، پیام خطای خوبی نمی دهد
گزینه های lint در AGP 7.1.0-alpha08 اجازه stdout را نمی دهد
افزونه Gradle Android: انواع باید نام مجموعه منبع را در معرض نمایش قرار دهند
حافظه پنهان پیکربندی نسبت به تنظیم متغیر محیطی TERM شکننده است
AndroidComponentsExtension.addSourceSetConfigurations با فعال شدن آمار خراب می شود
خط اولیه اسکریپت 'C:\Users\mypc\AppData\Local\Temp\ijresolvers2.gradle': 162
AndroidComponentsExtension.addSourceSetConfigurations با فعال شدن آمار خراب می شود
دکسر (D8)
java.lang.VerifyError: تأییدکننده کلاس رد شد: [0x430] copy1 v2<-v264 type=Udefined cat=3
لینت
لینت با بررسی های لینت gradle خراب می شود
Lint با پیام InstantiationException بدون استثنا در lint stacktrace شکست می خورد
بررسی پرزهای مثبت کاذب android.permission.SCHEDULE_EXACT_ALARM فقط به برنامه های سیستم اعطا می شود
چک StringFormatInvalid باید برای روش Compose stringResource اعمال شود
حاشیه نویسی RequiresFeature برای فایل های Kotlin کار نمی کند
kotlin android.os.Handler removeCallbacks Runnable
WrongConstant lint در تعریف به جای استفاده از ثابت با استفاده از shift
WrongConstant پرز دو بار ظاهر می شود
استثنای زمان اجرا زیر API 26 با Java nio API پشتیبانی نشده (بدون خطای پرز)
Lint از استفاده از RequiresApi حتی در روش کمکی خصوصی در آزمایش جلوگیری می کند
حالت K2 هنگام استفاده از .hasRoute (Route::class) در Android Studio هشدار RestrictedApi می دهد.
Lint پیشنهاد می‌کند در آزمایش @RequiresExtension را با SdkSuppress@ که از پسوندهای SDK پشتیبانی نمی‌کند، جایگزین کنید.
هنگامی که یک FrameLayout با fitSystemWindows برای بسته بندی یک RelativeLayout فرزند که نیاز به padding سفارشی دارد، Lint به اشتباه یک طرح تودرتوی غیرضروری را گزارش می کند.
قانون پرز CoarseFineLocation ویژگی maxSdkVersion را در نظر نمی گیرد
AppLinkSplitToWebAndCustom در lint 8.7.3 Unknown Issue است
بررسی خرابی StringEscapeDetector در "\\"
هشدار پرز اشتباه برای حاشیه نویسی «@Parcelize» در رابط های مهر و موم شده
AS 2024.3.1.4 به طور متناوب هنگام ویرایش متون کاتلین آویزان می شود.
ادغام لینت
lintVitalRelease به طور خودکار هنگام ساخت بسته نرم افزاری اجرا نمی شود
کوچک کننده (R8)
Gson proguard پس از ارتقاء به AGP 8.8 به درستی کار نمی کند
java.lang.VerifyError: تأییدکننده کلاس رد شد
Leanback وقتی با R8 موجود در AGP 8.10.0-alpha04 کوچک می شود خراب می شود