پلاگین Android Gradle 4.0.0 (آوریل 2020)

این نسخه از افزونه اندروید به موارد زیر نیاز دارد:

• Gradle 6.1.1 . برای کسب اطلاعات بیشتر، بخش مربوط به به‌روزرسانی Gradle را بخوانید.

• SDK Build Tools 29.0.2 یا بالاتر.

ویژگی های جدید

این نسخه از پلاگین اندروید Gradle شامل ویژگی های جدید زیر است.

پشتیبانی از Android Studio Build Analyzer

پنجره Build Analyzer به شما کمک می کند تا مشکلات مربوط به فرآیند ساخت خود را درک و تشخیص دهید، مانند بهینه سازی های غیرفعال و وظایفی که به درستی پیکربندی نشده اند. این ویژگی زمانی در دسترس است که از Android Studio نسخه 4.0 و بالاتر با افزونه Android Gradle نسخه 4.0.0 و بالاتر استفاده می کنید. می توانید پنجره Build Analyzer را از Android Studio به صورت زیر باز کنید:

1. اگر قبلاً این کار را نکرده‌اید، برنامه خود را با انتخاب Build > Make Project از نوار منو بسازید.
2. View > Tool Windows > Build را از نوار منو انتخاب کنید.
3. در پنجره Build ، پنجره Build Analyzer را به یکی از روش های زیر باز کنید:
   • پس از اتمام ساخت پروژه اندروید استودیو، روی تب Build Analyzer کلیک کنید.
   • پس از اتمام ساخت پروژه اندروید استودیو، روی پیوند در سمت راست پنجره Build Output کلیک کنید.

پنجره Build Analyzer مشکلات ساخت احتمالی را در درختی در سمت چپ سازماندهی می کند. برای بررسی جزئیات آن در پنل سمت راست می توانید هر موضوع را بررسی کرده و روی آن کلیک کنید. وقتی Android Studio ساخت شما را تجزیه و تحلیل می‌کند، مجموعه وظایفی را محاسبه می‌کند که مدت زمان ساخت را تعیین می‌کنند و تصویری را ارائه می‌کند تا به شما در درک تأثیر هر یک از این کارها کمک کند. همچنین می توانید با گسترش گره هشدارها، جزئیات مربوط به هشدارها را دریافت کنید.

برای کسب اطلاعات بیشتر، شناسایی رگرسیون های سرعت ساخت را بخوانید.

پاکسازی کتابخانه جاوا 8 در D8 و R8

افزونه Android Gradle اکنون شامل پشتیبانی از استفاده از تعدادی API زبان جاوا 8 بدون نیاز به حداقل سطح API برای برنامه شما است.

از طریق فرآیندی به نام desugaring ، کامپایلر DEX، D8، در Android Studio نسخه 3.0 و بالاتر، قبلاً پشتیبانی قابل توجهی از ویژگی‌های زبان جاوا 8 (مانند عبارات لامبدا، روش‌های رابط پیش‌فرض، تلاش با منابع و موارد دیگر) ارائه کرده است. در اندروید استودیو 4.0، موتور شیرین‌زدایی گسترش یافته است تا بتوان APIهای زبان جاوا را از قند خارج کرد. این بدان معناست که اکنون می‌توانید APIهای زبان استانداردی را که فقط در نسخه‌های اخیر اندروید (مانند java.util.streams ) در دسترس بودند، در برنامه‌هایی که از نسخه‌های قدیمی‌تر Android پشتیبانی می‌کنند، اضافه کنید.

مجموعه API های زیر در این نسخه پشتیبانی می شود:

• جریان های متوالی ( java.util.stream )
• زیر مجموعه ای از java.time
• java.util.function
• افزوده‌های اخیر به java.util.{Map,Collection,Comparator}
• اختیاری ( java.util.Optional ، java.util.OptionalInt و java.util.OptionalDouble ) و برخی کلاس‌های جدید مفید با APIهای بالا
• برخی از موارد اضافه شده به java.util.concurrent.atomic (روش های جدید در AtomicInteger ، AtomicLong و AtomicReference )
• ConcurrentHashMap (با رفع اشکال برای Android 5.0)

