Unterstützung für VNDK-Build-System

In Android 8.1 und höher ist die VNDK-Unterstützung im Build-System integriert. Wenn die VNDK-Unterstützung aktiviert ist, prüft das Build-System die Abhängigkeiten zwischen Modulen, erstellt eine anbieterspezifische Variante für Anbietermodule und installiert diese Module automatisch in den entsprechenden Verzeichnissen.

Beispiel für die Unterstützung von VNDK-Builds

In diesem Beispiel wird in der Moduldefinition Android.bp eine Bibliothek mit dem Namen libexample definiert. Das Attribut vendor_available gibt an, dass Framework- und Herstellermodule von libexample abhängen können:

Abbildung 1.-Unterstützung aktiviert.

Sowohl die Framework-Ausführungsdatei /system/bin/foo als auch die Anbieter-Ausführungsdatei /vendor/bin/bar hängen von libexample ab und haben libexample in ihren shared_libs-Eigenschaften.

Wenn libexample sowohl von Framework- als auch von Anbietermodulen verwendet wird, werden zwei Varianten von libexample erstellt. Die Core-Variante (benannt nach libexample) wird von Framework-Modulen verwendet und die Anbieter-Variante (benannt nach libexample.vendor) von Anbietermodulen. Die beiden Varianten werden in unterschiedlichen Verzeichnissen installiert:

• Die Core-Variante wird in /system/lib[64]/libexample.so installiert.
• Die Anbietervariante wird im VNDK APEX installiert, weil vndk.enabled true ist.

Weitere Informationen finden Sie unter Moduldefinition.

Build-Support konfigurieren

Wenn Sie die vollständige Unterstützung des Build-Systems für ein Produktgerät aktivieren möchten, fügen Sie BOARD_VNDK_VERSION zu BoardConfig.mk hinzu:

BOARD_VNDK_VERSION := current

Diese Einstellung hat eine globale Wirkung: Wenn sie in BoardConfig.mk definiert ist, werden alle Module geprüft. Da es keinen Mechanismus zum Sperren oder Zulassen eines betreffenden Moduls gibt, sollten Sie alle unnötigen Abhängigkeiten entfernen, bevor Sie BOARD_VNDK_VERSION hinzufügen. Sie können ein Modul testen und kompilieren, indem Sie BOARD_VNDK_VERSION in Ihren Umgebungsvariablen festlegen:

$ BOARD_VNDK_VERSION=current m module_name.vendor

Wenn BOARD_VNDK_VERSION aktiviert ist, werden mehrere globale Standardsuchpfade für Header entfernt. Dazu gehören:

• frameworks/av/include
• frameworks/native/include
• frameworks/native/opengl/include
• hardware/libhardware/include
• hardware/libhardware_legacy/include
• hardware/ril/include
• libnativehelper/include
• libnativehelper/include_deprecated
• system/core/include
• system/media/audio/include

Wenn ein Modul von den Headern aus diesen Verzeichnissen abhängt, müssen Sie die Abhängigkeiten mit header_libs, static_libs und/oder shared_libs explizit angeben.

VNDK-APEX

In Android 10 und niedriger wurden Module mit vndk.enabled in /system/lib[64]/vndk[-sp]-${VER} installiert. In Android 11 und höher werden VNDK-Bibliotheken im APEX-Format verpackt. Der Name des VNDK-APEX ist com.android.vndk.v${VER}. Je nach Gerätekonfiguration ist VNDK APEX zusammengeführt oder nicht zusammengeführt und über den kanonischen Pfad /apex/com.android.vndk.v${VER} verfügbar.

Abbildung 2: VNDK-APEX.

Moduldefinition

Wenn Sie Android mit BOARD_VNDK_VERSION erstellen möchten, müssen Sie die Moduldefinition in Android.mk oder Android.bp überarbeiten. In diesem Abschnitt werden verschiedene Arten von Moduldefinitionen, mehrere VNDK-bezogene Moduleigenschaften und Abhängigkeitsprüfungen beschrieben, die im Build-System implementiert sind.

Anbietermodule

Anbietermodule sind anbieterspezifische ausführbare Dateien oder gemeinsam genutzte Bibliotheken, die auf einer Anbieterpartition installiert werden müssen. In Android.bp-Dateien muss für Anbietermodule die Anbieter- oder proprietäre Eigenschaft auf true festgelegt werden. In Android.mk-Dateien muss für Anbietermodule LOCAL_VENDOR_MODULE oder LOCAL_PROPRIETARY_MODULE auf true festgelegt werden.

