Prise en charge du système de génération VNDK

Dans Android 8.1 et versions ultérieures, le système de construction a un support VNDK intégré. Lorsque la prise en charge de VNDK est activée, le système de génération vérifie les dépendances entre les modules, crée une variante spécifique au fournisseur pour les modules du fournisseur et installe automatiquement ces modules dans les répertoires désignés.

Exemple de prise en charge de la génération VNDK

Dans cet exemple, la définition du module Android.bp définit une bibliothèque nommée libexample . La propriété vendor_available indique que les modules du framework et les modules du fournisseur peuvent dépendre de libexample :

libexample vendor_available:true et vndk.enabled:true

Figure 1. Prise en charge de VNDK activée

L'exécutable du framework /system/bin/foo et l'exécutable du fournisseur /vendor/bin/bar dépendent de libexample et ont libexample dans leurs propriétés shared_libs .

Si libexample est utilisé à la fois par les modules du framework et les modules du fournisseur, deux variantes de libexample sont construites. La variante de base (nommée d'après libexample ) est utilisée par les modules de framework et la variante de fournisseur (nommée d'après libexample.vendor ) est utilisée par les modules de fournisseur. Les deux variantes sont installées dans des répertoires différents :

  • La variante principale est installée dans /system/lib[64]/libexample.so .
  • La variante du fournisseur est installée dans VNDK APEX car vndk.enabled est true .

Pour plus de détails, voir Définition du module .

Configuration de la prise en charge de la génération

Pour activer la prise en charge complète du système de build pour un périphérique de produit, ajoutez BOARD_VNDK_VERSION à BoardConfig.mk :

BOARD_VNDK_VERSION := current

Ce paramètre a un effet global : lorsqu'il est défini dans BoardConfig.mk , tous les modules sont vérifiés. Comme il n'existe aucun mécanisme pour mettre sur liste noire ou sur liste blanche un module incriminé, vous devez nettoyer toutes les dépendances inutiles avant d'ajouter BOARD_VNDK_VERSION . Vous pouvez tester et compiler un module en définissant BOARD_VNDK_VERSION dans vos variables d'environnement :

$ BOARD_VNDK_VERSION=current m module_name.vendor

Lorsque BOARD_VNDK_VERSION est activé, plusieurs chemins de recherche d'en-tête globaux par défaut sont supprimés . Ceux-ci inclus:

  • 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

Si un module dépend des en-têtes de ces répertoires, vous devez spécifier (explicitement) les dépendances avec header_libs , static_libs et/ou shared_libs .

APEX VNDK

Dans Android 10 et versions antérieures, les modules avec vndk.enabled étaient installés dans /system/lib[64]/vndk[-sp]-${VER} . Dans Android 11 et versions ultérieures, les bibliothèques VNDK sont empaquetées au format APEX et le nom de VNDK APEX est com.android.vndk.v${VER} . Selon la configuration de l'appareil, VNDK APEX est aplati ou non et est disponible à partir du chemin canonique /apex/com.android.vndk.v${VER} .

APEX VNDK

Figure 2. APEX VNDK

Définition des modules

Pour compiler Android avec BOARD_VNDK_VERSION , vous devez réviser la définition du module dans Android.mk ou Android.bp . Cette section décrit différents types de définitions de module, plusieurs propriétés de module liées à VNDK et les vérifications de dépendance implémentées dans le système de génération.

Modules vendeurs

Les modules fournisseur sont des exécutables spécifiques au fournisseur ou des bibliothèques partagées qui doivent être installés dans une partition fournisseur. Dans les fichiers Android.bp , les modules de fournisseur doivent définir la propriété vendor ou propriétaire sur true . Dans les fichiers Android.mk , les modules de fournisseur doivent définir LOCAL_VENDOR_MODULE ou LOCAL_PROPRIETARY_MODULE sur true .

Si BOARD_VNDK_VERSION est défini, le système de construction interdit les dépendances entre les modules du fournisseur et les modules du framework et émet des erreurs si :

  • un module sans vendor:true dépend d'un module avec vendor:true , ou
  • un module avec vendor:true dépend d'un module non- llndk_library qui n'a ni vendor:true ni vendor_available:true .

