خط زمان انتقال DSL/API افزایه Android Gradle

«افزونه Gradle برای Android»‏ (AGP) سیستم ساخت پشتیبانی‌شده برای برنامه‌های Android است و از کامپایل کردن انواع مختلف منابع و پیوند دادن آن‌ها به یکدیگر در برنامه‌ای که می‌توانید در دستگاه Android فیزیکی یا شبیه‌ساز اجرا کنید پشتیبانی می‌کند.

بخش زیر تکامل برنامه‌ریزی‌شده DSL و API مربوط به AGP را شرح می‌دهد. با معرفی میاناهای برنامه‌سازی کاربردی جدید در نسخه‌های پایدار، میاناهای برنامه‌سازی کاربردی قدیمی به‌عنوان منسوخ‌شده علامت‌گذاری خواهند شد. سپس آن میاناهای برنامه‌سازی کاربردی منسوخ‌شده در نسخه پایدار بعدی غیرقابل‌دسترس خواهند شد. بخش‌های زیر اطلاعاتی درباره تغییرات آتی در هر نسخه اصلی AGP ارائه می‌دهند.

برای گزارش دقیق‌تر از منسوخ شدن یا حذف میانای برنامه‌سازی کاربردی AGP، به به‌روزرسانی‌های میانای برنامه‌سازی کاربردی AGP مراجعه کنید.

AGP 10.0 (اواخر ۲۰۲۶)

تغییرات و مدرن‌سازی میانای برنامه‌سازی کاربردی «افزایه Android Gradle» نسخه ۱۰.۰

AGP 10.0 انتقال به مدل ساخت کاملاً تنبل و سازگار با حافظه پنهان پیکربندی را تکمیل می‌کند. این نسخه پخش اوج تلاش چندساله برای جایگزین کردن میاناهای برنامه‌سازی کاربردی قدیمی و غیرتنبل با معماری ایمن‌تر و کارآمدتر است.

چرا مدل ساخت تنبل؟

In the legacy, non-lazy build model, Gradle eagerly evaluates objects, queries variant data, and configures tasks across all project modules during every sync or build invocation. این ارزیابی مشتاقانه زمان واحد پردازش مرکزی و حافظه را برای انواع و تکالیفی که درحال اجرا نیستند هدر می‌دهد و باعث تداخل ترتیب ارزیابی در اسکریپت‌های ساخت پیچیده می‌شود.

با انتقال به مدل ساخت کاملاً تنبل بااستفاده از ارائه‌دهندگان تنبل (Provider<T>) و Variant API مدرن (androidComponents {})، ویژگی‌ها و سیم‌کشی تکلیف به‌صورت تنبل و درصورت درخواست فقط زمانی محاسبه می‌شوند که نمودار اجرای ساخت فعال به آن‌ها نیاز داشته باشد.

میاناهای برنامه‌سازی کاربردی قدیمی که در این نسخه برداشته می‌شوند، اساساً با این معماری مدرن ناسازگار بودند. برداشتن آن‌ها به AGP امکان می‌دهد تا به‌طور کامل از «حافظه نهان پیکربندی Gradle» و «جداسازی پروژه» پشتیبانی کند، که به‌شدت سرعت ساخت و زمان همگام‌سازی را در «استودیو Android» بهبود می‌بخشد.

تفاوت معماری اصلی

BaseVariant API قدیمی (applicationVariants.all {}) مشتاق و وظیفه‌محور بود. این افزایه به توسعه‌دهندگان دسترسی مستقیم به وظایف Gradle و پیکربندی‌های داخلی درطول فاز پیکربندی می‌داد که ذاتاً ویژگی‌های عملکردی Gradle مدرن را مختل می‌کند.

Variant API جدید (androidComponents {}) تنبل و مصنوع‌محور است. این نسخه به‌طور گسترده از Property API متعلق به Gradle استفاده می‌کند و همه ارجاع‌ها به Task و TaskProvider را به‌طور کامل حذف می‌کند و شما را ملزم می‌کند به‌جای خودِ کارهای اساسی، به‌طور تمیز با ورودی‌ها و خروجی‌ها (Variant.artifacts) تعامل داشته باشید.

