Google 致力于为黑人社区推动种族平等。查看具体举措

实现 Java SDK 库

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

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

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

  • 生成存根库,将 stubsstubs.systemstubs.test 包括在内。这些存根库是通过识别 @hide@SystemApi@TestApi 注释创建的。在构建时,当 SDK 版本分别为 currentsystem_currenttest_current 时,会自动引用它们。
  • Android 通过存根文件获取 API 列表,并通过将 master 中的当前 API 列表与最近发布的 Android 版本中的 API 列表进行比较来验证是否以向后兼容的方式维护 API。
  • 如果安装了运行时的实现库,就会生成并安装 XML 文件。
使用 Java SDK 库的构建流程
图 1. 使用 Java SDK 库的构建流程

示例和来源

存根库的最小组件是必需的 srcsapi_packages 属性。

java_sdk_library {
        name: "com.android.future.usb.accessory",
        srcs: ["src/**/*.java"],
        api_packages: ["com.android.future.usb"],
    }

如需构建用于运行时的实现库,请填充所有 java_library 属性,如 hostdexcompile_dexerrorprone

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_libsrcs_lib_whitelist_dirssrcs_lib_whitelist_pkgsmerge_annotations_dirsmerge_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.txtmodule_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