La vérification des dépendances s'applique à header_libs , static_libs et shared_libs dans Android.bp , et à LOCAL_HEADER_LIBRARIES , LOCAL_STATIC_LIBRARIES et LOCAL_SHARED_LIBRARIES dans Android.mk .

LL-NDK

Les bibliothèques partagées LL-NDK sont des bibliothèques partagées avec des ABI stables. Les modules de framework et de fournisseur partagent la même implémentation et la dernière. Pour chaque bibliothèque partagée LL-NDK, Android.bp contient une définition de module llndk_library :

llndk_library {
    name: "libvndksupport",
    symbol_file: "libvndksupport.map.txt",
}

Cette définition de module spécifie un nom de module et un fichier de symboles décrivant les symboles visibles pour les modules du fournisseur. Par exemple:

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

Sur la base du fichier de symboles, le système de génération génère une bibliothèque partagée de stub pour les modules de fournisseur, qui se lient à ces bibliothèques lorsque BOARD_VNDK_VERSION est activé. Un symbole est inclus dans la bibliothèque partagée de stub uniquement s'il :

  • N'est pas défini dans la section se terminant par _PRIVATE ou _PLATFORM ,
  • N'a pas de balise #platform-only , et
  • N'a pas de balises #introduce* ou la balise correspond à la cible.

VNDKName

Dans les fichiers Android.bp , les définitions de module cc_library , cc_library_static , cc_library_shared et cc_library_headers prennent en charge trois propriétés liées à VNDK : vendor_available , vndk.enabled et vndk.support_system_process .

Si vendor_available ou vndk.enabled est true , deux variantes ( core et vendor ) peuvent être construites. La variante principale doit être traitée comme un module de structure et la variante fournisseur doit être traitée comme un module fournisseur. Si certains modules du framework dépendent de ce module, la variante de base est construite. Si certains modules du fournisseur dépendent de ce module, la variante du fournisseur est construite. Le système de compilation applique les vérifications de dépendance suivantes :

  • La variante de base est toujours réservée au framework et inaccessible aux modules du fournisseur.
  • La variante du fournisseur est toujours inaccessible aux modules du framework.
  • Toutes les dépendances de la variante du fournisseur, qui sont spécifiées dans header_libs , static_libs et/ou shared_libs , doivent être soit une llndk_library soit un module avec vendor_available ou vndk.enabled .
  • Si vendor_available est true , la variante du fournisseur est accessible à tous les modules du fournisseur.
  • Si vendor_available est false , la variante du fournisseur n'est accessible qu'aux autres modules VNDK ou VNDK-SP (c'est-à-dire que les modules avec vendor:true ne peuvent pas lier les modules vendor_available:false ).

Le chemin d'installation par défaut de cc_library ou cc_library_shared est déterminé par les règles suivantes :

  • La variante principale est installée dans /system/lib[64] .
  • Le chemin d'installation de la variante du fournisseur peut varier :
    • Si vndk.enabled est false , la variante du fournisseur est installée dans /vendor/lib[64] .
    • Si vndk.enabled est true , la variante du fournisseur est installée dans VNDK APEX( com.android.vndk.v${VER} ).

Le tableau ci-dessous résume la manière dont le système de génération gère les variantes du fournisseur :

fournisseur_disponible vndk
autorisé		 vndk
support_same_process		 Descriptions des variantes du fournisseur
true false false Les variantes du fournisseur sont VND-ONLY . Les bibliothèques partagées sont installées dans /vendor/lib[64] .
true Non valide (erreur de construction)
true false Les variantes du fournisseur sont VNDK . Les bibliothèques partagées sont installées sur VNDK APEX.
true Les variantes du fournisseur sont VNDK-SP . Les bibliothèques partagées sont installées sur VNDK APEX.

false

false

false

Aucune variante de fournisseur. Ce module est FWK UNIQUEMENT .

true Non valide (erreur de construction)
true false Les variantes du fournisseur sont VNDK-Private . Les bibliothèques partagées sont installées sur VNDK APEX. Ceux-ci ne doivent pas être directement utilisés par les modules du fournisseur.
true Les variantes du fournisseur sont VNDK-SP-Private . Les bibliothèques partagées sont installées sur VNDK APEX. Ceux-ci ne doivent pas être directement utilisés par les modules du fournisseur.

Extensions VNDK

Les extensions VNDK sont des bibliothèques partagées VNDK avec des API supplémentaires. Les extensions sont installées sur /vendor/lib[64]/vndk[-sp] (sans suffixe de version) et remplacent les bibliothèques partagées VNDK d'origine lors de l'exécution.

Définition des extensions VNDK

Dans Android 9 et supérieur, Android.bp prend en charge nativement les extensions VNDK. Pour créer une extension VNDK, définissez un autre module avec une propriété vendor:true et une propriété extends :

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

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

Un module avec les propriétés vendor:true , vndk.enabled:true et extend définit l' extends VNDK :

  • La propriété extends doit spécifier un nom de bibliothèque partagée VNDK de base (ou un nom de bibliothèque partagée VNDK-SP).
  • Les extensions VNDK (ou extensions VNDK-SP) sont nommées d'après les noms des modules de base à partir desquels elles s'étendent. Par exemple, le binaire de sortie de libvndk_ext est libvndk.so au lieu de libvndk_ext.so .
  • Les extensions VNDK sont installées dans /vendor/lib[64]/vndk .
  • Les extensions VNDK-SP sont installées dans /vendor/lib[64]/vndk-sp .
  • Les bibliothèques partagées de base doivent avoir à la fois vndk.enabled:true et vendor_available:true .

Une extension VNDK-SP doit s'étendre à partir d'une bibliothèque partagée VNDK-SP ( vndk.support_system_process doit être égal) :

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

Les extensions VNDK (ou extensions VNDK-SP) peuvent dépendre de bibliothèques partagées d'autres fournisseurs :

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

Utilisation des extensions VNDK

Si un module fournisseur dépend d'API supplémentaires définies par des extensions VNDK, le module doit spécifier le nom de l'extension VNDK dans sa propriété shared_libs :

// 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",
    ],
}

