درباره افزایه Android Gradle

سیستم ساخت «استودیو Android» براساس Gradle است و افزایه Android Gradle چندین ویژگی را که مختص ساخت برنامه‌های Android است اضافه می‌کند.

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

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

برای جزئیات درباره نحوه پیکربندی ساخت‌های Android با Gradle، صفحه‌های زیر را ببینید:

• پیکربندی کردن ساخت
• مرجع DSL افزایه Android Gradle
• مرجع Gradle DSL
• راهنمای کاربر عملکرد Gradle

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

android skills add agp-9-upgrade

به‌روزرسانی افزایه Android Gradle

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

می‌توانید نسخه افزایه را در منو فایل > ساختار پروژه > پروژه در «استودیو Android» یا فایل build.gradle.kts سطح بالا مشخص کنید. نسخه افزونه برای همه ماژول‌های ساخته‌شده در آن پروژه Android Studio اعمال می‌شود. مثال زیر افزونه را روی نسخه ۹.۵.۰ از فایل build.gradle.kts تنظیم می‌کند:

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

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

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

اگر نسخه افزایه مشخص‌شده بارگیری نشده باشد، Gradle دفعه بعدی که پروژه‌تان را می‌سازید یا روی فایل > همگام‌سازی پروژه با فایل‌های Gradle در نوار منو «استودیو Android» کلیک می‌کنید، آن را بارگیری می‌کند.

به‌روزرسانی Gradle

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

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

می‌توانید نسخه Gradle را در منو فایل > ساختار پروژه > پروژه در «استودیو Android» مشخص کنید، یا نسخه Gradle را بااستفاده از خط فرمان به‌روز کنید. روش ترجیحی استفاده از ابزار خط فرمان Gradle Wrapper است که اسکریپت‌های gradlew را به‌روز می‌کند. مثال زیر نسخه Gradle را بااستفاده از Gradle Wrapper روی ۹.۶.۰ تنظیم می‌کند. توجه داشته باشید که باید این فرمان را دو بار اجرا کنید تا هم Gradle و هم Gradle Wrapper ارتقا یابد (برای اطلاعات بیشتر، به ارتقا دادن Gradle Wrapper مراجعه کنید).

gradle wrapper --gradle-version 9.6.0

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

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

سازگاری افزایه Android Gradle و «استودیو Android»

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

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

حداقل نسخه‌های ابزارها برای سطح میانای برنامه‌سازی کاربردی Android

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

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