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

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

کاتلین 

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

شیار 

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

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

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

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

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

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

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

gradle wrapper --gradle-version 8.7

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

...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.7-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
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.6 پشتیبانی می‌کند، سطح API 34 است. در اینجا سایر اطلاعات سازگاری وجود دارد:

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

تغییر رفتار لینت

با شروع پلاگین Android Gradle 8.7.0-alpha08، اگر هنگام اجرای lint با استفاده از Gradle LintError وجود داشته باشد، وظیفه تجزیه و تحلیل پرز یک استثنا ایجاد می کند. این تغییر از ذخیره شدن خطاهای نادر در کش ساخت جلوگیری می کند.

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

مسائل رفع شد

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

رفع مشکلات
پلاگین اندروید Gradle
AGP باید ادعا کند که از API 35 که در شرف عرضه است پشتیبانی می کند
AGP 8.5: بسیاری دیگر از وظایف "mergeDebugResources" اجرا می شوند و سرعت ساخت ها را کاهش می دهند.
ndk 27 ​​را NDK پیش فرض در AGP قرار دهید.
AGP باید ادعا کند که از API 35 که در شرف عرضه است پشتیبانی می کند
AGP باید ادعا کند که از API 35 که در شرف عرضه است پشتیبانی می کند
اجرای لینت اندروید با NoSuchFileException ناموفق بود
BuildType#initWith بلوک پس‌پردازش کپی‌ها، اما پیکربندی محافظ اعمال نمی‌شود
نمی توان برای برچسب های foregroundServiceType ادغام کرد
اجرای لینت اندروید با NoSuchFileException ناموفق بود
لینت
Lint باید اشیاء نامعتبر مورد استفاده به عنوان ViewGroups را بررسی کند
"android:host is missing" برای uris با میزبان پوچ
ناسازگاری KtAnalysisSessionProvider با بررسی های lint معرفی شده در 8.7.0-alpha04
"مثبت نادرست" WrongConstant هنگام استفاده از PackageManager.ResolveInfoFlags.of با Kotlin

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

رفع مشکلات
پلاگین اندروید Gradle
اسناد agp دارای مقدار زیادی TBD هستند
لینت
AGP 8.6.1: رگرسیون - خرابی پرزهای ثابت اشتباه هنگام استفاده از [Int].toLong() در داخل یک @LongDef در Kotlin
خطای پرز «حداقل یک میزبان باید مشخص شود» هنگام تنظیم طرح intent-filter http یا https

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

رفع مشکلات
لینت
AGP 8.7.0 - Lint False Positive RestrictedApi در NavOptionsBuilder.popUpTo
کوچک کننده (R8)
[R8 8.6.27] پیاده سازی روش با "throw null" جایگزین شد
فایل‌های پیش‌فرض اندروید پروگارد هنگام استفاده با نسخه فعلی R8 هشدار می‌دهند
MissingStartupProfileItemsDiagnostic اگر پیام خیلی بزرگ باشد، کلاینت Gradle را با خطای کمبود حافظه خراب می کند.