Implementieren der Java SDK-Bibliothek

Die Android - Plattform enthält eine große Anzahl von gemeinsam genutzten Java - Bibliotheken , die gegebenenfalls in Classpath von Anwendungen mit dem aufgenommen werden können <uses-library> -Tag in dem App - Manifest. Apps verknüpfen mit diesen Bibliotheken. Behandeln Sie sie daher wie den Rest der Android-API in Bezug auf Kompatibilität, API-Überprüfung und Tool-Unterstützung. Beachten Sie jedoch, dass die meisten Bibliotheken nicht über diese Funktionen verfügen.

Das java_sdk_library Modultyp hilft Bibliotheken dieser Art zu verwalten. 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 die Gerätehersteller ihre eigenen gemeinsamen Java - Bibliotheken durch die <uses-library> -Tag anstelle des bootclass Pfad, java_sdk_library können überprüfen , dass diese Java - Bibliotheken API-stabil sind.

Die java_sdk_library Geräte optional SDK APIs für die Verwendung von Apps. Bibliotheken durch implementiert java_sdk_library in Ihrer Build - Datei ( Android.bp ) die folgenden Operationen ausführen :

  • Die Stubs Bibliotheken erzeugt werden , um umfassen stubs , stubs.system und stubs.test . Diese Stubs Bibliotheken werden erstellt , durch die Anerkennung @hide , @SystemApi und @TestApi Anmerkungen.
  • Die java_sdk_library verwaltet API - Spezifikation Dateien (wie current.txt ) in einem API - Unterverzeichnis. Diese Dateien werden mit dem neuesten Code überprüft, um sicherzustellen, dass es sich um die aktuellsten Versionen handelt. Ist dies nicht der Fall, erhalten Sie eine Fehlermeldung, in der erläutert wird, wie Sie sie aktualisieren. Überprüfen Sie alle Update-Änderungen manuell, um sicherzustellen, dass sie Ihren Erwartungen entsprechen.
  • 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 java_sdk_library Module als Teil AOSP Ort, wenn sie zuvor veröffentlichte Versionen in prebuilts/sdk/<latest number> .
  • Hinsichtlich Spezifikation der API überprüft Dateien, können Sie eine der folgenden drei Dinge tun:
    • Erlauben Sie den Überprüfungen, fortzufahren. (Tun Sie nichts.)
    • Deaktivieren Kontrollen durch die folgenden auf das Hinzufügen java_sdk_library :
      unsafe_ignore_missing_latest_api: true,
    • Geben Sie leere APIs für neue java_sdk_library Module , indem leere Textdateien mit dem Namen module_name.txt in der version/scope/api Verzeichnis .
  • Wenn die Implementierungsbibliothek für die Laufzeit installiert ist, wird eine XML-Datei generiert und installiert.

So funktioniert java_sdk_library

Ein java_sdk_library namens X erstellt die folgenden:

  1. Zwei Kopien der Implementierung Bibliothek: eine Bibliothek mit dem Namen X und einem anderen namens X.impl . Bibliothek X ist auf dem Gerät installiert ist . Bibliothek X.impl gibt es nur , wenn explizit Zugriff auf die Implementierung Bibliothek wird von anderen Modulen benötigt werden , wie zum Beispiel für den Einsatz in der Prüfung. 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 Quellenmodul (von droidstubs Modultyp) - die Umsetzung verbraucht Quelle und gibt eine Gruppe von Stub - Quellen zusammen mit der API - Spezifikation Datei.
    • Eine Stubs Bibliothek (von java_library Modultyp) - ist die kompilierte Version der Stummel. Die Libs verwendet , um dieses zu kompilieren sind nicht die gleichen wie die des mitgelieferten java_sdk_library , die die Details der Implementierung gewährleistet Leck nicht in die API - Stubs.
    • Wenn Sie zusätzliche Bibliotheken müssen die Stubs kompilieren, verwenden Sie die stub_only_libs und stub_only_static_libs Eigenschaften , die sie zu liefern.

Wenn ein java_sdk_library wird als „ X “, und als „wird kompiliert gegen X “, beziehen sich immer auf das so und es nicht ändern. 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 verursacht hat. Nehmen Sie alle erforderlichen Korrekturen anhand dieser Anleitung 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 Umfang zu bestimmen:
    • Der Umfang ist zu breit: 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, wie z. B. System-APIs, die in den öffentlichen APIs enthalten sind.
    • Der Umfang ist zu eng: Die abhängige Bibliothek hat nicht Zugriff auf alle erforderlichen Bibliotheken. Beispielsweise muss die abhängige Bibliothek die System-API verwenden, ruft jedoch stattdessen die öffentliche API ab. Dies führt normalerweise zu einem Kompilierungsfehler, da benötigte APIs fehlen.
  • Um die Bibliothek zu beheben, gehen Sie nur eine der folgenden Möglichkeiten :
    • Ändern Sie den sdk_version die Version auszuwählen , die Sie benötigen. ODER
    • Ausdrücklich die entsprechende Bibliothek, wie <X>.stubs oder <X>.stubs.system .