برای پشتیبانی از این APIهای زبانی، D8 یک فایل DEX کتابخانه جداگانه که شامل پیاده سازی APIهای گمشده است، کامپایل می کند و آن را در برنامه شما قرار می دهد. فرآیند شیرین سازی کد برنامه شما را بازنویسی می کند تا در عوض از این کتابخانه در زمان اجرا استفاده کند.

برای فعال کردن پشتیبانی از این APIهای زبان، موارد زیر را در فایل build.gradle ماژول برنامه خود قرار دهید:

android {
  defaultConfig {
    // Required when setting minSdkVersion to 20 or lower
    multiDexEnabled true
  }


compileOptions {
    // Flag to enable support for the new language APIs
    coreLibraryDesugaringEnabled true
    // Sets Java compatibility to Java 8
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
}

dependencies {
  coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.0.4'
}

android {
  defaultConfig {
    // Required when setting minSdkVersion to 20 or lower
    multiDexEnabled = true
  }


compileOptions {
    // Flag to enable support for the new language APIs
    isCoreLibraryDesugaringEnabled = true
    // Sets Java compatibility to Java 8
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
  }
}

dependencies {
  coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:1.0.4")
}

توجه داشته باشید که ممکن است لازم باشد قطعه کد بالا را در فایل build.gradle یک ماژول کتابخانه قرار دهید اگر

• آزمون‌های ابزاری ماژول کتابخانه از این APIهای زبان (به طور مستقیم یا از طریق ماژول کتابخانه یا وابستگی‌های آن) استفاده می‌کنند. این به این دلیل است که API های از دست رفته برای APK آزمایشی شما ارائه می شود.

• شما می خواهید lint را به صورت مجزا روی ماژول کتابخانه اجرا کنید. این برای کمک به لینت است که کاربردهای معتبر APIهای زبان را تشخیص دهد و از گزارش هشدارهای نادرست جلوگیری کند.

گزینه های جدید برای فعال یا غیرفعال کردن ویژگی های ساخت

افزونه Android Gradle 4.0.0 راه جدیدی را برای کنترل ویژگی‌های ساختنی که می‌خواهید فعال یا غیرفعال کنید، مانند View Binding و Data Binding، معرفی می‌کند. هنگامی که ویژگی های جدید اضافه می شوند، به طور پیش فرض غیرفعال می شوند. سپس می‌توانید از بلوک buildFeatures استفاده کنید تا فقط ویژگی‌هایی را که می‌خواهید فعال کنید، و به شما کمک می‌کند عملکرد ساخت را برای پروژه خود بهینه کنید. می توانید گزینه های هر ماژول را در فایل build.gradle سطح ماژول به صورت زیر تنظیم کنید:

android {
  // The default value for each feature is shown below. You can change the value to
  // override the default behavior.
  buildFeatures {
    // Determines whether to generate a BuildConfig class.
    buildConfig = true
    // Determines whether to support View Binding.
    // Note that the viewBinding.enabled property is now deprecated.
    viewBinding = false
    // Determines whether to support Data Binding.
    // Note that the dataBinding.enabled property is now deprecated.
    dataBinding = false
    // Determines whether to generate binder classes for your AIDL files.
    aidl = true
    // Determines whether to support RenderScript.
    renderScript = true
    // Determines whether to support injecting custom variables into the module’s R class.
    resValues = true
    // Determines whether to support shader AOT compilation.
    shaders = true
  }
}

android {
  // The default value for each feature is shown below. You can change the value to
  // override the default behavior.
  buildFeatures {
    // Determines whether to generate a BuildConfig class.
    buildConfig = true
    // Determines whether to support View Binding.
    // Note that the viewBinding.enabled property is now deprecated.
    viewBinding = false
    // Determines whether to support Data Binding.
    // Note that the dataBinding.enabled property is now deprecated.
    dataBinding = false
    // Determines whether to generate binder classes for your AIDL files.
    aidl = true
    // Determines whether to support RenderScript.
    renderScript = true
    // Determines whether to support injecting custom variables into the module’s R class.
    resValues = true
    // Determines whether to support shader AOT compilation.
    shaders = true
  }
}

همچنین می‌توانید تنظیمات پیش‌فرض این ویژگی‌ها را در همه ماژول‌های یک پروژه با گنجاندن یک یا چند مورد زیر در فایل gradle.properties پروژه خود، مانند تصویر زیر، تعیین کنید. به خاطر داشته باشید، همچنان می‌توانید از بلوک buildFeatures در فایل build.gradle در سطح ماژول برای لغو این تنظیمات پیش‌فرض در سراسر پروژه استفاده کنید.

android.defaults.buildfeatures.buildconfig=true
android.defaults.buildfeatures.aidl=true
android.defaults.buildfeatures.renderscript=true
android.defaults.buildfeatures.resvalues=true
android.defaults.buildfeatures.shaders=true

وابستگی ویژگی به ویژگی

در نسخه‌های قبلی پلاگین Android Gradle، همه ماژول‌های ویژگی فقط به ماژول پایه برنامه وابسته هستند. هنگام استفاده از پلاگین Android Gradle 4.0.0، اکنون می توانید یک ماژول ویژگی را اضافه کنید که به ماژول ویژگی دیگری بستگی دارد. یعنی یک ویژگی :video می تواند به ویژگی :camera بستگی داشته باشد که به ماژول پایه بستگی دارد، همانطور که در شکل زیر نشان داده شده است.

ماژول ویژگی :video به ویژگی :camera بستگی دارد که به ماژول پایه :app بستگی دارد.

این بدان معناست که وقتی برنامه شما درخواست دانلود یک ماژول ویژگی را می‌دهد، برنامه ماژول‌های ویژگی دیگری را نیز دانلود می‌کند. پس از ایجاد ماژول های ویژگی برای برنامه خود، می توانید یک وابستگی ویژگی به ویژگی را در فایل build.gradle ماژول اعلام کنید. به عنوان مثال، ماژول :video یک وابستگی به :camera به صورت زیر اعلام می کند:

// In the build.gradle file of the ':video' module.
dependencies {
  // All feature modules must declare a dependency
  // on the base module.
  implementation project(':app')
  // Declares that this module also depends on the 'camera'
  // feature module.
  implementation project(':camera')
  ...
}

// In the build.gradle file of the ':video' module.
dependencies {
    // All feature modules must declare a dependency
    // on the base module.
    implementation(project(":app"))
    // Declares that this module also depends on the 'camera'
    // feature module.
    implementation(project(":camera"))
    ...
}

علاوه بر این، باید ویژگی وابستگی ویژگی به ویژگی را در Android Studio فعال کنید (مثلاً برای پشتیبانی از این ویژگی هنگام ویرایش پیکربندی Run) با کلیک کردن روی Help > Edit Custom VM Options از نوار منو و شامل موارد زیر:

-Drundebug.feature.on.feature=true

فراداده های وابستگی

هنگام ساختن برنامه خود با استفاده از افزونه Android Gradle نسخه 4.0.0 و بالاتر، این افزونه شامل ابرداده هایی است که وابستگی هایی را که در برنامه شما کامپایل شده اند را توصیف می کند. هنگام آپلود برنامه شما، کنسول Play این ابرداده را بررسی می کند تا مزایای زیر را در اختیار شما قرار دهد:

• برای مشکلات شناخته شده با SDK و وابستگی هایی که برنامه شما استفاده می کند، هشدار دریافت کنید
• برای حل این مشکلات بازخورد عملی دریافت کنید

داده ها فشرده می شوند، توسط یک کلید امضای Google Play رمزگذاری می شوند و در بلوک امضای برنامه انتشار شما ذخیره می شوند. با این حال، می‌توانید متادیتا را خودتان در فایل‌های ساخت میانی محلی در فهرست زیر بررسی کنید: <project>/<module>/build/outputs/sdk-dependencies/release/sdkDependency.txt .

اگر ترجیح می‌دهید این اطلاعات را به اشتراک نگذارید، می‌توانید با قرار دادن موارد زیر در فایل build.gradle ماژول خود انصراف دهید:

android {
  dependenciesInfo {
      // Disables dependency metadata when building APKs.
      includeInApk = false
      // Disables dependency metadata when building Android App Bundles.
      includeInBundle = false
  }
}

android {
  dependenciesInfo {
      // Disables dependency metadata when building APKs.
      includeInApk = false
      // Disables dependency metadata when building Android App Bundles.
      includeInBundle = false
  }
}

کتابخانه های بومی را از وابستگی های AAR وارد کنید

اکنون می توانید کتابخانه های C/C++ را از وابستگی های AAR برنامه خود وارد کنید. هنگامی که مراحل پیکربندی شرح داده شده در زیر را دنبال می کنید، Gradle به طور خودکار این کتابخانه های بومی را برای استفاده با سیستم ساخت بومی خارجی شما، مانند CMake، در دسترس قرار می دهد. توجه داشته باشید که Gradle فقط این کتابخانه ها را در اختیار ساخت شما قرار می دهد. شما همچنان باید اسکریپت های ساخت خود را برای استفاده از آنها پیکربندی کنید.

کتابخانه ها با استفاده از قالب بسته Prefab صادر می شوند.

هر وابستگی می تواند حداکثر یک بسته Prefab را که شامل یک یا چند ماژول است، نشان دهد. یک ماژول Prefab یک کتابخانه واحد است که می تواند یک کتابخانه اشتراکی، ایستا یا فقط هدر باشد.

به طور معمول، نام بسته با نام مصنوع Maven و نام ماژول با نام کتابخانه مطابقت دارد، اما این همیشه درست نیست. از آنجایی که باید نام بسته و ماژول کتابخانه‌ها را بدانید، ممکن است لازم باشد برای تعیین نام آن‌ها به اسناد وابستگی مراجعه کنید.

سیستم ساخت بومی خارجی خود را پیکربندی کنید

برای مشاهده مراحلی که باید دنبال کنید، مراحل زیر را برای سیستم ساخت بومی خارجی که قصد استفاده از آن را دارید دنبال کنید.

هر یک از وابستگی‌های AAR برنامه شما که شامل کدهای بومی است، یک فایل Android.mk را نشان می‌دهد که باید آن را به پروژه ndk-build خود وارد کنید. شما این فایل را با استفاده از دستور import&endash;module وارد می‌کنید، که مسیرهایی را که مشخص کرده‌اید با استفاده از ویژگی import&endash;add&endash;path در پروژه ndk-build شما جستجو می‌کند. به عنوان مثال، اگر برنامه شما libapp.so تعریف می کند و از curl استفاده می کند، باید موارد زیر را در فایل Android.mk خود قرار دهید:

1. برای CMake:

   add_library(app SHARED app.cpp)
   
   
   # Add these two lines.
   find_package(curl REQUIRED CONFIG)
   target_link_libraries(app curl::curl)

2. برای ndk-build :

   include $(CLEAR_VARS)
   LOCAL_MODULE := libapp
   LOCAL_SRC_FILES := app.cpp
   # Link libcurl from the curl AAR.
   LOCAL_SHARED_LIBRARIES := curl
   include $(BUILD_SHARED_LIBRARY)
   
   
   # If you don't expect that your project will be built using versions of the NDK
   # older than r21, you can omit this block.
   ifneq ($(call ndk-major-at-least,21),true)
       $(call import-add-path,$(NDK_GRADLE_INJECTED_IMPORT_PATH))
   endif
   
   # Import all modules that are included in the curl AAR.
   $(call import-module,prefab/curl)

وابستگی های بومی موجود در یک AAR از طریق متغیر CMAKE_FIND_ROOT_PATH {: .external} در معرض پروژه CMake شما قرار می گیرند. هنگامی که CMake فراخوانی می شود، این مقدار به طور خودکار توسط Gradle تنظیم می شود، بنابراین اگر سیستم ساخت شما این متغیر را تغییر می دهد، مطمئن شوید که به جای اختصاص دادن به آن، آن را اضافه کنید.

هر وابستگی یک بسته فایل پیکربندی {: .external} را در ساخت CMake شما نمایش می دهد که با دستور find_package {: .external} وارد می کنید. این دستور بسته‌های فایل پیکربندی را جستجو می‌کند که با نام بسته و نسخه داده شده مطابقت دارند و اهدافی را که برای استفاده در ساخت شما تعریف می‌کند، در معرض دید قرار می‌دهد. به عنوان مثال، اگر برنامه شما libapp.so تعریف می کند و از curl استفاده می کند، باید موارد زیر را در فایل CMakeLists.txt خود قرار دهید:

add_library(app SHARED app.cpp)


# Add these two lines.
find_package(curl REQUIRED CONFIG)
target_link_libraries(app curl::curl)

اکنون می توانید #include "curl/curl.h" در app.cpp تعیین کنید. هنگامی که پروژه خود را می سازید، سیستم ساخت بومی خارجی شما به طور خودکار libapp.so با libcurl.so پیوند می دهد و libcurl.so را در APK یا بسته نرم افزاری بسته می کند. برای اطلاعات بیشتر به نمونه پیش ساخته curl {:.external} مراجعه کنید.

تغییر رفتار

هنگام استفاده از این نسخه از افزونه، ممکن است با تغییرات زیر در رفتار مواجه شوید.

به روز رسانی پیکربندی امضای v1/v2

رفتار پیکربندی‌های امضای برنامه در بلوک signingConfig به موارد زیر تغییر کرده است:

امضای v1

• اگر v1SigningEnabled به صراحت فعال باشد، AGP امضای برنامه v1 را انجام می دهد.
• اگر v1SigningEnabled به صراحت توسط کاربر غیرفعال شده باشد، امضای برنامه v1 انجام نمی شود.
• اگر کاربر به‌صراحت امضای v1 را فعال نکرده باشد، می‌توان آن را به‌طور خودکار بر اساس minSdk و targetSdk غیرفعال کرد.

امضای v2

• اگر v2SigningEnabled به صراحت فعال باشد، AGP امضای برنامه v2 را انجام می دهد.
• اگر v2SigningEnabled به صراحت توسط کاربر غیرفعال شده باشد، امضای برنامه v2 انجام نمی شود.
• اگر کاربر به طور صریح امضای v2 را فعال نکرده باشد، می توان آن را به طور خودکار بر اساس targetSdk غیرفعال کرد.

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

feature و افزونه های instantapp Android Gradle حذف شدند

افزونه Android Gradle 3.6.0 افزونه Feature ( com.android.feature ) و افزونه Instant App ( com.android.instantapp ) را به نفع استفاده از افزونه Dynamic Feature ( com.android.dynamic-feature ) برای ساخت و بسته بندی منسوخ کرد. برنامه های فوری شما با استفاده از Android App Bundles .

در افزونه Android Gradle نسخه 4.0.0 و بالاتر، این افزونه های منسوخ شده به طور کامل حذف می شوند. بنابراین، برای استفاده از آخرین افزونه Android Gradle، باید برنامه فوری خود را برای پشتیبانی از Android App Bundles منتقل کنید . با انتقال برنامه‌های فوری خود، می‌توانید از مزایای بسته‌های برنامه استفاده کنید و طراحی مدولار برنامه خود را ساده کنید .

توجه: برای باز کردن پروژه هایی که از افزونه های حذف شده در Android Studio نسخه 4.0 و بالاتر استفاده می کنند، پروژه باید از افزونه Android Gradle نسخه 3.6.0 یا پایین تر استفاده کند.

ویژگی پردازش حاشیه نویسی جداگانه حذف شد

امکان جداسازی پردازش حاشیه نویسی به یک کار اختصاصی حذف شده است. هنگامی که پردازشگرهای حاشیه نویسی غیر افزایشی در پروژه های فقط جاوا استفاده می شوند، از این گزینه برای حفظ کامپایل تدریجی جاوا استفاده می شود. با تنظیم android.enableSeparateAnnotationProcessing روی true در فایل gradle.properties فعال شد که دیگر کار نمی کند.

در عوض، برای بهبود عملکرد ساخت، باید به استفاده از پردازشگرهای حاشیه نویسی افزایشی مهاجرت کنید.

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

افزونه Android Gradle دیگر پردازنده‌های حاشیه‌نویسی را که در مسیر کلاس کامپایل اعلام می‌کنید بررسی نمی‌کند یا شامل آن نمی‌شود، و ویژگی annotationProcessorOptions.includeCompileClasspath DSL دیگر اثری ندارد. اگر پردازنده های حاشیه نویسی را در مسیر کلاس کامپایل قرار دهید، ممکن است با خطای زیر مواجه شوید:

Error: Annotation processors must be explicitly declared now.

برای حل این مشکل، باید با استفاده از پیکربندی وابستگی annotationProcessor پردازنده های حاشیه نویسی را در فایل های build.gradle خود قرار دهید. برای کسب اطلاعات بیشتر، افزودن پردازنده های حاشیه نویسی را بخوانید.

بسته بندی خودکار وابستگی های از پیش ساخته شده توسط CMake

نسخه‌های قبلی پلاگین Android Gradle مستلزم این بود که با استفاده از jniLibs کتابخانه‌های از پیش ساخته شده‌ای که توسط ساخت بومی خارجی CMake شما استفاده می‌شود، به‌صراحت بسته‌بندی کنید. ممکن است کتابخانه‌هایی در دایرکتوری src/main/jniLibs ماژول خود داشته باشید، یا احتمالاً در دایرکتوری دیگری که در فایل build.gradle شما پیکربندی شده است:

sourceSets {
  main {
    // The libs directory contains prebuilt libraries that are used by the
    // app's library defined in CMakeLists.txt via an IMPORTED target.
    jniLibs.srcDirs = ['libs']
  }
}

sourceSets {
  main {
    // The libs directory contains prebuilt libraries that are used by the
    // app's library defined in CMakeLists.txt via an IMPORTED target.
    jniLibs.setSrcDirs(listOf("libs"))
  }
}

با Android Gradle Plugin 4.0، پیکربندی فوق دیگر ضروری نیست و منجر به شکست ساخت می شود:

* What went wrong:
Execution failed for task ':app:mergeDebugNativeLibs'.
  > A failure occurred while executing com.android.build.gradle.internal.tasks.Workers$ActionFacade
    > More than one file was found with OS independent path 'lib/x86/libprebuilt.so'

اکنون بیلد بومی خارجی به طور خودکار آن کتابخانه ها را بسته بندی می کند، بنابراین بسته بندی صریح کتابخانه با jniLibs منجر به یک کپی می شود. برای جلوگیری از خطای ساخت، کتابخانه از پیش ساخته شده را به مکانی خارج از jniLibs منتقل کنید یا پیکربندی jniLibs را از فایل build.gradle خود حذف کنید.

مسائل شناخته شده

این بخش مشکلات شناخته شده ای را که در افزونه Android Gradle نسخه 4.0.0 وجود دارد، توضیح می دهد.

شرایط مسابقه در مکانیزم کارگر Gradle

تغییرات در پلاگین Android Gradle 4.0 می‌تواند هنگام اجرا با &endash;&endash;no&endash;daemon و نسخه‌های Gradle 6.3 یا پایین‌تر باعث ایجاد شرایط مسابقه در Gradle شود و باعث شود که پس از اتمام ساخت، بیلدها هنگ کنند.

این مشکل در Gradle 6.4 برطرف خواهد شد.