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

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

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

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

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

• پیکربندی ساخت
• مرجع زبان مدل‌سازی دامنه افزایه 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.4.0" apply false
    id("com.android.library") version "9.4.0" apply false
    id("org.jetbrains.kotlin.android") version "2.4.10" apply false
}

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

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

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

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

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

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

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

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 اضافه می‌کند. جدول زیر فهرست می‌کند که برای هر نسخه از Android Studio به کدام نسخه AGP نیاز است.

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

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

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

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