Die Android-Plattform enthält eine große Anzahl gemeinsam genutzter Java-Bibliotheken, die optional in den Klassenpfad von Apps mit dem Tag <uses-library>
im App-Manifest aufgenommen werden können. Apps verlinken mit diesen Bibliotheken, behandeln Sie sie also in Bezug auf Kompatibilität, API-Überprüfung und Werkzeugunterstützung wie den Rest der Android-API. Beachten Sie jedoch, dass die meisten Bibliotheken diese Funktionen nicht haben.
Der java_sdk_library
hilft bei der Verwaltung solcher Bibliotheken. Gerätehersteller können diesen Mechanismus für ihre eigenen gemeinsam genutzten Java-Bibliotheken verwenden, um die Abwärtskompatibilität für ihre APIs aufrechtzuerhalten. Wenn Gerätehersteller ihre eigenen gemeinsam genutzten Java-Bibliotheken über das Tag <uses-library>
anstelle des Bootclass-Pfads verwenden, kann java_sdk_library
überprüfen, ob diese Java-Bibliotheken API-stabil sind.
Die java_sdk_library
implementiert optionale SDK-APIs zur Verwendung durch Apps. Bibliotheken, die über java_sdk_library
in Ihrer Build-Datei ( Android.bp
) implementiert werden, führen die folgenden Vorgänge aus:
- Die Stubs-Bibliotheken werden so generiert, dass sie
stubs
,stubs.system
undstubs.test
. Diese Stubs-Bibliotheken werden erstellt, indem die Annotationen@hide
,@SystemApi
und@TestApi
erkannt werden. - Die
java_sdk_library
verwaltet API-Spezifikationsdateien (z. B.current.txt
) in einem API-Unterverzeichnis. Diese Dateien werden mit dem neuesten Code verglichen, um sicherzustellen, dass es sich um die aktuellsten Versionen handelt. Wenn dies nicht der Fall ist, erhalten Sie eine Fehlermeldung, die erklärt, wie Sie sie aktualisieren können. Überprüfen Sie alle Aktualisierungsänderungen manuell, um sicherzustellen, dass sie Ihren Erwartungen entsprechen.
Um alle APIs zu aktualisieren, verwendenm update-api
. Um zu überprüfen, ob eine API aktuell ist, verwendenm checkapi
. - Die API-Spezifikationsdateien werden mit den zuletzt veröffentlichten Android-Versionen verglichen, um sicherzustellen, dass die API mit früheren Versionen abwärtskompatibel ist. Die als Teil von AOSP bereitgestellten
java_sdk_library
Module platzieren ihre zuvor veröffentlichten Versionen inprebuilts/sdk/<latest number>
. - In Bezug auf die Überprüfung der API-Spezifikationsdateien können Sie eines der folgenden drei Dinge tun:
- Lassen Sie die Prüfungen fortfahren. (Nichts tun.)
- Deaktivieren Sie Prüfungen, indem Sie Folgendes zu
java_sdk_library
:
unsafe_ignore_missing_latest_api: true,
- Stellen Sie leere APIs für neue
java_sdk_library
Module bereit, indem Sie leere Textdateien namensmodule_name.txt
im Verzeichnisversion/scope/api
erstellen. - Wenn die Implementierungsbibliothek für die Laufzeit installiert ist, wird eine XML-Datei generiert und installiert.
Funktionsweise von java_sdk_library
Eine java_sdk_library
namens X
erstellt Folgendes:
- Zwei Kopien der Implementierungsbibliothek: eine Bibliothek mit dem Namen
X
und eine andere mit dem NamenX.impl
. BibliothekX
ist auf dem Gerät installiert. Die BibliothekX.impl
ist nur vorhanden, wenn ein expliziter Zugriff auf die Implementierungsbibliothek von anderen Modulen benötigt wird, z. B. für die Verwendung beim Testen. Beachten Sie, dass ein expliziter Zugriff selten erforderlich ist. - Bereiche können aktiviert und deaktiviert werden, um den Zugriff anzupassen. (Ähnlich wie Java-Schlüsselwortzugriffsmodifikatoren bietet ein öffentlicher Bereich einen breiten Zugriffsbereich; ein Testbereich enthält APIs, die nur zum Testen verwendet werden.) Für jeden aktivierten Bereich erstellt die Bibliothek Folgendes:
- Ein Stubs-Quellmodul (vom
droidstubs
-Modultyp) – verbraucht die Implementierungsquelle und gibt einen Satz von Stub-Quellen zusammen mit der API-Spezifikationsdatei aus. - Eine Stubs-Bibliothek (vom
java_library
-Modultyp) – ist die kompilierte Version der Stubs. Die zum Kompilieren verwendeten Bibliotheken sind nicht die gleichen wie die, die für diejava_sdk_library
, wodurch sichergestellt wird, dass die Implementierungsdetails nicht in die API-Stubs gelangen. - Wenn Sie zusätzliche Bibliotheken zum Kompilieren der Stubs benötigen, verwenden Sie die Eigenschaften
stub_only_libs
undstub_only_static_libs
, um sie bereitzustellen.
Wenn eine java_sdk_library
„ X
“ heißt und als „ X
“ kompiliert wird, beziehen Sie sich immer so darauf und ändern Sie sie nicht. Der Build wählt eine geeignete Bibliothek aus. Um sicherzustellen, dass Sie über die am besten geeignete Bibliothek verfügen, überprüfen Sie Ihre Stubs, um festzustellen, ob der Build Fehler eingeführt hat. Nehmen Sie mithilfe dieser Anleitung alle erforderlichen Korrekturen vor:
- Stellen Sie sicher, dass Sie über eine geeignete Bibliothek verfügen, indem Sie in der Befehlszeile nachsehen, welche Stubs dort aufgelistet sind, um Ihren Bereich zu bestimmen:
- Umfang ist zu weit: Die abhängige Bibliothek benötigt einen bestimmten Umfang an APIs. Sie sehen jedoch in der Bibliothek enthaltene APIs, die außerhalb dieses Bereichs liegen, z. B. System-APIs, die in den öffentlichen APIs enthalten sind.
- Umfang ist zu eng: Die abhängige Bibliothek hat keinen Zugriff auf alle erforderlichen Bibliotheken. Beispielsweise muss die abhängige Bibliothek die System-API verwenden, erhält aber stattdessen die öffentliche API. Dies führt normalerweise zu einem Kompilierungsfehler, da erforderliche APIs fehlen.
- Führen Sie zum Reparieren der Bibliothek nur einen der folgenden Schritte aus:
- Ändern Sie die
sdk_version
, um die gewünschte Version auszuwählen. ODER - Geben Sie explizit die entsprechende Bibliothek an, z. B.
<X>.stubs
oder<X>.stubs.system
.
java_sdk_library X-Nutzung
Die Implementierungsbibliothek X
wird verwendet, wenn sie von apex.java_libs
. Aufgrund einer Soong-Einschränkung muss jedoch X.impl
explizit verwendet werden, wenn Bibliothek X
von einem anderen java_sdk_library
-Modul innerhalb derselben APEX-Bibliothek referenziert wird, nicht Bibliothek X
.
Wenn von woanders auf die java_sdk_library
verwiesen wird, wird eine Stubs-Bibliothek verwendet. Die Stubs-Bibliothek wird gemäß der sdk_version
-Eigenschaftseinstellung des abhängigen Moduls ausgewählt. Beispielsweise verwendet ein Modul, das sdk_version: "current"
angibt, die öffentlichen Stubs, während ein Modul, das sdk_version: "system_current"
die System-Stubs verwendet. Wenn keine exakte Übereinstimmung gefunden werden kann, wird die nächstgelegene Stub-Bibliothek verwendet. Eine java_sdk_library
, die nur eine öffentliche API bereitstellt, stellt die öffentlichen Stubs für alle bereit.