Wenn BOARD_VNDK_VERSION definiert ist, lässt das Build-System keine Abhängigkeiten zwischen Anbietermodulen und Framework-Modulen zu und gibt Fehler aus, wenn:

• ein Modul ohne vendor:true hängt von einem Modul mit vendor:true ab oder
• Ein Modul mit vendor:true hängt von einem Modul ohne llndk_library ab, das weder vendor:true noch vendor_available:true hat.

Die Abhängigkeitsprüfung gilt für header_libs, static_libs und shared_libs in Android.bp sowie für LOCAL_HEADER_LIBRARIES, LOCAL_STATIC_LIBRARIES und LOCAL_SHARED_LIBRARIES in Android.mk.

LL-NDK

LL-NDK-Bibliotheken sind gemeinsam genutzte Bibliotheken mit stabilen ABIs. Sowohl Framework- als auch Anbietermodule haben dieselbe und die neueste Implementierung. Für jede LL-NDK-Shared Library enthält cc_library eine llndk-Property mit einer Symboldatei:

cc_library {
    name: "libvndksupport",
    llndk: {
        symbol_file: "libvndksupport.map.txt",
    },
}

Die Symboldatei beschreibt die für Anbietermodule sichtbaren Symbole. Beispiel:

LIBVNDKSUPPORT {
  global:
    android_load_sphal_library; # llndk
    android_unload_sphal_library; # llndk
  local:
    *;
};

Anhand der Symboldatei generiert das Build-System eine Stub-Shared Library für Vendormodule, die mit diesen Bibliotheken verknüpft werden, wenn BOARD_VNDK_VERSION aktiviert ist. Ein Symbol ist nur dann in der Stub-Bibliothek enthalten, wenn es:

• Ist nicht im Abschnitt „Endet mit _PRIVATE oder _PLATFORM“ definiert.
• Hat kein #platform-only-Tag und
• Hat keine #introduce*-Tags oder das Tag stimmt mit dem Ziel überein.

VNDK

In Android.bp-Dateien unterstützen die Moduldefinitionen cc_library, cc_library_static, cc_library_shared und cc_library_headers drei VNDK-bezogene Attribute: vendor_available, vndk.enabled und vndk.support_system_process.

Wenn vendor_available oder vndk.enabled true ist, können zwei Varianten (core und vendor) erstellt werden. Die Core-Variante sollte als Framework-Modul und die Anbieter-Variante als Anbietermodul behandelt werden. Wenn einige Framework-Module von diesem Modul abhängen, wird die Core-Variante erstellt. Wenn einige Anbietermodule von diesem Modul abhängen, wird die Anbieter-Variante erstellt. Das Build-System erzwingt die folgenden Abhängigkeitsprüfungen:

• Die Core-Variante ist immer nur für das Framework verfügbar und für Anbietermodule nicht zugänglich.
• Die Anbietervariante ist für Framework-Module immer nicht zugänglich.
• Alle Abhängigkeiten der Anbieter-Variante, die in header_libs, static_libs und/oder shared_libs angegeben sind, müssen entweder ein llndk_library oder ein Modul mit vendor_available oder vndk.enabled sein.
• Wenn vendor_available gleich true ist, ist die Anbieter-Variante für alle Anbietermodule zugänglich.
• Wenn vendor_available false ist, ist die Anbietervariante nur für andere VNDK- oder VNDK-SP-Module zugänglich. Module mit vendor:true können also keine vendor_available:false-Module verknüpfen.

Der Standardinstallationspfad für cc_library oder cc_library_shared wird durch die folgenden Regeln bestimmt:

• Die Core-Variante wird in /system/lib[64] installiert.
• Der Installationspfad der Anbietervariante kann variieren:
  • Wenn vndk.enabled false ist, wird die Anbieter-Variante in /vendor/lib[64] installiert.
  • Wenn vndk.enabled true ist, wird die Anbietervariante im VNDK APEX(com.android.vndk.v${VER}) installiert.

In der folgenden Tabelle wird zusammengefasst, wie das Build-System die Anbietervarianten verarbeitet:

VNDK-Erweiterungen

VNDK-Erweiterungen sind gemeinsam genutzte VNDK-Bibliotheken mit zusätzlichen APIs. Erweiterungen werden in /vendor/lib[64]/vndk[-sp] (ohne Versionssuffix) installiert und überschreiben die ursprünglichen gemeinsam genutzten VNDK-Bibliotheken zur Laufzeit.

VNDK-Erweiterungen definieren

Unter Android 9 und höher werden VNDK-Erweiterungen von Android.bp nativ unterstützt. Um eine VNDK-Erweiterung zu erstellen, definieren Sie ein weiteres Modul mit einer vendor:true- und einer extends-Eigenschaft:

