Java SDK-Bibliothek implementieren

Die Android-Plattform enthält eine große Anzahl gemeinsam genutzter Java-Bibliotheken. der optional in den Klassenpfad von Apps mit der Eigenschaft <uses-library>-Tag im App-Manifest ein. App-Link diese Bibliotheken nicht verwenden und sie daher wie den Rest der Android API behandeln. hinsichtlich Kompatibilität, API-Überprüfung und Tool-Support. Beachten Sie jedoch, dass die meisten Bibliotheken nicht über diese Funktionen verfügen.

Mit dem Modultyp java_sdk_library können Sie Bibliotheken verwalten dieser Art. Gerätehersteller können diesen Mechanismus gemeinsame Java-Bibliotheken, um die Abwärtskompatibilität für ihre APIs aufrechtzuerhalten. Wenn Gerätehersteller ihre eigenen freigegebenen Java-Bibliotheken über die <uses-library> anstelle des Bootclass-Pfads verwenden, java_sdk_library kann verifizieren, dass diese Java-Bibliotheken API-stable.

Die java_sdk_library implementiert optionale SDK APIs zur Verwendung durch Apps. Bibliotheken, die über java_sdk_library in Ihrem Build-Datei (Android.bp) folgende Vorgänge ausführen:

  • Die Stubs-Bibliotheken werden generiert, um stubs, stubs.system und stubs.test. Diese Stubs-Bibliotheken werden durch die Erkennung von @hide erstellt, @SystemApi- und @TestApi-Annotationen.
  • java_sdk_library verwaltet API-Spezifikationsdateien (z. B. current.txt) in einem API-Unterverzeichnis. Diese Dateien mit dem aktuellen Code abgeglichen, um sicherzustellen, aktuellen Versionen Ist dies nicht der Fall, erhalten Sie eine Fehlermeldung, wie Sie sie aktualisieren. Alle Aktualisierungsänderungen an sicherzustellen, dass sie Ihren Erwartungen entsprechen.

    Verwenden Sie m update-api, um alle APIs zu aktualisieren. Um zu prüfen, ob eine API aktuell ist, m checkapi verwenden.
  • Die API-Spezifikationsdateien werden mit den zuletzt verwendeten Dateien abgeglichen. veröffentlichten Android-Versionen überprüfen, um sicherzustellen, dass die API abwärtskompatibel ist mit früheren Releases. Bereitgestellte java_sdk_library-Module im Rahmen von AOSP ihre zuvor veröffentlichten Versionen prebuilts/sdk/<latest number>.
  • In Bezug auf die Überprüfung der API-Spezifikationsdateien haben Sie folgende Möglichkeiten: eines der folgenden drei Dinge:
    • Warten Sie, bis die Überprüfung fortgesetzt wird. Sie müssen nichts unternehmen.
    • Um die Überprüfung zu deaktivieren, fügen Sie Folgendes zu java_sdk_library hinzu:
      unsafe_ignore_missing_latest_api: true,
    • Leere APIs für neue java_sdk_library-Module angeben indem Sie in folgendem Ordner leere Textdateien mit dem Namen module_name.txt erstellen: das version/scope/api-Verzeichnis.
  • Wenn die Implementierungsbibliothek für die Laufzeit installiert ist, eine XML-Datei generiert und installiert wird.

Funktionsweise von java_sdk_library

Ein java_sdk_library mit dem Namen X erstellt Folgendes:

  1. Zwei Kopien der Implementierungsbibliothek: eine Bibliothek namens X und ein weiteres mit dem Namen X.impl. Bibliothek „X“ ist installiert auf dem Gerät. Die Bibliothek X.impl ist nur vorhanden, wenn expliziter Zugriff auf wird die Implementierungsbibliothek von anderen Modulen benötigt, z. B. zur Verwendung in Tests durchführen. Ein expliziter Zugriff ist selten erforderlich.
  2. Bereiche können aktiviert und deaktiviert werden, um den Zugriff anzupassen. (Ähnlich wie Java Modifizierer für den Zugriff auf Keywords bietet der öffentliche Geltungsbereich ein breites Spektrum an Zugriffsrechten. eine Testbereich enthält APIs, die nur für Tests verwendet werden.) Für jeden aktivierten Bereich wird Folgendes erstellt:
    • Ein Stub-Quellmodul (vom Modultyp droidstubs) – verbraucht der Implementierungsquelle und gibt eine Reihe von Stub-Quellen die API-Spezifikationsdatei.
    • Eine Stub-Bibliothek (vom Modultyp java_library) ist die der kompilierten Version der Stubs. Die zum Kompilieren verwendeten Bibliotheken entsprechen denen in java_sdk_library. Dadurch wird sichergestellt, dass Implementierungsdetails können nicht in die API-Stubs gelangen.
    • Wenn Sie zum Kompilieren der Stubs zusätzliche Bibliotheken benötigen, verwenden Sie die Methode stub_only_libs und stub_only_static_libs , um sie bereitzustellen.

