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

این صفحه حاوی یادداشت‌های انتشار برای نسخه‌های پیش‌نمایش پلاگین Android Gradle (AGP) است.

پلاگین اندروید Gradle 9.0

پلاگین Android Gradle 9.0 نسخه اصلی جدید AGP است و تغییرات API و رفتار را به همراه دارد.

برای به روز رسانی به پلاگین Android Gradle 9.0.0-alpha10 از افزونه Android Gradle Upgrade Assistant در Android Studio Otter استفاده کنید | 2025.2.1.

دستیار ارتقاء AGP به حفظ رفتارهای موجود هنگام ارتقاء پروژه در صورت لزوم کمک می کند و به شما امکان می دهد پروژه خود را برای استفاده از AGP 9.0 ارتقا دهید، حتی اگر آماده پذیرش همه پیش فرض های جدید در AGP 9.0 نباشید.

سازگاری

حداکثر سطح API Android که افزونه Android Gradle 9.0.0-alpha10 پشتیبانی می کند، سطح API 36 است.

افزونه Android Gradle 9.0.0-alpha10 به Gradle 9.0.0 نیاز دارد.

کلاس‌های DSL android اکنون فقط رابط‌های عمومی جدید را پیاده‌سازی می‌کنند

در طول چندین سال گذشته، ما رابط‌های جدیدی را برای DSL و API خود معرفی کرده‌ایم تا بهتر کنترل کنیم کدام APIها عمومی هستند. نسخه‌های AGP 7.x و 8.x هنوز از انواع قدیمی DSL (به‌عنوان مثال BaseExtension ) استفاده می‌کردند که رابط‌های عمومی جدید را نیز پیاده‌سازی می‌کردند تا با پیشرفت کار روی اینترفیس‌ها، سازگاری را حفظ کنند.

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

برای به روز رسانی به AGP 9.0، ممکن است لازم باشد موارد زیر را انجام دهید:

• اطمینان حاصل کنید که پروژه شما با Kotlin داخلی سازگار است: افزونه org.jetbrains.kotlin.android با DSL جدید سازگار نیست.

• پروژه های KMP را به پلاگین کتابخانه Android Gradle برای KMP تغییر دهید: استفاده از افزونه org.jetbrains.kotlin.multiplatform در همان پروژه فرعی Gradle به عنوان افزونه های com.android.library و com.android.application با DSL جدید سازگار نیست.

• فایل‌های ساخت خود را به‌روزرسانی کنید: در حالی که تغییر رابط‌ها به منظور حفظ DSL تا حد امکان مشابه است، ممکن است تغییرات کوچکی رخ دهد.

• منطق ساخت سفارشی خود را برای ارجاع به DSL و API جدید به روز کنید: هر ارجاعی به DSL داخلی را با رابط های DSL عمومی جایگزین کنید. در بیشتر موارد این جایگزینی یک به یک خواهد بود. هر گونه استفاده از applicationVariants و API های مشابه را با androidComponents API جدید جایگزین کنید. این ممکن است پیچیده تر باشد، زیرا androidComponents API به گونه ای طراحی شده است که پایدارتر باشد تا افزونه ها را برای مدت طولانی تری سازگار نگه دارد. برای نمونه دستور العمل های Gradle ما را بررسی کنید.

• به‌روزرسانی افزونه‌های شخص ثالث: برخی از افزونه‌های شخص ثالث ممکن است همچنان به رابط‌ها یا APIهایی وابسته باشند که دیگر در معرض نمایش نیستند. به نسخه هایی از آن پلاگین هایی که با AGP 9.0 سازگار هستند مهاجرت کنید.

تغییر به رابط های DSL جدید از پلاگین ها و اسکریپت های ساخت Gradle با استفاده از API های منسوخ مختلف جلوگیری می کند، از جمله:

androidComponents {
    onVariants() { variant ->
        variant.signingConfig
            .enableV1Signing.set(false)
    }
}

androidComponents {
    beforeVariants(
        selector()
            .withBuildType("debug")
            .withFlavor("color", "blue")
    ) { variantBuilder ->
        variantBuilder.enable = false
    }
  }

اگر به AGP 9.0 به روز رسانی کنید و پیام خطای زیر را مشاهده کنید، به این معنی است که پروژه شما هنوز به برخی از انواع قدیمی ارجاع می دهد:

java.lang.ClassCastException: class com.android.build.gradle.internal.dsl.ApplicationExtensionImpl$AgpDecorated_Decorated
cannot be cast to class com.android.build.gradle.BaseExtension

اگر توسط افزونه‌های شخص ثالث ناسازگار مسدود شده‌اید، می‌توانید انصراف دهید و پیاده‌سازی‌های قدیمی را برای DSL و همچنین نسخه قدیمی API را پس بگیرید. در حین انجام این کار، رابط های جدید نیز در دسترس هستند، و همچنان می توانید منطق ساخت خود را به API جدید به روز کنید. برای انصراف، این خط را در فایل gradle.properties خود قرار دهید:

