androidlib.java_实现 Java SDK 库

Android 平台包含大量的共享 Java 库，可以使用应用清单中的 标记选择性地将其纳入应用的类路径中。由于应用与这些库相关联，因此在兼容性、API 审核和工具支持方面，应将其与其他 Android API 一样对待。不过，大多数库都没有这些功能。

Android 10 引入了 java_sdk_library，这是一个新的构建规则，可解决共享 Java 库的兼容性问题。设备制造商可在自己的共享 Java 库中运用此机制，以保持其 API 的向后兼容性。如果设备制造商通过 标记(而不是 bootclass 路径)使用自己的共享 Java 库，则 java_sdk_library 可以验证这些 Java 库是否能让 API 保持稳定。

java_sdk_library 是一个 Java 库，可为应用实现可选的 SDK API。通过 makefile (Android.bp) 中的 java_sdk_library 实现的库会执行以下操作：

生成存根库，将 stubs、stubs.system 和 stubs.test 包括在内。这些存根库是通过识别 @hide、@SystemApi 和 @TestApi 注释创建的。在构建时，当 SDK 版本分别为 current、system_current 和 test_current 时，会自动引用它们。

Android 通过存根文件获取 API 列表，并通过将 master 中的当前 API 列表与最近发布的 Android 版本中的 API 列表进行比较来验证是否以向后兼容的方式维护 API。

如果安装了运行时的实现库，就会生成并安装 XML 文件。

图 1. 使用 Java SDK 库的构建流程

示例和来源

存根库的最小组件是必需的 srcs 和 api_packages 属性。

java_sdk_library {

name: "com.android.future.usb.accessory",

srcs: ["src/**/*.java"],

api_packages: ["com.android.future.usb"],

}

如需构建用于运行时的实现库，请填充所有 java_library 属性，如 hostdex、compile_dex 和 errorprone。

java_sdk_library {

name: "android.test.base",

srcs: ["src/**/*.java"],

errorprone: {

javacflags: ["-Xep:DepAnn:ERROR"],

},

hostdex: true,

api_packages: [

"android.test",

"android.test.suitebuilder.annotation",

"com.android.internal.util",

"junit.framework",

],

compile_dex: true,

}

如需创建存根库，请填充 droidstubs 属性，如 srcs_lib、srcs_lib_whitelist_dirs、srcs_lib_whitelist_pkgs、merge_annotations_dirs 和 merge_inclusion_annotations_dirs。您还可以将以下属性用于存根库中：

api_srcs：属于 API 但不属于运行时库的可选源文件的列表。

stubs_only_libs：构建存根时位于类路径中的 Java 库的列表。

hidden_api_packages：必须对 API 隐藏的软件包名称的列表。

droiddoc_options：metalava 的附加参数。

java_sdk_library {

name: "android.test.mock",

srcs: ["src/**/*.java"],

api_packages: [

"android.test.mock",

],

srcs_lib: "framework",

srcs_lib_whitelist_dirs: ["core/java"],

srcs_lib_whitelist_pkgs: ["android"],

compile_dex: true,

}

保持向后兼容性

构建系统通过在构建时将最新的 API 文件与生成的 API 文件进行比较来检查 API 是否保持向后兼容性。此操作通过一个名为 prebuilt_apis 的新构建规则来完成，该规则会创建预构建的存根库模块和 API 列表模块。使用 java_sdk_library 构建的所有库都必须在 prebuilt_apis 中的拥有最新版的 api_dirs 中的 API 文件。当您发布版本时，可以使用 PRODUCT-sdk_phone_armv7-sdk 通过 dist build 获取 API 列表文件和存根库。

api_dirs 属性是 prebuilt_apis 中的 API 版本目录的列表。API 版本目录应位于与 Android.bp 相同的目录级别。

prebuilt_apis {

name: "sdk",

api_dirs: [

"1",

"2",

....

"28",

"current",

],

}

在 prebuilts 目录下配置 version/scope/api/ 结构的目录。version 与 API 级别相对应，而 scope 可确定目录是公开目录、系统目录还是测试目录。

version/scope 包含 Java 库。

version/scope/api 包含 API .txt 文件。在此处创建名为 module_name.txt 和 module_name-removed.txt 的空文本文件。

├── 28

│ ├── public

│ │ ├── api

│ │ │ ├── android.test.base-removed.txt

│ │ │ └── android.test.base.txt

│ │ └── android.test.base.jar

│ ├── system

│ │ ├── api

│ │ │ ├── android.test.base-removed.txt

│ │ │ └── android.test.base.txt

│ │ └── android.test.base.jar

│ └── test

│ ├── api

│ │ ├── android.test.base-removed.txt

│ │ └── android.test.base.txt

│ └── android.test.base.jar

└── Android.bp