Si un module fournisseur dépend des extensions VNDK, ces extensions VNDK sont automatiquement installées dans /vendor/lib[64]/vndk[-sp] . Si un module ne dépend plus d'une extension VNDK, ajoutez une étape propre à CleanSpec.mk pour supprimer la bibliothèque partagée. Par exemple:

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

Compilation conditionnelle

Cette section décrit comment gérer les différences subtiles (par exemple, ajouter ou supprimer une fonctionnalité de l'une des variantes) entre les trois bibliothèques partagées VNDK suivantes :

  • Variante de base (par exemple /system/lib[64]/libexample.so )
  • Variante du fournisseur (par exemple /apex/com.android.vndk.v${VER}/lib[64]/libexample.so )
  • Extension VNDK (par exemple /vendor/lib[64]/vndk[-sp]/libexample.so )

Drapeaux conditionnels du compilateur

Le système de build Android définit __ANDROID_VNDK__ pour les variantes du fournisseur et les extensions VNDK par défaut. Vous pouvez protéger le code avec les gardes du préprocesseur C :

void all() { }

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

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

En plus de __ANDROID_VNDK__ , différents cflags ou cppflags peuvent être spécifiés dans Android.bp . Les cflags ou cppflags spécifiés dans target.vendor sont spécifiques à la variante du fournisseur.

Par exemple, le fichier Android.bp suivant définit libexample et libexample_ext :

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

Et voici la liste de code de 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

Selon ces deux fichiers, le système de construction génère des bibliothèques partagées avec les symboles exportés suivants :

Chemin d'installation Symboles exportés
/system/lib[64]/libexample.so all , framework_only
/apex/com.android.vndk.v${VER}/lib[64]/libexample.so all , vndk
/vendor/lib[64]/vndk/libexample.so all , vndk , vndk_ext

Exigences sur les symboles exportés

Le vérificateur d' ABI VNDK compare l'ABI des variantes du fournisseur VNDK et des extensions VNDK aux vidages ABI de référence sous prebuilts/abi-dumps/vndk .

  • Les symboles exportés par les variantes du fournisseur VNDK (par exemple /apex/com.android.vndk.v${VER}/lib[64]/libexample.so ) doivent être identiques (et non les surensembles) aux symboles définis dans les vidages ABI.
  • Les symboles exportés par les extensions VNDK (par exemple /vendor/lib[64]/vndk/libexample.so ) doivent être des surensembles des symboles définis dans les vidages ABI.

Si les variantes du fournisseur VNDK ou les extensions VNDK ne respectent pas les exigences ci-dessus, le vérificateur VNDK ABI émet des erreurs de construction et arrête la construction.

Exclusion des fichiers source ou des bibliothèques partagées des variantes du fournisseur

Pour exclure les fichiers source de la variante du fournisseur, ajoutez-les à la propriété exclude_srcs . De même, pour vous assurer que les bibliothèques partagées ne sont pas liées à la variante du fournisseur, ajoutez ces bibliothèques à la propriété exclude_shared_libs . Par exemple:

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

Dans cet exemple, la variante principale de libexample_cond_exclude inclut le code de fwk.c et both.c et dépend des bibliothèques partagées libfwk_only et libboth . La variante fournisseur de libexample_cond_exclude inclut uniquement le code de both.c car fwk.c est exclu par la propriété exclude_srcs . De même, cela dépend uniquement de la bibliothèque partagée libboth car libfwk_only est exclu par la propriété exclude_shared_libs .

Exporter les en-têtes des extensions VNDK

Une extension VNDK peut ajouter de nouvelles classes ou de nouvelles fonctions à une bibliothèque partagée VNDK. Il est suggéré de conserver ces déclarations dans des en-têtes indépendants et d'éviter de modifier les en-têtes existants.

Par exemple, un nouveau fichier d'en-tête include-ext/example/ext/feature_name.h est créé pour l'extension libexample_ext :

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

Dans le fichier Android.bp suivant, libexample exporte uniquement include , tandis que libexample_ext exporte à la fois include et include-ext . Cela garantit que feature_name.h ne sera pas inclus par erreur par les utilisateurs de libexample :

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

S'il n'est pas possible de séparer les extensions en fichiers d'en-tête indépendants, une alternative consiste à ajouter des gardes #ifdef . Cependant, assurez-vous que tous les utilisateurs de l'extension VNDK ajoutent les indicateurs de définition. Vous pouvez définir cc_defaults pour ajouter des indicateurs de définition à cflags et lier des bibliothèques partagées avec shared_libs .

Par exemple, pour ajouter une nouvelle fonction membre Example2::get_b() à l'extension libexample2_ext , vous devez modifier le fichier d'en-tête existant et ajouter une garde #ifdef :

#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_

Un cc_defaults nommé libexample2_ext_defaults est défini pour les utilisateurs de libexample2_ext :

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

Les utilisateurs de libexample2_ext peuvent simplement inclure libexample2_ext_defaults dans leur propriété defaults :

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

Packs de produits

Dans le système de construction Android, la variable PRODUCT_PACKAGES spécifie les exécutables, les bibliothèques partagées ou les packages qui doivent être installés sur l'appareil. Les dépendances transitives des modules spécifiés sont également implicitement installées dans l'appareil.

Si BOARD_VNDK_VERSION est activé, les modules avec vendor_available ou vndk.enabled bénéficient d'un traitement spécial. Si un module de structure dépend d'un module avec vendor_available ou vndk.enabled , la variante principale est incluse dans l'ensemble d'installation transitive. Si un module fournisseur dépend d'un module avec vendor_available , la variante fournisseur est incluse dans l'ensemble d'installation transitive. Cependant, les variantes du fournisseur des modules avec vndk.enabled sont installées, qu'elles soient ou non utilisées par les modules du fournisseur.

Lorsque les dépendances sont invisibles pour le système de construction (par exemple, les bibliothèques partagées qui peuvent être ouvertes avec dlopen() lors de l'exécution), vous devez spécifier les noms de module dans PRODUCT_PACKAGES pour installer ces modules explicitement.

Si un module a vendor_available ou vndk.enabled , le nom du module représente sa variante principale. Pour spécifier explicitement la variante du fournisseur dans PRODUCT_PACKAGES , ajoutez un suffixe .vendor au nom du module. Par exemple:

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

Dans cet exemple, libexample signifie /system/lib[64]/libexample.so et libexample.vendor signifie /vendor/lib[64]/libexample.so . Pour installer /vendor/lib[64]/libexample.so , ajoutez libexample.vendor à PRODUCT_PACKAGES :

PRODUCT_PACKAGES += libexample.vendor