android.newDsl=false

همچنین می توانید قبل از ارتقاء به AGP 9.0 ارتقاء به API های جدید را شروع کنید. رابط های جدید برای بسیاری از نسخه های AGP وجود داشته است و بنابراین می توانید ترکیبی از جدید و قدیمی داشته باشید. اسناد مرجع AGP API سطح API را برای هر نسخه AGP و زمانی که هر کلاس، متد و فیلد اضافه شده است را نشان می دهد.

در طول مرحله آلفای 9.0، با نویسندگان افزونه ها تماس می گیریم تا به آنها کمک کنیم تا پلاگین هایی را که کاملاً با حالت های جدید سازگار هستند، تطبیق داده و منتشر کنند، و دستیار ارتقاء AGP را در Android Studio بهبود می بخشد تا شما را در انتقال راهنمایی کند.

اگر متوجه شدید که DSL یا Variant API جدید قابلیت ها یا ویژگی هایی ندارد، لطفاً در اسرع وقت مشکل خود را مطرح کنید.

کاتلین داخلی

افزونه Android Gradle 9.0 شامل پشتیبانی داخلی از کامپایل Kotlin است که جایگزین افزونه Kotlin به طور جداگانه اعمال شده است. این امر ادغام با AGP را ساده می کند، از استفاده از API های منسوخ اجتناب می کند و در برخی موارد عملکرد را بهبود می بخشد.

افزونه اندروید Gradle 9.0 به پلاگین Kotlin Gradle 2.2.10 وابستگی زمان اجرا دارد که حداقل نسخه مورد نیاز برای پشتیبانی داخلی کاتلین است.

کاتلین داخلی در AGP 9.0 پشتیبانی کامل از Android Studio IDE را برای تجهیزات تست به ارمغان می آورد. برای امتحان این، از AGP 9.0.0-alpha07 یا جدیدتر استفاده کنید.

می‌توانید با تنظیم android.builtInKotlin=false از Kotlin داخلی انصراف دهید.

اگر از Kotlin داخلی انصراف داده اید و همچنین نیاز به استفاده از نسخه قدیمی پلاگین Kotlin Gradle دارید، می توانید به اجبار آن را کاهش دهید:

buildscript {
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("2.0.0") } // or another version that you want to use
        }
    }
}

تغییر رفتار

پلاگین Android Gradle 9.0 دارای رفتارهای جدید زیر است:

AGP 9.0 شامل به‌روزرسانی‌های پیش‌فرض ویژگی‌های Gradle زیر است. این به شما این امکان را می دهد که رفتار AGP 8.13 را هنگام ارتقاء حفظ کنید:

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

ویژگی های حذف شده

پلاگین Android Gradle 9.0 عملکرد زیر را حذف می کند:

• پشتیبانی از اپلیکیشن Wear OS جاسازی شده
  AGP 9.0 پشتیبانی از جاسازی برنامه‌های Wear OS را که دیگر در Play پشتیبانی نمی‌شوند، حذف می‌کند. این شامل حذف پیکربندی‌های wearApp و AndroidSourceSet.wearAppConfigurationName DSL می‌شود. برای نحوه انتشار برنامه خود در Wear OS به توزیع در Wear OS مراجعه کنید.
• androidDependencies و sourceSets گزارش وظیفه

DSL تغییر کرد

پلاگین Android Gradle 9.0 دارای تغییرات شکسته DSL زیر است:

• پارامترسازی CommonExtension حذف شده است.

  به خودی خود، این فقط یک تغییر شکستن سطح منبع برای کمک به جلوگیری از تغییرات شکستن سطح منبع در آینده است، اما همچنین به این معنی است که روش‌های بلوک باید از CommonExtension به ApplicationExtension ، LibraryExension ، DynamicFeatureExtension و TestExtension منتقل شوند.

  هنگام ارتقای پروژه خود به AGP 9.0، کد پلاگین Gradle را که از آن پارامترها یا روش های بلوک استفاده می کند، تغییر دهید. به عنوان مثال، افزونه زیر برای حذف پارامتر نوع و عدم تکیه بر روش های بلوک حذف شده به روز می شود:

  AGP 8.13

  val commonExtension: CommonExtension<*, *, *, *, *, *> =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig {
          minSdk {
              version = release(28)
          }
      }
  }
  

  AGP 9.0

  val commonExtension: CommonExtension =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig.apply {
          minSdk {
              version = release(28)
          }
      }
  }
  

  برای پلاگین هایی که طیف وسیعی از نسخه های AGP را هدف قرار می دهند، استفاده مستقیم از گیرنده با نسخه های AGP کمتر از 9.0 باینری سازگار است.

