Android Gradle 外掛程式 4.1.0 版 (2020 年 8 月)

相容性

<p>This version of the Android plugin requires the following:</p>
<ul>
  <li>
    <p><a href="https://docs.gradle.org/6.5.1/release-notes.html">Gradle 6.5</a>.
    To learn more, read the section about <a href="#updating-gradle">updating
    Gradle</a>.</p>
  </li>
  <li>
    <p><a href="/studio/releases/build-tools.html#notes">SDK Build Tools
    29.0.2</a> or higher.</p>
  </li>
</ul>
<p>The default NDK version in this release is 21.1.6352462. To install a
different NDK version, see <a href="/studio/projects/install-ndk#specific-version">Install a specific version of the NDK</a>.</p>

新功能

此版本的 Android Gradle 外掛程式內附以下新功能。

支援 Kotlin 指令碼 DSL

為改善 Kotlin 建構指令碼使用者的編輯體驗，現在對於 Android Gradle 外掛程式 4.1 版的 DSL 和 API，您可以從實作類別之外的一組 Kotlin 介面中進行定義。這表示：

• Kotlin 類型已能明確宣告是否可為空值和可變動性。
• 根據這些介面所產生的文件會發布在 Kotlin API 參考資料。
• Android Gradle 外掛程式的 API 介面已明確定義，後續的 Android 版本會更加穩定。

重要事項：如果您已採用 KTS 建構指令碼或在 buildSrc 中使用 Kotlin，這項異動可能造成來源相容性因特定錯誤而中斷，例如先前版本中的執行階段錯誤。

可在 DSL 內變動的集合類型現在一律定義為：

val collection: MutableCollectionType

也就是說，即使某些集合曾支援以下類型，這種類型都無法再寫入 Kotlin 指令碼：

collection = collectionTypeOf(...)

不過，由於集合變動受到全面支援，因此 collection += … 和 collection.add(...) 應適用於任何地方。

升級採用 Android Gradle 外掛程式 Kotlin API 和 DSL 的專案時，如果發現任何問題，請務必回報錯誤。

從 AAR 匯出 C/C++ 依附元件

Android Gradle 外掛程式 4.0 版新增了在 AAR 依附元件中匯入 Prefab 套件的功能。現在 AGP 4.1 版可針對 Android 程式庫專案的 AAR，匯出外部原生建構作業的程式庫。

如要匯出原生程式庫，請在程式庫專案中，將以下內容加入 build.gradle 檔案的 android 區塊：

buildFeatures {
    prefabPublishing true
}


prefab {
    <var>mylibrary</var&;gt {
      headers "src/main/cpp/<var>mylibrary</var>/include"
    }
<var>myotherlibrary</var> {
    headers "src/main/cpp/<var>myotherlibrary</var>/include"
}

}
      
buildFeatures {
    prefabPublishing = true
}


prefab {
    create("<var>mylibrary</var>") {
      headers = "src/main/cpp/<var>mylibrary</var>/include"
    }
create("<var>myotherlibrary</var>") {
    headers = "src/main/cpp/<var>myotherlibrary</var>/include"
}

}
      

在此示例中，來自 ndk-build 或 CMake 外部原生建構作業的 mylibrary 和 myotherlibrary 程式庫會封裝至建構作業產生的 AAR 中，而且這些程式庫會分別將標頭從指定目錄匯出至依附於其的項目。

注意：如果採用的是 Android Gradle 外掛程式 4.0 以上版本，請注意匯入預先建構原生程式庫的設定有所變更。詳情請參閱 Android Gradle 外掛程式 4.0 版的版本資訊。

R8 對 Kotlin 中繼資料的支援

為識別 Kotlin 語言結構，Kotlin 會在 Java 類別檔案中使用自訂中繼資料。R8 現在支援維護及重新寫入 Kotlin 中繼資料，可以針對使用 kotlin-reflect 的 Kotlin 程式庫和應用程式縮減大小。

如要保留 Kotlin 中繼資料，請新增下列保留規則：

-keep class kotlin.Metadata { *; }


-keepattributes RuntimeVisibleAnnotations

這將指示 R8 保留所有直接保留類別的 Kotlin 中繼資料。

詳情請參閱 Medium 文章「Shrinking Kotlin libraries and applications using Kotlin reflection with R8」(針對使用 Kotlin 反映機制的 Kotlin 程式庫和應用程式，使用 R8 縮減大小)。