java_sdk_library X-Nutzung

Die Implementierung Bibliothek X verwendet wird , wenn es aus referenzierten ist apex.java_libs . Doch aufgrund einer Soong Einschränkung, wenn Bibliothek X von einem anderen verwiesen wird java_sdk_library Modul innerhalb derselben APEX Bibliothek, X.impl müssen explizit verwendet werden, nicht Bibliothek X .

Wenn die java_sdk_library von anderer Stelle Bezug genommen wird, ist eine Stummel - Bibliothek verwendet. Die Stubs Bibliothek wird ausgewählt nach dem abhängigen Moduls sdk_version Eigenschaftseinstellung. Zum Beispiel ist ein Modul , das angibt , sdk_version: "current" verwendet den öffentlichen Stubs, während ein Modul , das angibt sdk_version: "system_current" verwendet das System Stubs. Wenn keine genaue Übereinstimmung gefunden werden kann, wird die nächstgelegene Stub-Bibliothek verwendet. Ein java_sdk_library , die eine öffentliche API bietet nur werden die öffentlichen Stubs für alle liefern.

Build-Flow mit Java SDK-Bibliothek
Abbildung 1. Erstellen Fluss mit Java SDK - Bibliothek

Beispiele und Quellen

Die srcs und api_packages Eigenschaften müssen in der Gegenwart sein java_sdk_library .

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 ermöglichen Tive sie verwenden möchten. Sie können auch (optional) migrieren bestehende java_sdk_library Instanzen explizit die API ermöglichen Scopes werden sie verwenden:

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

Um die Konfiguration impl Bibliothek zur Laufzeit verwendet, verwenden 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,
    }

Um Stubs-Bibliotheken zu konfigurieren, verwenden Sie die folgenden Eigenschaften:

  • merge_annotations_dirs und merge_inclusion_annotations_dirs .
  • api_srcs : Die Liste der optionalen Quelldateien , die Teil der API sind aber nicht Teil der Laufzeitbibliothek.
  • stubs_only_libs : Die Liste der Java - Bibliotheken , die in dem Classpath sind , wenn Stubs zu bauen.
  • hidden_api_packages : Die Liste der Paketnamen , die von der API versteckt werden muss.
  • droiddoc_options : Zusätzliches Argument für metalava .
  • droiddoc_option_files : Listet die Dateien , die von innen heraus referenziert werden können droiddoc_options mit $(location <label>) , wobei <file> ein Eintrag in der Liste ist.
  • annotations_enabled .

Die java_sdk_library ist ein java_library , aber es ist kein droidstubs Modul und so nicht alle der Unterstützung droidstubs Eigenschaften. Das folgende Beispiel wurde aus der aufgenommenen android.test.mock Bibliothek 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,
    }

Aufrechterhaltung der Abwärtskompatibilität

Das Build-System überprüft, ob die APIs die Abwärtskompatibilität beibehalten haben, indem es die neuesten API-Dateien mit den generierten API-Dateien zum Zeitpunkt des Builds vergleicht. Die java_sdk_library führt die Kompatibilitätsprüfung der Informationen bereitgestellt durch Verwendung prebuilt_apis . Alle Bibliotheken mit integrierten java_sdk_library müssen API - Dateien in der neuesten Version von haben api_dirs in prebuilt_apis . Wenn Sie die Release - Version können die API - Listen von Dateien und Stubs Bibliotheken mit mit dist Build erhalten werden PRODUCT=sdk_phone_armv7-sdk .

Die api_dirs Eigenschaft Liste der API - Version Verzeichnisse in prebuilt_apis . Die API-Version Verzeichnisse müssen im befinden Android.bp Verzeichnisebene.

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

Konfigurieren Sie die Verzeichnisse mit der version / scope /api/ Struktur unter dem prebuilts Verzeichnis. version entspricht die API - Ebene und scope definiert , ob das Verzeichnis öffentlich ist, ein System oder Test.

  • version / scope enthält Java - Bibliotheken.
  • version / scope /api enthält API .txt - Dateien. Erstellen Sie leere Textdateien namens 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