چه چیزی برداشته و جایگزین می‌شود

همه میاناهای قبلی و کلاس‌های استفاده‌شده در DSL قدیمی و Variant API قدیمی حذف شده‌اند. برای آماده‌سازی دستورگان ساخت و افزایه‌های سفارشی، از میاناهای برنامه‌سازی کاربردی و پرچم‌های پایان عمر زیر به نسخه‌های به‌روز انتقال دهید:

میانای برنامه‌سازی کاربردی یا ویژگی برداشته‌شده تعویض یا اقدام لازم است
دسترسی مستقیم به تکلیف:
  • getJavaCompile()
  • getMergeResourcesProvider()
  • getAssembleProvider()
میانای برنامه‌سازی کاربردی Artifacts: به‌جای واکشی تکلیف برای تغییر رفتار آن، از variant.artifacts برای افزودن، اصلاح، یا جایگزین کردن فایل‌های واقعی (Artifacts) که بین تکالیف ردوبدل می‌شوند استفاده کنید.
ثبت منبع مشتاق:
  • registerJavaGeneratingTask()
  • registerResGeneratingTask()
میانای برنامه‌سازی کاربردی Sources: دایرکتوری خروجی تکلیف سفارشی‌تان را بااستفاده از variant.sources.java.addGeneratedSourceDirectory(...) سیم‌کشی کنید.
دسترسی به پیکربندی / مسیر کلاس:
  • getCompileConfiguration()
  • getCompileClasspath()
Instrumentation API: برای اصلاح یا بازرسی بایت‌کد (رایج‌ترین مورد استفاده برای دسترسی به classpath)، از variant.instrumentation.transformClassesWith(...) بااستفاده از AsmClassVisitorFactory استفاده کنید.
جهش خصوصیت مشتاق:
  • buildConfigField()
  • resValue()
نمونه‌های Lazy `MapProperty`: از variant.buildConfigFields.put(...) و variant.manifestPlaceholders.put(...) استفاده کنید.
پرچم‌های انصراف:
  • android.newDsl
  • android.builtInKotlin
جایگزین مستقیمی وجود ندارد. این پرچم‌ها را از gradle.properties بردارید؛ DSL مدرن و Kotlin داخلی به‌شدت اعمال می‌شوند.
افزونه‌های Legacy Variant API:
  • applicationVariants
  • libraryVariants
  • testVariants
  • unitTestVariants
جایگزینی با androidComponents.onVariants().
فیلتر کردن متغیر (variantFilter بلوک) بااستفاده از انتخابگرهای گوناگونی، با androidComponents.beforeVariants() جایگزین کنید.
مؤلفه‌های SDK و NDK:
  • sdkDirectory
  • ndkDirectory
  • bootClasspath
  • adbExecutable
بااستفاده از androidComponents.sdkComponents به مؤلفه‌های کیت توسعه نرم‌افزار دسترسی پیدا کنید.
محیط‌های آزمایشی:
  • deviceProvider
  • testServer
انتقال ثبت دستگاه آزمایشی سفارشی به دستگاه‌های تحت مدیریت Gradle.
میاناهای برنامه‌سازی کاربردی ثبت منسوخ‌شده:
  • registerArtifactType
  • registerBuildTypeSourceProvider
  • registerProductFlavorSourceProvider
  • registerJavaArtifact
  • registerMultiFlavorSourceProvider
  • wrapJavaSourceSet
بدون جایگزینی مستقیم حذف شد.
Transform API تبدیل‌ها را با Artifacts API و AsmClassVisitorFactory جایگزین می‌کند.

برای دسترسی به همه میاناهای برنامه‌سازی کاربردی جایگزین DSL و Variant (androidComponents {}) میانجی‌ها و کلاس‌ها، همیشه از gradle-api مصنوع هنگام توسعه افزایه‌های Gradle سفارشی یا منطق ساخت استفاده کنید.

مراحل انتقال