cc_library {
    name: "libvndk",
    vendor_available: true,
    vndk: {
        enabled: true,
    },
}

cc_library {
    name: "libvndk_ext",
    vendor: true,
    vndk: {
        enabled: true,
        extends: "libvndk",
    },
}

Ein Modul mit den Attributen vendor:true, vndk.enabled:true und extends definiert die VNDK-Erweiterung:

• Für die Property extends muss der Name einer gemeinsam genutzten VNDK-Basisbibliothek (oder einer gemeinsam genutzten VNDK-SP-Bibliothek) angegeben werden.
• VNDK-Erweiterungen (oder VNDK-SP-Erweiterungen) werden nach den Namen der Basismodule benannt, von denen sie abgeleitet werden. Die Ausgabedatei von libvndk_ext ist beispielsweise libvndk.so anstelle von libvndk_ext.so.
• VNDK-Erweiterungen werden in /vendor/lib[64]/vndk installiert.
• VNDK-SP-Erweiterungen werden in /vendor/lib[64]/vndk-sp installiert.
• Die gemeinsam genutzten Basisbibliotheken müssen sowohl vndk.enabled:true als auch vendor_available:true enthalten.

Eine VNDK-SP-Erweiterung muss von einer gemeinsam genutzten VNDK-SP-Bibliothek abgeleitet werden (vndk.support_system_process muss gleich sein):

cc_library {
    name: "libvndk_sp",
    vendor_available: true,
    vndk: {
        enabled: true,
        support_system_process: true,
    },
}

cc_library {
    name: "libvndk_sp_ext",
    vendor: true,
    vndk: {
        enabled: true,
        extends: "libvndk_sp",
        support_system_process: true,
    },
}

VNDK-Erweiterungen (oder VNDK-SP-Erweiterungen) können von anderen gemeinsam genutzten Anbieterbibliotheken abhängen:

cc_library {
    name: "libvndk",
    vendor_available: true,
    vndk: {
        enabled: true,
    },
}

cc_library {
    name: "libvndk_ext",
    vendor: true,
    vndk: {
        enabled: true,
        extends: "libvndk",
    },
    shared_libs: [
        "libvendor",
    ],
}

cc_library {
    name: "libvendor",
    vendor: true,
}

VNDK-Erweiterungen verwenden

Wenn ein Anbietermodul von zusätzlichen APIs abhängt, die durch VNDK-Erweiterungen definiert werden, muss das Modul den Namen der VNDK-Erweiterung in seiner shared_libs-Eigenschaft angeben:

// A vendor shared library example
cc_library {
    name: "libvendor",
    vendor: true,
    shared_libs: [
        "libvndk_ext",
    ],
}

// A vendor executable example
cc_binary {
    name: "vendor-example",
    vendor: true,
    shared_libs: [
        "libvndk_ext",
    ],
}

Wenn ein Anbietermodul von VNDK-Erweiterungen abhängt, werden diese VNDK-Erweiterungen automatisch in /vendor/lib[64]/vndk[-sp] installiert. Wenn ein Modul nicht mehr von einer VNDK-Erweiterung abhängt, fügen Sie CleanSpec.mk einen Bereinigungsschritt hinzu, um die gemeinsam genutzte Bibliothek zu entfernen. Beispiel:

$(call add-clean-step, rm -rf $(TARGET_OUT_VENDOR)/lib/libvndk.so)

Bedingte Kompilierung

In diesem Abschnitt wird beschrieben, wie Sie mit den subtilen Unterschieden (z.B. Hinzufügen oder Entfernen eines Features aus einer der Varianten) zwischen den folgenden drei gemeinsam genutzten VNDK-Bibliotheken umgehen:

• Kernvariante (z.B. /system/lib[64]/libexample.so)
• Anbietervariante (z.B. /apex/com.android.vndk.v${VER}/lib[64]/libexample.so)
• VNDK-Erweiterung (z.B. /vendor/lib[64]/vndk[-sp]/libexample.so)

Bedingte Compiler-Flags

Das Android-Build-System definiert __ANDROID_VNDK__ standardmäßig für Anbieter-Varianten und VNDK-Erweiterungen. Sie können den Code mit den C-Präprozessor-Guards schützen:

void all() { }

#if !defined(__ANDROID_VNDK__)
void framework_only() { }
#endif

#if defined(__ANDROID_VNDK__)
void vndk_only() { }
#endif

Zusätzlich zu __ANDROID_VNDK__ können in Android.bp verschiedene cflags oder cppflags angegeben werden. Die in target.vendor angegebene cflags oder cppflags ist spezifisch für die Anbieter-Variante.