DSL حذف شد

پلاگین Android Gradle 9.0 حذف می کند:

• AndroidSourceSet.jni ، زیرا کاربردی نبود.

• AndroidSourceSet.wearAppConfigurationName ، زیرا مربوط به پشتیبانی از برنامه Wear OS جاسازی شده حذف شده است.

• BuildType.isRenderscriptDebuggable ، زیرا کاربردی نبود.

• DependencyVariantSelection . با DependencySelection جایگزین شده است که به صورت kotlin.android.localDependencySelection در معرض نمایش قرار می گیرد.

• Installation.installOptions(String) . با ویژگی تغییرپذیر Installation.installOptions جایگزین شده است.

• بلوک PostProcessing آزمایشی، اما هرگز تثبیت نشده است.

• ProductFlavor.setDimension که با ویژگی dimension جایگزین می شود

• LanguageSplitOptions که فقط برای Google Play Instant مفید بود که منسوخ شده است.

API های حذف شده

پلاگین Android Gradle 9.0 حذف می کند:

• AndroidComponentsExtension.finalizeDSl . با finalizeDsl جایگزین شده است

• Component.transformClassesWith . Instrumentation.transformClassesWith جایگزین آن شده است

• Component.setAsmFramesComputationMode . Instrumentation.setAsmFramesComputationMode جایگزین آن شده است

• ComponentBuilder.enabled ComponentBuilder.enable جایگزین آن شده است.

• DependenciesInfoBuilder.includedInApk . آیا با includeInApk جایگزین شده است

• DependenciesInfoBuilder.includedInBundle . آیا با includeInBundle جایگزین شده است

• GeneratesApk.targetSdkVersion . Is با targetSdk جایگزین شده است

• Variant.minSdkVersion . Is با minSdk جایگزین شده است

• Variant.maxSdkVersion . Is با maxSdk جایگزین می شود

• Variant.targetSdkVersion . Is با targetSdk جایگزین شده است

• Variant.unitTest ، زیرا برای افزونه com.android.test قابل اجرا نبود. unitTest در زیرگروه های VariantBuilder که HasUnitTest گسترش می دهد در دسترس است.

• VariantBuilder.targetSdk و targetSdkPreview ، زیرا در کتابخانه ها معنی نداشتند. به جای آن از GeneratesApkBuilder.targetSdk یا GeneratesApkBuilder.targetSdkPreview استفاده کنید.

• VariantBuilder.enableUnitTest ، زیرا برای افزونه com.android.test قابل اجرا نبود. enableUnitTest در زیرگروه های VariantBuilder که HasUnitTestBuilder گسترش می دهد در دسترس است.

• VariantBuilder.unitTestEnabled به نفع نام مستمر enableUnitTest در زیرگروه‌های VariantBuilder که HasUnitTestBuilder گسترش می‌دهند، حذف می‌شود.

• VariantOutput.enable . آیا با enabled جایگزین می شود

• FeaturePlugin و FeatureExtension منسوخ و غیرفعال شده است.

• APIهای BaseExtension.registerTransform منسوخ و غیرفعال شده، که فقط اجازه کامپایل در برابر آخرین نسخه AGP را می دهد، در حالی که در AGP 4.2 یا پایین تر اجرا می شود.

ویژگی های Gradle حذف شد

ویژگی‌های Gradle زیر ابتدا به‌عنوان راه‌هایی برای غیرفعال کردن ویژگی‌هایی که به‌طور پیش‌فرض فعال شده بودند، اضافه شدند.

این ویژگی‌ها به‌طور پیش‌فرض از نسخه AGP 8.0 یا پایین‌تر غیرفعال شده‌اند. این ویژگی‌ها را فقط در پروژه‌های فرعی فعال کنید که از آنها برای ساخت کارآمدتر استفاده می‌کنند.

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

ویژگی های Gradle اجباری

اگر ویژگی های Gradle زیر را تنظیم کنید AGP 9.0 خطا می دهد.

افزونه Android Gradle به‌روزرسانی دستیار پروژه‌هایی را که از این ویژگی‌ها استفاده می‌کنند به AGP 9.0 ارتقا نمی‌دهد.

مسائل رفع شد

پلاگین اندروید Gradle 9.0.0-alpha10

پلاگین اندروید Gradle 9.0.0-alpha09

پلاگین اندروید Gradle 9.0.0-alpha08

پلاگین اندروید Gradle 9.0.0-alpha07

پلاگین Android Gradle 9.0.0-alpha06

پلاگین اندروید Gradle 9.0.0-alpha05

پلاگین اندروید Gradle 9.0.0-alpha04

پلاگین اندروید Gradle 9.0.0-alpha03

پلاگین Android Gradle 9.0.0-alpha02

پلاگین Android Gradle 9.0.0-alpha01