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

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

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

برای خلاصه‌ای از تغییرات مهم آینده در افزونه‌ی اندروید گریدل، به نقشه راه افزونه‌ی اندروید گریدل مراجعه کنید.

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

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

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

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

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

شما می‌توانید نسخه افزونه را در منوی File > Project Structure > Project در اندروید استودیو یا فایل build.gradle.kts که در بالاترین سطح قرار دارد، مشخص کنید. نسخه افزونه برای همه ماژول‌های ساخته شده در آن پروژه اندروید استودیو اعمال می‌شود. مثال زیر افزونه را از فایل build.gradle.kts به نسخه 9.0 تنظیم می‌کند:

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

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

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

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

به‌روزرسانی گرادل

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

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

شما می‌توانید نسخه Gradle را در منوی File > Project Structure > Project در اندروید استودیو مشخص کنید، یا نسخه Gradle خود را با استفاده از خط فرمان به‌روزرسانی کنید. روش ترجیحی استفاده از ابزار خط فرمان Gradle Wrapper است که اسکریپت‌های gradlew را به‌روزرسانی می‌کند. مثال زیر نسخه Gradle را با استفاده از Gradle Wrapper به 9.1.0 تنظیم می‌کند. توجه داشته باشید، برای ارتقاء Gradle و خود Gradle Wrapper باید این دستور را دو بار اجرا کنید (برای اطلاعات بیشتر، به ارتقاء Gradle Wrapper مراجعه کنید).

gradle wrapper --gradle-version 9.1.0

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

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

سازگاری با افزونه‌ی اندروید گریدل و اندروید استودیو

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

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

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

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

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