Im folgenden Beispiel werden mit Android.bp die Variablen libexample und libexample_ext definiert:

cc_library {
    name: "libexample",
    srcs: ["src/example.c"],
    vendor_available: true,
    vndk: {
        enabled: true,
    },
    target: {
        vendor: {
            cflags: ["-DLIBEXAMPLE_ENABLE_VNDK=1"],
        },
    },
}

cc_library {
    name: "libexample_ext",
    srcs: ["src/example.c"],
    vendor: true,
    vndk: {
        enabled: true,
        extends: "libexample",
    },
    cflags: [
        "-DLIBEXAMPLE_ENABLE_VNDK=1",
        "-DLIBEXAMPLE_ENABLE_VNDK_EXT=1",
    ],
}

Hier ist der Code von src/example.c:

void all() { }

#if !defined(LIBEXAMPLE_ENABLE_VNDK)
void framework_only() { }
#endif

#if defined(LIBEXAMPLE_ENABLE_VNDK)
void vndk() { }
#endif

#if defined(LIBEXAMPLE_ENABLE_VNDK_EXT)
void vndk_ext() { }
#endif

Anhand dieser beiden Dateien generiert das Build-System freigegebene Bibliotheken mit den folgenden exportierten Symbolen:

Anforderungen an die exportierten Symbole

Der VNDK-ABI-Checker vergleicht die ABI von VNDK-Anbieter-Varianten und VNDK-Erweiterungen mit den Referenz-ABI-Dumps unter prebuilts/abi-dumps/vndk.

• Von VNDK-Anbietervarianten exportierte Symbole (z.B. /apex/com.android.vndk.v${VER}/lib[64]/libexample.so) müssen mit den in ABI-Dumps definierten Symbolen identisch sein (nicht deren Obermengen).
• Von VNDK-Erweiterungen exportierte Symbole (z.B. /vendor/lib[64]/vndk/libexample.so) müssen Obermengen der in ABI-Dumps definierten Symbole sein.

Wenn VNDK-Anbietervarianten oder VNDK-Erweiterungen die oben genannten Anforderungen nicht erfüllen, gibt der VNDK-ABI-Checker Build-Fehler aus und stoppt den Build.

Quelldateien oder freigegebene Bibliotheken aus Anbietervarianten ausschließen

Wenn Sie Quelldateien aus der Anbietervariante ausschließen möchten, fügen Sie sie der Eigenschaft exclude_srcs hinzu. Damit freigegebene Bibliotheken nicht mit der Anbieter-Variante verknüpft werden, fügen Sie sie der Eigenschaft exclude_shared_libs hinzu. Beispiel:

cc_library {
    name: "libexample_cond_exclude",
    srcs: ["fwk.c", "both.c"],
    shared_libs: ["libfwk_only", "libboth"],
    vendor_available: true,
    target: {
        vendor: {
            exclude_srcs: ["fwk.c"],
            exclude_shared_libs: ["libfwk_only"],
        },
    },
}

In diesem Beispiel enthält die Core-Variante von libexample_cond_exclude den Code aus fwk.c und both.c und hängt von den gemeinsam genutzten Bibliotheken libfwk_only und libboth ab. Die Anbieter-Variante von libexample_cond_exclude enthält nur den Code aus both.c, da fwk.c durch die Property exclude_srcs ausgeschlossen wird. Ebenso hängt sie nur von der freigegebenen Bibliothek libboth ab, da libfwk_only durch die Property exclude_shared_libs ausgeschlossen wird.

Header aus VNDK-Erweiterungen exportieren

Eine VNDK-Erweiterung kann einer gemeinsam genutzten VNDK-Bibliothek neue Klassen oder Funktionen hinzufügen. Es wird empfohlen, diese Deklarationen in unabhängigen Headern zu belassen und die vorhandenen Header nicht zu ändern.

Für die VNDK-Erweiterung libexample_ext wird beispielsweise eine neue Headerdatei include-ext/example/ext/feature_name.h erstellt:

• Android.bp
• include-ext/example/ext/feature_name.h
• include/example/example.h
• src/example.c
• src/ext/feature_name.c

Im folgenden Beispiel exportiert Android.bp nur include, während libexample_ext sowohl include als auch include-ext exportiert.libexample So wird verhindert, dass feature_name.h von Nutzern von libexample fälschlicherweise einbezogen wird:

cc_library {
    name: "libexample",
    srcs: ["src/example.c"],
    export_include_dirs: ["include"],
    vendor_available: true,
    vndk: {
        enabled: true,
    },
}

