به‌روزرسانی‌های Android Gradle plugin API

این صفحه موارد منسوخ شدن و حذف میانای برنامه‌سازی کاربردی افزایه Android Gradle (AGP) را ردیابی می‌کند و اطلاعاتی درباره نحوه به‌روزرسانی کدتان براساس آن ارائه می‌دهد.

ردیاب حذف و منسوخ شدن میانای برنامه‌سازی کاربردی

جدول زیر زمان منسوخ شدن و حذف شدن AGP API را ازنظر نسخه AGP خلاصه می‌کند.

API	منسوخ‌شده در نسخه AGP	از نسخه AGP برداشته شد
Component.setAsmFramesComputationMode	‫۲-۷
Component.transformClassesWith	‫۲-۷
RenderScript	‫۲-۷
تبدیل	‫۲-۷	۸.۰

AGP 8.12

افزایه Android Gradle نسخه ۸.۱۲.۰ حاوی تغییرات API قابل‌توجه زیر است.

تغییر رفتار: گزینه includeAndroidResources مانیفست را از فهرست راهنمای آزمایشی ادغام می‌کند

اکنون می‌توانید فایل AndroidManifest.xml را در فهرست راهنمای منبع آزمایشی‌تان ایجاد کنید تا مانیفست را برای آزمایش‌های واحد با گزینه android.testOptions.unitTests.includeAndroidResources سفارشی‌سازی کنید. فایل مانیفست آزمایشی با مانیفست اصلی برنامه ادغام خواهد شد. مشکل شماره ۱۲۷۹۸۶۴۵۸

AGP 8.10

افزایه Android Gradle نسخه ۸.۱۰.۰ حاوی تغییرات قابل‌توجه زیر در میانای برنامه‌سازی کاربردی است.

تغییر مخرب در سطح منبع: finalizeDsl اکنون به استفاده از انواع پارامترشده نیاز دارد

برای اینکه AndroidComponentsExtension بتواند مستقیماً با افزونه com.android.kotlin.multiplatform.library استفاده شود، نوع محدودشده در finalizeDsl آسان‌تر شد.

برای مثال، اگر از انواع خام AndroidComponentsExtension برای پرداختن به برنامه‌ها و کتابخانه‌ها استفاده می‌کردید:

extensions.getByType(AndroidComponentsExtension::class).finalizeDsl { androidExtension ->
  androidExtension.experimentalProperties["android.example"] = true
}

باید کد منبع خود را قبل‌از ارتقا یا درحین آن با چیزی مثل این تطبیق دهید:

extensions.getByType<AndroidComponentsExtension<CommonExtension<*, *, *, *, *, *>, *, *>>().finalizeDsl { androidExtension ->
  androidExtension.experimentalProperties["android.example"] = true
}

توجه داشته باشید که اگر می‌خواهید کد finalizeDsl بنویسید که هم با افزونه‌های فعلی com.android.library و com.android.application و هم با افزونه جدید com.android.kotlin.multiplatform.library کار کند، ممکن است لازم باشد انواع را در زمان اجرا بررسی کنید:

extensions.getByType<AndroidComponentsExtension<*, *, *>>().finalizeDsl { androidExtension ->
  when(androidExtension) {
    is CommonExtension<*, *, *, *, *, *> -> androidExtension.experimentalProperties["android.example"] = true
    is KotlinMultiplatformAndroidLibraryExtension -> androidExtension.experimentalProperties["android.example"] = true
  }
}

این فقط یک تغییر ناسازگار در سطح منبع است و بر افزونه‌های دودویی تأثیری نخواهد گذاشت.

AGP 8.8

به‌روزرسانی‌های مهم میانای برنامه‌سازی کاربردی برای AGP 8.8 در زیر آمده است.

«پیکربندی‌های منبع» منسوخ شده است

پیکربندی‌های منبع از AGP 8.8 منسوخ شده‌اند. این کار به این دلیل انجام شد که AGP دیگر از تراکم‌های مختلف منابع پشتیبانی نمی‌کند و «کنسول Google Play» اکنون برنامه‌ها را ملزم می‌کند که به‌عنوان «دسته‌های برنامه» منتشر شوند. برای پیکربندی زبان، می‌توانید بااستفاده از localeFilters DSL، مکان‌هایی را که برنامه‌تان پشتیبانی می‌کند مشخص کنید تا پیکربندی‌های مکان را به منابع مربوطه نگاشت کنید.

