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

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

افزونه اندروید گریدل ۹.۰

افزونه اندروید گریدل ۹.۰ یک نسخه جدید و بزرگ از AGP است و تغییرات API و رفتاری را به همراه دارد.

برای به‌روزرسانی به افزونه‌ی اندروید گریدل ۹.۰.۰-alpha11، از دستیار ارتقاء افزونه‌ی اندروید گریدل در اندروید استودیو Otter 2 Feature Drop | 2025.2.2 استفاده کنید.

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

سازگاری

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

افزونه اندروید Gradle نسخه 9.0.0-alpha11 به Gradle نسخه 9.0.0 نیاز دارد.

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

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

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

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

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

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

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

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

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

تغییر به رابط‌های DSL جدید، مانع از استفاده افزونه‌ها و اسکریپت‌های Gradle build از 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 و زمان اضافه شدن هر کلاس، متد و فیلد نشان می‌دهند.

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

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

کاتلین داخلی

افزونه اندروید گریدل ۹.۰ شامل پشتیبانی داخلی از کامپایل کاتلین است که جایگزین افزونه کاتلین جداگانه اعمال شده می‌شود. این امر ادغام با AGP را ساده می‌کند، از استفاده از APIهای منسوخ جلوگیری می‌کند و در برخی موارد عملکرد را بهبود می‌بخشد.

افزونه‌ی اندروید Gradle نسخه ۹.۰ در زمان اجرا به افزونه‌ی Kotlin Gradle نسخه ۲.۲.۱۰ وابسته است که حداقل نسخه مورد نیاز برای پشتیبانی داخلی از کاتلین است.

کاتلین داخلی در AGP 9.0 پشتیبانی کامل IDE اندروید استودیو را برای تست-فیکسچرها فراهم می‌کند. برای امتحان کردن این، از AGP 9.0.0-alpha07 یا بالاتر استفاده کنید.

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

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

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

تغییرات رفتاری

افزونه‌ی اندروید گریدل ۹.۰ رفتارهای جدید زیر را دارد:

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

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

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

افزونه‌ی اندروید گریدل ۹.۰ قابلیت‌های زیر را حذف می‌کند:

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

دی‌اس‌ال تغییر کرد

افزونه‌ی اندروید گریدل ۹.۰ تغییرات 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)
          }
      }
  }
  

  ای جی پی ۹.۰

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

  برای افزونه‌هایی که طیف وسیعی از نسخه‌های AGP را هدف قرار می‌دهند، استفاده مستقیم از getter با نسخه‌های AGP پایین‌تر از ۹.۰ سازگار است.

DSL حذف شد

افزونه‌ی اندروید گریدل ۹.۰ موارد زیر را حذف می‌کند:

• 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 های حذف شده

افزونه‌ی اندروید گریدل ۹.۰ موارد زیر را حذف می‌کند:

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

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

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

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

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

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

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

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

• Variant.maxSdkVersion . با maxSdk جایگزین شده است.

• Variant.targetSdkVersion . با 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 خطایی ایجاد می‌کند.

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

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

افزونه اندروید گریدل ۹.۰.۰-alpha10

افزونه اندروید گریدل ۹.۰.۰-alpha09

افزونه اندروید گریدل ۹.۰.۰-alpha08

افزونه اندروید گریدل ۹.۰.۰-alpha07

افزونه اندروید گریدل ۹.۰.۰-alpha06

افزونه اندروید گریدل ۹.۰.۰-alpha05

افزونه اندروید گریدل ۹.۰.۰-alpha04

افزونه اندروید گریدل ۹.۰.۰-alpha03

افزونه اندروید گریدل ۹.۰.۰-alpha02

افزونه اندروید گریدل ۹.۰.۰-alpha01