偵錯版本的斷言

使用 Android Gradle 外掛程式 4.1.0 以上版本建構應用程式的偵錯版本後，內建編譯器 (D8) 會重新編寫應用程式的程式碼，藉此在編譯時間啟用斷言，讓斷言檢查保持啟用狀態。

行為變更

移除 Android Gradle 外掛程式建構快取

AGP 4.1 版已移除 AGP 建構快取。AGP 2.3 版推出 AGP 建構快取是為了補充 Gradle 建構快取；但在 AGP 4.1 版中，Gradle 建構快取已完全取代 AGP 建構快取。這項異動不會影響建構時間。

cleanBuildCache 工作、android.enableBuildCache 屬性和 android.buildCacheDir 屬性已遭淘汰，AGP 7.0 版也會移除這些項目。android.enableBuildCache 屬性目前沒有實際作用，而 android.buildCacheDir 屬性和 cleanBuildCache 工作在 AGP 7.0 以下版本中仍有效力，可用於刪除現有的 AGP 建構快取內容。

使用程式碼縮減功能的應用程式已大幅縮小

從這個版本開始，系統不再預設保留 R 類別的欄位。也就是說，若應用程式啟用程式碼縮減功能，就可能使得 APK 大幅縮小。這應該不會導致行為變更。除非您透過反映方式存取 R 類別；在這種情況下，您必須針對 R 類別新增保留規則。

android.namespacedRClass 屬性已重新命名為 android.nonTransitiveRClass

實驗旗標 android.namespacedRClass 已更名為 android.nonTransitiveRClass。

在 gradle.properties 檔案中設定此旗標後，即可啟用每個程式庫的 R 類別命名空間。也就是說，R 類別只會包含程式庫本身宣告的資源，不會納入程式庫依附元件的資源，使得程式庫的 R 類別得以縮小。

Kotlin DSL：coreLibraryDesugaringEnabled 更換名稱

Kotlin DSL 編譯選項 coreLibraryDesugaringEnabled 已變更為 isCoreLibraryDesugaringEnabled。如要進一步瞭解此旗標，請參閱「支援 Java 8+ API 脫糖 (Android Gradle 外掛程式 4.0.0 以上版本)」一節。

從程式庫專案的 BuildConfig 類別中移除版本屬性

針對程式庫專案，我們已從系統產生的 BuildConfig 類別中移除 BuildConfig.VERSION_NAME 和 BuildConfig.VERSION_CODE 屬性，原因是這些靜態值無法反映應用程式版本代碼及名稱的最終值，會誤導使用者。此外，系統會在合併資訊清單時捨棄這些值。

日後的 Android Gradle 外掛程式版本也會從程式庫的 DSL 中移除 versionName 和 versionCode 屬性。目前您無法從程式庫子專案自動存取應用程式的版本代碼/名稱。

應用程式模組沒有任何變更，您仍然可以在 DSL 中指派 versionCode 和 versionName 的值，這些值將套用至應用程式的資訊清單和 BuildConfig 欄位。

設定 NDK 路徑

您可以在模組的 build.gradle 檔案中使用 android.ndkPath 屬性，設定本機 NDK 安裝作業的路徑。

android {
  ndkPath "your-custom-ndk-path"
}

android {
  ndkPath = "your-custom-ndk-path"
}

如果您將這項屬性與 android.ndkVersion 屬性搭配使用，此路徑必須包含與 android.ndkVersion 相符的 NDK 版本。

程式庫單元測試行為變更

我們變更了程式庫單元測試的編譯和執行方式。現在，程式庫的單元測試會根據程式庫本身的編譯/執行階段類別進行編譯和執行作業，因此單元測試會採用和外部子專案相同的方式來使用程式庫。這項設定通常能達到更好的測試效果。

在某些情況下，使用資料繫結的程式庫單元測試可能會遇到缺少 DataBindingComponent 或 BR 類別的問題。這類測試應轉移至 androidTest 專案中的檢測設備測試，因為單元測試中對於這些類別的編譯與執行作業可能產生不正確的結果。

淘汰 io.fabric Gradle 外掛程式

io.fabric Gradle 外掛程式已淘汰，而且與 Android Gradle 外掛程式 4.1 版不相容。如要進一步瞭解淘汰的 Fabric SDK，以及改用 Firebase Crashlytics SDK 的方法，請參閱「開始使用 Firebase Crashlytics SDK」。