سیستم ساخت اندروید استودیو مبتنی بر Gradle است و افزونه Android Gradle چندین ویژگی را اضافه می کند که مخصوص ساخت برنامه های اندروید هستند. اگرچه پلاگین Android Gradle (AGP) معمولاً به صورت قفل شده با Android Studio به روز می شود، این افزونه (و بقیه سیستم Gradle) می تواند مستقل از Android Studio اجرا شود و به طور جداگانه به روز شود.
این صفحه نحوه به روز نگه داشتن ابزار Gradle و آنچه در به روز رسانی های اخیر وجود دارد را توضیح می دهد. برای یادداشت‌های انتشار نسخه‌های گذشته پلاگین Android Gradle، به یادداشت‌های انتشار قبلی مراجعه کنید.
برای مشاهده مواردی که در این نسخه از افزونه Android Gradle رفع شده است، به مسائل بسته مراجعه کنید.
برای یک خلاصه سطح بالا از تغییرات نهایی آتی در افزونه Android Gradle، نقشه راه پلاگین Android Gradle را ببینید.
برای جزئیات در مورد نحوه پیکربندی بیلدهای اندرویدی خود با Gradle، به صفحات زیر مراجعه کنید:
- ساخت خود را پیکربندی کنید
- پلاگین اندروید Gradle مرجع DSL
- مرجع Gradle DSL
- راهنمای کاربر عملکرد 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 |
|---|---|---|
| پیش نمایش باقلوا | میرکات | 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.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 |
| |||||||||
| لینت |
| |||||||||
پلاگین اندروید Gradle 8.7.1
| مسائل ثابت شده | |||
|---|---|---|---|
| پلاگین اندروید Gradle |
| ||
| لینت |
| ||
پلاگین اندروید Gradle 8.7.2
| مسائل ثابت شده | ||||
|---|---|---|---|---|
| لینت |
| |||
| کوچک کننده (R8) |
| |||
پلاگین اندروید Gradle 8.7.3
| مسائل ثابت شده | |||
|---|---|---|---|
| لینت |
| ||