Java SDK ライブラリの実装

Android プラットフォームには多数の共有 Java ライブラリが含まれており、必要であればアプリマニフェストの <uses-library> タグを使用してアプリのクラスパスにそれらをインクルードできます。これらのライブラリはアプリによってリンクされているので、互換性、API レビュー、ツールのサポートの点で、他の Android API と同様に扱う必要があります。ただし、ほとんどのライブラリにはこれらの機能がありません。

Android 10 では、共有 Java ライブラリの互換性の問題を解決するための新しいビルドルールとして、java_sdk_library が導入されています。デバイスメーカーは、独自の共有 Java ライブラリにこのメカニズムを使用して、API の下位互換性を維持できます。デバイスメーカーがブートクラスパスの代わりに <uses-library> タグを使用して独自の共有 Java ライブラリを使用している場合、java_sdk_library はそれらの Java ライブラリが API 安定性を持つことを確認できます。

java_sdk_library は、オプションの SDK API をアプリに実装する Java ライブラリです。Make ファイル（Android.bp）内の java_sdk_library を介して実装されたライブラリは、次の操作を実行します。

stubs、stubs.system、stubs.test を含むスタブライブラリを生成します。これらのスタブライブラリは、@hide、@SystemApi、および @TestApi アノテーションを認識することにより作成されます。それらは、SDK バージョンがそれぞれ current、system_current、test_current の場合、ビルド時に自動的に参照されます。
Android はスタブファイルから API リストを取得し、マスターの現行 API リストと最新の公開済み Android バージョンの API リストを比較して、API が下位互換性を維持しているかどうかを確認します。
ランタイム用の実装ライブラリがインストールされている場合は、XML ファイルが生成されてインストールされます。

例とソース

スタブライブラリの最小限の構成要素は、必須の srcs と api_packages のプロパティです。

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

ランタイムに使用する実装ライブラリをビルドするには、hostdex、compile_dex、errorprone など、すべての java_library プロパティに値を設定します。

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,
    }

スタブライブラリを作成するには、srcs_lib、srcs_lib_whitelist_dirs、srcs_lib_whitelist_pkgs、merge_annotations_dirs、merge_inclusion_annotations_dirs などの droidstubs プロパティに値を設定します。スタブライブラリには次のプロパティを使用することもできます。

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 を備えた配布ビルドで、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 はディレクトリが public、system、test のいずれであるかを示します。

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