برای کمک به ارتقای یکپارچه و قابل‌پیش‌بینی به AGP 10.0، این شیوه‌های انتقال را دنبال کنید:

  1. اجرای AGP Upgrade Assistant: قبل‌از ارتقای مستقیم به نسخه ۱۰.۰، AGP Upgrade Assistant رسمی را در Android Studio (Tools > AGP Upgrade Assistant) اجرا کنید. این ابزار چندین انتقال رایج DSL و اسکریپت ساخت را خودکار می‌کند و به حفظ رفتارهای ساخت موجود کمک می‌کند.
  2. استفاده از مهارت‌های «حالت عامل» در «استودیو Android»: از مهارت‌های ارتقای هوش مصنوعی (مانند مهارت‌های ارتقای AGP موجود در مخزن مهارت‌های Android) برای خودکارسازی و ساده‌سازی انتقال منطق ساخت پیچیده و DSLها در «استودیو Android» استفاده کنید.
  3. ابتدا هشدارهای منسوخ شدن را در AGP 9.x برطرف کنید: پروژه خود را به جدیدترین نسخه AGP 9.x ارتقا دهید و همه هشدارهای منسوخ شدن موجود را برطرف کنید. وقتی پروژه‌تان با نسخه 9.x بدون هشدار و بدون اتکا به android.newDsl=false یا android.builtInKotlin=false کار کند، انتقال به نسخه ۱۰٫۰ به‌راحتی انجام خواهد شد.
  4. افزایه‌های Gradle طرف سوم را ممیزی کنید: مطمئن شوید افزایه‌های طرف سوم به نسخه‌های سازگار با AGP 10.0 ارتقا یافته باشند. افزایه‌هایی که هنوز به انواع افزونه‌های قدیمی متکی هستند باعث خرابی ساخت می‌شوند، مانند ClassCastException: ... cannot be cast to class BaseExtension.
  5. از دستورالعمل‌های رسمی انتقال استفاده کنید: برای مثال‌های پیچیده و واقعی انتقال و مقایسه‌های پهلوبه‌پهلو، به مخزن رسمی gradle-recipes GitHub مراجعه کنید.

در اینجا مقایسه قبل و بعد نشان می‌دهد که چگونه از پرس‌وجوی مشتاقانه انواع قدیمی به پیکربندی تنبل انواع بااستفاده از androidComponents {} مهاجرت کنید:

قبل‌از: Legacy Variant API (در AGP 10.0 برداشته شده است)

// Eager evaluation using the legacy Variant API
android {
    applicationVariants.all { variant ->
        if (variant.buildType.name == "release") {
            // Eagerly queries and modifies properties during evaluation
        }
    }
}

بعداز: Modern Variant API (androidComponents {})

// Lazy, Configuration Cache compatible Variant API
androidComponents {
    onVariants(selector().withBuildType("release")) { variant ->
        // Safely and lazily configures properties
    }
}

نحوه آزمایش کردن رفتار AGP 10.0 در AGP 9.x

برای شروع آزمایش رفتارهای ساخت AGP 10.0 و اعتبارسنجی سازگاری آن، لازم نیست منتظر انتشار آن باشید. هنگام اجرا در هر نسخه AGP 9.x، می‌توانید با تأیید اینکه gradle.properties شما هرگونه انصراف را غیرفعال می‌کند و پرچم‌های رفتار سخت‌گیرانه زیر را تنظیم می‌کند، رفتار AGP 10.0 را به‌طور صریح اعمال کنید:

# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true

# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true

با اعمال android.newDsl=true و android.builtInKotlin=true، می‌توانید تأیید کنید که منطق ساخت سفارشی و افزایه‌های طرف سوم شما کاملاً با الزامات سخت‌گیرانه میانای برنامه‌سازی کاربردی AGP 10.0 سازگار هستند.

انصراف دادن از زیرپروژه انتخابی درطول انتقال