Beispiele und Quellen
Die Eigenschaften srcs
und api_packages
müssen in java_sdk_library
vorhanden sein.
java_sdk_library { name: "com.android.future.usb.accessory", srcs: ["src/**/*.java"], api_packages: ["com.android.future.usb"], }
AOSP empfiehlt (ist aber nicht erforderlich), dass neue java_sdk_library
Instanzen explizit die API-Bereiche aktivieren, die sie verwenden möchten. Sie können auch (optional) vorhandene java_sdk_library
Instanzen migrieren, um die von ihnen verwendeten API-Bereiche explizit zu aktivieren:
java_sdk_library { name: "lib", public: { enabled: true, }, system: { enabled: true, }, … }
Um die für die Laufzeit verwendete impl
Bibliothek zu konfigurieren, verwenden Sie alle normalen java_library
Eigenschaften wie hostdex
, compile_dex
und 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, }
Verwenden Sie zum Konfigurieren von Stub-Bibliotheken die folgenden Eigenschaften:
-
merge_annotations_dirs
undmerge_inclusion_annotations_dirs
. -
api_srcs
: Die Liste optionaler Quelldateien, die Teil der API, aber nicht Teil der Laufzeitbibliothek sind. -
stubs_only_libs
: Die Liste der Java-Bibliotheken, die sich beim Erstellen von Stubs im Klassenpfad befinden. -
hidden_api_packages
: Die Liste der Paketnamen, die vor der API verborgen werden müssen. -
droiddoc_options
: Zusätzliches Argument für metalava . -
droiddoc_option_files
: Listet die Dateien auf, auf die innerhalb vondroiddoc_options
mit$(location <label>)
verwiesen werden kann, wobei<file>
ein Eintrag in der Liste ist. -
annotations_enabled
.
Die java_sdk_library
ist eine java_library
, aber kein droidstubs
-Modul und unterstützt daher nicht alle droidstubs
Eigenschaften. Das folgende Beispiel stammt aus der Build-Datei der Bibliothek android.test.mock .
java_sdk_library { name: "android.test.mock", srcs: [":android-test-mock-sources"], api_srcs: [ // Note: The following aren’t APIs of this library. Only APIs under the // android.test.mock package are taken. These do provide private APIs // to which android.test.mock APIs reference. These classes are present // in source code form to access necessary comments that disappear when // the classes are compiled into a Jar library. ":framework-core-sources-for-test-mock", ":framework_native_aidl", ], libs: [ "framework", "framework-annotations-lib", "app-compat-annotations", "Unsupportedappusage", ], api_packages: [ "android.test.mock", ], permitted_packages: [ "android.test.mock", ], compile_dex: true, default_to_stubs: true, }
Aufrechterhaltung der Abwärtskompatibilität
Das Build-System prüft, ob die APIs die Abwärtskompatibilität beibehalten haben, indem es die neuesten API-Dateien mit den generierten API-Dateien zur Build-Zeit vergleicht. Die java_sdk_library
führt die Kompatibilitätsprüfung anhand der von prebuilt_apis
bereitgestellten Informationen durch. Alle mit java_sdk_library
Bibliotheken müssen über API-Dateien in der neuesten Version von api_dirs
in prebuilt_apis
verfügen. Wenn Sie die Version veröffentlichen, können die API-Listendateien und Stubs-Bibliotheken mit dist build mit PRODUCT=sdk_phone_armv7-sdk
.
Die Eigenschaft api_dirs
ist eine Liste der API-Versionsverzeichnisse in prebuilt_apis
. Die API-Versionsverzeichnisse müssen sich auf der Android.bp
-Verzeichnisebene befinden.
prebuilt_apis { name: "foo", api_dirs: [ "1", "2", .... "30", "current", ], }
Konfigurieren Sie die Verzeichnisse mit der Struktur version / scope /api/
unter dem vorgefertigten Verzeichnis. version
entspricht der API-Ebene und scope
definiert, ob das Verzeichnis öffentlich, System oder Test ist.
-
version / scope
enthält Java-Bibliotheken. -
version / scope /api
enthält API.txt
Dateien. Erstellen Sie hier leere Textdateien mit den Namenmodule_name .txt
undmodule_name -removed.txt
.├── 30 │ ├── public │ │ ├── api │ │ │ ├── android.test.mock-removed.txt │ │ │ └── android.test.mock.txt │ │ └── android.test.mock.jar │ ├── system │ │ ├── api │ │ │ ├── android.test.mock-removed.txt │ │ │ └── android.test.mock.txt │ │ └── android.test.mock.jar │ └── test │ ├── api │ │ ├── android.test.mock-removed.txt │ │ └── android.test.mock.txt │ └── android.test.mock.jar └── Android.bp