cc_library {
    name: "libexample_ext",
    srcs: [
        "src/example.c",
        "src/ext/feature_name.c",
    ],
    export_include_dirs: [
        "include",
        "include-ext",
    ],
    vendor: true,
    vndk: {
        enabled: true,
        extends: "libexample",
    },
}

Wenn es nicht möglich ist, Erweiterungen in unabhängige Headerdateien aufzuteilen, können Sie stattdessen #ifdef-Guards hinzufügen. Achten Sie jedoch darauf, dass alle Nutzer der VNDK-Erweiterung die Define-Flags hinzufügen. Sie können cc_defaults definieren, um cflags Define-Flags hinzuzufügen und gemeinsam genutzte Bibliotheken mit shared_libs zu verknüpfen.

Wenn Sie beispielsweise der VNDK-Erweiterung libexample2_ext eine neue Member-Funktion Example2::get_b() hinzufügen möchten, müssen Sie die vorhandene Headerdatei ändern und einen #ifdef-Schutz hinzufügen:

#ifndef LIBEXAMPLE2_EXAMPLE_H_
#define LIBEXAMPLE2_EXAMPLE_H_

class Example2 {
 public:
  Example2();

  void get_a();

#ifdef LIBEXAMPLE2_ENABLE_VNDK_EXT
  void get_b();
#endif

 private:
  void *impl_;
};

#endif  // LIBEXAMPLE2_EXAMPLE_H_

Für die Nutzer von libexample2_ext ist eine cc_defaults mit dem Namen libexample2_ext_defaults definiert:

cc_library {
    name: "libexample2",
    srcs: ["src/example2.cpp"],
    export_include_dirs: ["include"],
    vendor_available: true,
    vndk: {
        enabled: true,
    },
}

cc_library {
    name: "libexample2_ext",
    srcs: ["src/example2.cpp"],
    export_include_dirs: ["include"],
    vendor: true,
    vndk: {
        enabled: true,
        extends: "libexample2",
    },
    cflags: [
        "-DLIBEXAMPLE2_ENABLE_VNDK_EXT=1",
    ],
}

cc_defaults {
    name: "libexample2_ext_defaults",
    shared_libs: [
        "libexample2_ext",
    ],
    cflags: [
        "-DLIBEXAMPLE2_ENABLE_VNDK_EXT=1",
    ],
}

Nutzer von libexample2_ext können libexample2_ext_defaults einfach in ihre defaults-Property einfügen:

cc_binary {
    name: "example2_user_executable",
    defaults: ["libexample2_ext_defaults"],
    vendor: true,
}

Produktpakete

Im Android-Build-System gibt die Variable PRODUCT_PACKAGES die ausführbaren Dateien, gemeinsam genutzten Bibliotheken oder Pakete an, die auf dem Gerät installiert werden sollen. Die transitiven Abhängigkeiten der angegebenen Module werden ebenfalls implizit auf dem Gerät installiert.

Wenn BOARD_VNDK_VERSION aktiviert ist, werden Module mit vendor_available oder vndk.enabled besonders behandelt. Wenn ein Framework-Modul von einem Modul mit vendor_available oder vndk.enabled abhängt, ist die Core-Variante im transitiven Installationssatz enthalten. Wenn ein Anbietermodul von einem Modul mit vendor_available abhängt, ist die Anbieter-Variante im transitiven Installationssatz enthalten. Anbietervarianten von Modulen mit vndk.enabled werden jedoch installiert, unabhängig davon, ob sie von Anbietermodulen verwendet werden.

Wenn die Abhängigkeiten für das Build-System unsichtbar sind (z.B. freigegebene Bibliotheken, die zur Laufzeit mit dlopen() geöffnet werden können), sollten Sie die Modulnamen in PRODUCT_PACKAGES angeben, um diese Module explizit zu installieren.

Wenn ein Modul vendor_available oder vndk.enabled enthält, steht der Modulname für die Kernvariante. Wenn Sie die Anbieter-Variante in PRODUCT_PACKAGES explizit angeben möchten, hängen Sie das Suffix .vendor an den Modulnamen an. Beispiel:

cc_library {
    name: "libexample",
    srcs: ["example.c"],
    vendor_available: true,
}

In diesem Beispiel steht libexample für /system/lib[64]/libexample.so und libexample.vendor für /vendor/lib[64]/libexample.so. So installieren Sie /vendor/lib[64]/libexample.so: Fügen Sie libexample.vendor zu PRODUCT_PACKAGES hinzu:

PRODUCT_PACKAGES += libexample.vendor