اگر می‌خواهید android.newDsl=true را به‌طور سراسری در پروژه‌تان فعال کنید تا رفتارهای مدرن را آزمایش کنید، اما برای انتقال زیرپروژه‌های خاص به زمان بیشتری نیاز دارید، می‌توانید از AGP 9.4.0-alpha04 به‌طور انتخابی از ماژول‌های تکی انصراف دهید. افزودن android.newDsl.optOut به gradle.properties با مشخص کردن مسیرهای پروژه:

# Enable modern DSL globally across the build
android.newDsl=true

# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib

Selective built-in Kotlin disablement per module

اگر می‌خواهید Kotlin داخلی را به‌طور سراسری در پروژه‌تان فعال کنید (android.builtInKotlin=true)، اما برای انتقال زیرپروژه‌های خاص از kotlin-android (یا برای پیمانه‌های بدون کد Kotlin) به زمان بیشتری نیاز دارید، آن پیمانه‌ها را به‌جای سطح پروژه در سطح DSL پیکربندی کنید. ‫enableKotlin = false را در فایل ساخت واحد تنظیم کنید:

android {
    enableKotlin = false
}

گردش کار بازخورد و گزارش اشکال

می‌خواهیم مطمئن شویم Variant API جدید از موارد استفاده موردنیاز شما پشتیبانی می‌کند. اگر در انتقال از میاناهای برنامه‌سازی کاربردی قدیمی با مانعی مواجه شدید که Variant API جدید نمی‌تواند مورد استفاده شما را برآورده کند، این مراحل را برای ارائه بازخورد دنبال کنید:

  1. بررسی موارد موجود: ابتدا اشکال ردیابی سراسری AGP 10.0 Variant API را بررسی کنید تا ببینید آیا مسدودکننده انتقال شما ازقبل شناخته شده است یا نه، و به مشکل رأی مثبت دهید.
  2. گزارش کردن میاناهای برنامه‌سازی کاربردی مفقود: اگر مورد استفاده شما منحصربه‌فرد است، بااستفاده از الگوی AGP 10.0 خاص ما درخواست ویژگی جدیدی ثبت کنید تا بتوانیم بررسی کنیم و به شما کمک کنیم.

(آزمایشی) دسترسی به کلاس‌های AGP داخلی خصوصی برداشته شده است

وابستگی به آرتیفکت gradle اکنون همه کلاس‌های داخلی را پنهان می‌کند و دسترسی کامپایل را فقط به رابط‌ها و کلاس‌های موجود در آرتیفکت gradle-api می‌دهد. این امر بر کامپایل افزونه تأثیر می‌گذارد.

امکان افزودن دستی وابستگی برای دسترسی به کلاس‌های داخلی وجود ندارد.

AGP 9.0 (ژانویه ۲۰۲۶)

«میاناهای برنامه‌سازی کاربردی» Variant جدید پایدار هستند، «میاناهای برنامه‌سازی کاربردی» قدیمی منسوخ شده‌اند

Variant APIs که در نسخه‌های ۴.۱ و ۴.۲ درحال توسعه بودند، اکنون پایدار هستند و در آرتیفکت gradle-api قرار دارند. میاناهای قبلی و کلاس‌های استفاده‌شده در Variant API قدیمی اکنون منسوخ شده‌اند و برای استفاده به موافقت صریح نیاز دارند.

میاناهای DSL جدید پایدار هستند، میاناهای قدیمی منسوخ شده‌اند

میاناهای DSL که در نسخه‌های ۴.۱، ۴.۲، و ۷.۰ درحال توسعه بودند اکنون پایدار هستند و در آرتیفکت gradle-api قرار دارند. رابط‌ها و کلاس‌های قبلی استفاده‌شده در DSL اکنون منسوخ شده‌اند و برای استفاده به موافقت صریح نیاز دارند.

کلاس‌های AGP داخلی خصوصی همچنان دردسترس است

کلاس‌های داخلی خصوصی از AGP، که در سایر آرتیفکت‌ها قرار دارند، همچنان درطول کامپایل کردن افزایه‌ها و فایل‌های ساخت دردسترس هستند، اما استفاده از آن‌ها را توصیه نمی‌کنیم زیرا ممکن است در هر زمانی به‌طور مخرب تغییر کنند.