AGP 8.0

به‌روزرسانی‌های مهم میانای برنامه‌سازی کاربردی برای AGP 8.0 در زیر آمده است.

Transform API برداشته شده است

با شروع AGP 8.0،‏ Transform API برداشته می‌شود. یعنی همه کلاس‌های موجود در بسته com.android.build.api.transform برداشته شده‌اند.

‫Transform API برای بهبود عملکرد ساخت درحال برداشته شدن است. پروژه‌هایی که از Transform API استفاده می‌کنند، AGP را مجبور می‌کنند تا از جریان کمتر بهینه‌شده‌ای برای ساخت استفاده کند که می‌تواند منجر به پس‌رفت‌های بزرگی در زمان‌های ساخت شود. همچنین استفاده از Transform API و ترکیب آن با دیگر ویژگی‌های Gradle دشوار است؛ هدف میاناهای برنامه‌سازی کاربردی جایگزین این است که توسعه AGP را بدون ایجاد مشکلات عملکرد یا صحت ساخت آسان‌تر کنند.

میاناهای برنامه‌سازی کاربردی جایگزین

هیچ جایگزین واحدی برای Transform API وجود ندارد—میاناهای برنامه‌سازی کاربردی جدید و هدفمندی برای هر مورد استفاده وجود دارد. همه میاناهای برنامه‌سازی کاربردی جایگزین در بلوک androidComponents {} قرار دارند. همه این میاناهای برنامه‌سازی کاربردی ازطریق AGP 7.2 دردسترس هستند.

پشتیبانی از تبدیل بایت‌کد

برای تبدیل بایت‌کد، از Instrumentation API استفاده کنید. برای کتابخانه‌ها، می‌توانید ابزار دقیق را فقط برای کلاس‌های پروژه محلی ثبت کنید؛ برای برنامه‌ها و آزمایش‌ها، می‌توانید انتخاب کنید که ابزار دقیق را فقط برای کلاس‌های محلی یا همه کلاس‌ها، ازجمله وابستگی‌های محلی و ازراه‌دور، ثبت کنید. برای استفاده از این میانای برنامه‌سازی کاربردی، ابزار به‌طور مستقل در هر کلاس اجرا می‌شود و دسترسی محدودی به دیگر کلاس‌ها در classpath دارد (برای اطلاعات بیشتر، createClassVisitor() را ببینید). این محدودیت عملکرد ساخت‌های کامل و افزایشی را بهبود می‌بخشد و سطح API را ساده نگه می‌دارد. هر کتابخانه به‌محض آماده شدن به‌صورت موازی ابزاربندی می‌شود، نه پس‌از تکمیل شدن کل فرایند کامپایل. علاوه‌براین، تغییر در یک کلاس واحد به این معنی است که فقط کلاس‌های تحت‌تأثیر قرارگرفته باید در ساخت افزایشی مجدداً ابزارگذاری شوند. برای نمونه‌ای از نحوه استفاده از Instrumentation API، به دستورالعمل AGP تبدیل کلاس‌ها با ASM مراجعه کنید.

پشتیبانی از افزودن کلاس‌های تولیدشده به برنامه

برای افزودن کلاس‌های تولیدشده بیشتر به برنامه، از میانای برنامه‌سازی کاربردی مصنوعات با MultipleArtifact.ALL_CLASSES_DIRS استفاده کنید. به‌طور خاص، از

artifacts.use(TaskProvider)
  .wiredWith(...)
  .toAppend(Artifact.Multiple)

با MultipleArtifact.ALL_CLASSES_DIRS برای افزودن دایرکتوری‌های تولیدشده اضافی به کلاس‌های پروژه. Artifacts API به‌طور خودکار مکان منحصربه‌فردی را برای خروجی تکلیف سفارشی شما انتخاب می‌کند. برای دیدن نمونه‌ای از نحوه استفاده از این API، دستورالعمل addToAllClasses را ببینید.

پشتیبانی از تبدیل‌ها براساس تجزیه‌وتحلیل کل برنامه

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