Wenn eine java_sdk_library „X“ heißt und die als „X“ kompiliert sind, sollten Sie sich immer so darauf beziehen und keine Änderungen . Der Build wählt eine geeignete Bibliothek aus. Um sicherzustellen, am besten geeignet ist, überprüfen Sie Ihre Stubs, um zu sehen, ob der Build Fehler. Nehmen Sie die erforderlichen Korrekturen anhand dieser Anleitung vor:

  • Überprüfen Sie, ob Sie über eine geeignete Bibliothek verfügen, indem Sie in der Befehlszeile nachsehen Untersuchen Sie, welche Stubs dort aufgeführt sind, um Ihren Bereich zu ermitteln:
    • Bereich ist zu groß: Die abhängige Bibliothek benötigt einen bestimmten API-Bereich. Aber sehen Sie APIs in der Bibliothek, die außerhalb dieses Bereichs liegen, z. B. die in den öffentlichen APIs enthalten sind.
    • Bereich zu eng gefasst: Die je nach Bibliothek vorhandene Bibliothek hat keinen Zugriff auf alle erforderlichen Bibliotheken. Die abhängige Bibliothek muss beispielsweise die Methode System-API verwendet, erhält aber stattdessen die öffentliche API. Dies führt in der Regel zu einer Kompilierungsfehler, da erforderliche APIs fehlen.
  • Führen Sie nur einen der folgenden Schritte aus, um Probleme mit der Bibliothek zu beheben:
    • Ändern Sie den sdk_version, um die benötigte Version auszuwählen. ODER
    • Geben Sie explizit die entsprechende Bibliothek an, z. B. <X>.stubs. oder <X>.stubs.system.

Verwendung von java_sdk_library X

Die Implementierungsbibliothek X wird verwendet, wenn von apex.java_libs. Aufgrund einer Soong-Einschränkung ist es jedoch möglich, Auf X wird in einem anderen java_sdk_library-Modul verwiesen innerhalb derselben APEX-Bibliothek, X.impl explizit verwendet werden, nicht die Bibliothek X.

Wenn von einer anderen Stelle auf java_sdk_library verwiesen wird, erstellt ein Stub verwendet wird. Die Stub-Bibliothek wird anhand der abhängigen Eigenschaftseinstellung sdk_version des Moduls. Ein Modul, das gibt an, dass sdk_version: "current" die öffentlichen Stubs verwendet, während ein das sdk_version: "system_current" angibt, System-Stubs verwenden. Wenn keine exakte Übereinstimmung gefunden werden kann, wird die nächstgelegene Stub-Bibliothek verwendet. Ein java_sdk_library, der nur eine öffentliche API bereitstellt, die öffentlichen Dienste für alle bereitstellen.

Build-Ablauf mit Java SDK-Bibliothek
Abbildung 1: Build-Ablauf mit Java SDK-Bibliothek

Beispiele und Quellen

Die Properties 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 (aber nicht erforderlich), dass neue java_sdk_library -Instanzen explizit die API-Bereiche, die sie verwenden möchten. Sie können auch Vorhandene java_sdk_library-Instanzen migrieren (optional) zu die von ihnen verwendeten API-Bereiche explizit aktiviert werden: 

java_sdk_library {
         name: "lib",
         public: {
           enabled: true,
         },
         system: {
           enabled: true,
         },
         …
    }

Verwenden Sie zum Konfigurieren der impl-Bibliothek, die für die Laufzeit verwendet wird, alle die 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 die folgenden Attribute, um Stubs-Bibliotheken zu konfigurieren:

  • merge_annotations_dirs und merge_inclusion_annotations_dirs.
  • api_srcs: die Liste der optionalen Quelldateien, die Teil sind der API, aber nicht Teil der Laufzeitbibliothek.
  • stubs_only_libs: Die Liste der Java-Bibliotheken in der classpath verwenden, wenn Stubs erstellt werden.
  • hidden_api_packages: Die Liste der Paketnamen, die die von der API ausgeblendet werden.
  • droiddoc_options: zusätzliches Argument für Metalava verwendet.
  • droiddoc_option_files: Listet die Dateien auf, auf die verwiesen werden kann. in droiddoc_options mit $(location <label>), Dabei ist <file> ein Eintrag in der Liste.
  • annotations_enabled.

java_sdk_library ist eine java_library, aber keine droidstubs-Modul und unterstützt daher nicht alle droidstubs Eigenschaften. Das folgende Beispiel stammt aus der Android.test.mock-Bibliotheks-Build -Datei. 

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

Abwärtskompatibilität aufrechterhalten

Das Build-System prüft, ob die APIs abwärtskompatibel indem Sie die neuesten API-Dateien mit den generierten API-Dateien zur Build-Zeit. Der java_sdk_library führt die Kompatibilitätsprüfung anhand der von prebuilt_apis bereitgestellten Informationen. Alle mit java_sdk_library erstellten Bibliotheken müssen API-Dateien haben in der neuesten Version von api_dirs in prebuilt_apis. Wenn Sie die Version veröffentlichen, listet die API Dateien und Stubs auf Bibliotheken können mit dist build mit PRODUCT=sdk_phone_armv7-sdk abgerufen werden.

Das Attribut api_dirs ist eine Liste der API-Versionsverzeichnisse in prebuilt_apis Die Verzeichnisse für die API-Version müssen auf der Verzeichnisebene Android.bp. 

prebuilt_apis {
       name: "foo",
       api_dirs: [
           "1",
           "2",
             ....
           "30",
           "current",
       ],
    }

Verzeichnisse mit dem version/scope/api/ konfigurieren Struktur unter dem vordefinierten Verzeichnis. version entspricht der API-Ebene und scope definiert ob das Verzeichnis öffentlich, ein System- oder ein Testverzeichnis ist.

  • version/scope Java-Bibliotheken enthält.
  • version/scope/api enthält API .txt Dateien. Erstellen Sie leere Textdateien mit dem Namen module_name.txt und module_name-removed.txt hier. 
     ├── 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