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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

gradle wrapper --gradle-version 8.13

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

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

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

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

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

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

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

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

تغییرات نسخه‌بندی (نوامبر ۲۰۲۰)

ما در حال به‌روزرسانی شماره‌گذاری نسخه برای افزونه اندروید گریدل (AGP) هستیم تا با ابزار ساخت گریدل که در زیر آن قرار دارد، مطابقت بیشتری داشته باشد.

در اینجا تغییرات قابل توجه آمده است:

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

• هر ساله یک نسخه اصلی از AGP منتشر خواهد شد که با نسخه اصلی Gradle همسو است.

• نسخه پس از AGP 4.2، نسخه ۷.۰ خواهد بود و نیاز به ارتقاء به نسخه Gradle 7.x دارد. هر نسخه اصلی AGP نیاز به ارتقاء نسخه اصلی در ابزار Gradle اصلی دارد.

• APIها تقریباً یک سال قبل منسوخ می‌شوند و قابلیت‌های جایگزین همزمان در دسترس قرار می‌گیرند. APIهای منسوخ‌شده تقریباً یک سال بعد در طول به‌روزرسانی بزرگ بعدی حذف خواهند شد.

سازگاری

حداکثر سطح API که افزونه اندروید Gradle نسخه ۸.۱۳ پشتیبانی می‌کند، سطح API ۳۶ است. در اینجا اطلاعات سازگاری دیگری نیز وجود دارد:

مشکلات برطرف شده

افزونه اندروید گریدل ۸.۱۳.۰