برای ثبت کردن تکلیفی که همه کلاس‌ها را باهم تبدیل می‌کند، افزایه Android Gradle نسخه ۷.۴ میانای برنامه‌سازی کاربردی Artifacts.forScope را معرفی می‌کند. برای تبدیل کردن همه کلاس‌ها در پروژه فعلی، از Artifacts.forScope.PROJECT استفاده کنید. برای تبدیل همه کلاس‌ها در پروژه فعلی، پروژه‌های واردشده، و همه وابستگی‌های خارجی، از Artifacts.forScope.ALL استفاده کنید. کد زیر نحوه استفاده از Artifacts.forScope.ALL را برای ثبت تکلیفی که همه کلاس‌ها را باهم تبدیل می‌کند نشان می‌دهد:

variant.artifacts.forScope(ScopedArtifacts.Scope.ALL)
    .use(taskProvider)
    .toTransform(
        ScopedArtifact.CLASSES,
        ModifyClassesTask::allJars,
        ModifyClassesTask::allDirectories,
        ModifyClassesTask::output,
    )

برای دیدن نمونه‌ای از نحوه استفاده از این API، به دستورالعمل modifyProjectClasses مراجعه کنید و برای دیدن نمونه‌ای از نحوه ثبت افزونه‌های سفارشی در انواع ساخت Android، به دستورالعمل customizeAgpDsl مراجعه کنید.

اگر مورد استفاده شما تحت پوشش هیچ‌یک از میاناهای برنامه‌سازی کاربردی AndroidComponents نیست، می‌توانید اشکالی را ثبت کنید.

چند افزونه پرکاربرد قبلاً برای استفاده از این میاناهای برنامه‌سازی کاربردی جدید منتقل شده‌اند، ازجمله افزونه پایشگر کارایی Firebase (نسخه ۱.۴.۱ با AGP 8.0 سازگار است) و افزونه Hilt Gradle (نسخه ۲.۴۰.۱ با AGP 8.0 سازگار است). «دستیار ارتقا» AGP همچنین به توسعه‌دهندگان پروژه کمک می‌کند افزایه‌های پرکاربرد را درصورت نیاز ارتقا دهند.

اگر از Transform API ازطریق افزونه شخص ثالث استفاده می‌کنید، می‌توانید به نویسنده اطلاع دهید که افزونه او باید به‌روزرسانی شود تا با API جدید برای AGP 8.0 کار کند.

AGP 7.2

به‌روزرسانی‌های مهم میانای برنامه‌سازی کاربردی برای AGP 7.2 در زیر آمده است.

RenderScript منسوخ شده است

از AGP 7.2، میاناهای برنامه‌سازی کاربردی RenderScript منسوخ شده‌اند. این APIها همچنان کار خواهند کرد اما هشدار فراخوانی می‌کنند و در نسخه‌های آینده AGP به‌طور کامل برداشته خواهند شد. برای راهنمایی درباره نحوه انتقال از RenderScript، به انتقال از RenderScript مراجعه کنید.

‫Component.transformClassesWith و Component.setAsmFramesComputationMode منسوخ شده‌اند

از AGP 7.2 به بعد، میاناهای برنامه‌سازی کاربردی ابزارسازی بایت‌کد کلاس Component.transformClassesWith و Component.setAsmFramesComputationMode منسوخ شده‌اند. این متدها به بلوک جدیدی به نام Component.instrumentation منتقل شده‌اند که شامل همه میاناهای برنامه‌سازی کاربردی مربوط به پیکربندی فرایند ابزارسازی است. برای ادامه استفاده از این ویژگی‌های ابزار دقیق، به‌جای آن از APIهای مربوطه در بلوک جدید استفاده کنید، همان‌طور که در تکه‌کد زیر نشان داده شده است:

androidComponents {
      onVariants(selector().all(), {
          instrumentation.transformClassesWith(AsmClassVisitorFactoryImpl.class,
                                               InstrumentationScope.Project) { params ->
              params.x = "value"
          }
          instrumentation.setAsmFramesComputationMode(
              COMPUTE_FRAMES_FOR_INSTRUMENTED_METHODS
          )
      })
  }