به روز رسانی API پلاگین Android Gradle

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

ردیاب حذف و حذف API

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

AGP 8.0

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

Transform API حذف شده است

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

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

API های جایگزین

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

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

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

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

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

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

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

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

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

برای ثبت وظیفه ای که همه کلاس ها را با هم تبدیل می کند، افزونه Android Gradle 7.4 API 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,
    )

دستور modifyProjectClasses را برای مثالی از نحوه استفاده از این API و دستور customizeAgpDsl را برای مثالی از نحوه ثبت پسوندهای سفارشی در انواع ساخت اندروید ببینید.

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

چندین پلاگین پرکاربرد قبلاً برای استفاده از این APIهای جدید مهاجرت کرده اند، از جمله افزونه نظارت بر عملکرد Firebase (1.4.1 با AGP 8.0 سازگار است) و پلاگین Hilt Gradle (2.40.1 با AGP 8.0 سازگار است). دستیار ارتقاء AGP همچنین به توسعه دهندگان پروژه کمک می کند تا پلاگین های معمولی را در صورت نیاز ارتقا دهند.

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

AGP 7.2

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

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

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

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

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

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