Implementieren der Java SDK-Bibliothek

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

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 und stubs.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, verwenden m update-api . Um zu überprüfen, ob eine API aktuell ist, verwenden m 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 in prebuilts/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 namens module_name.txt im Verzeichnis version/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:

  1. Zwei Kopien der Implementierungsbibliothek: eine Bibliothek mit dem Namen X und eine andere mit dem Namen X.impl . Bibliothek X ist auf dem Gerät installiert. Die Bibliothek X.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.
  2. 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 die java_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 und stub_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.

Build-Flow mit der Java SDK-Bibliothek
Abbildung 1. Build-Flow mit der Java SDK-Bibliothek

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 und merge_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 von droiddoc_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 Namen module_name .txt und module_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