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

Sous Android 8.1 et versions ultérieures, le système de build prend en charge VNDK intégré. Lorsque la prise en charge de VNDK est activée, le système de build 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 support de build 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 :

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 par les modules du fournisseur, deux variantes de libexample sont construites. La variante principale (nommée d'après libexample ) est utilisée par les modules du framework et la variante du fournisseur (nommée d'après libexample.vendor ) est utilisée par les modules du 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 build

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

Sous Android 10 et versions antérieures, les modules avec vndk.enabled ont été installés dans /system/lib[64]/vndk[-sp]-${VER} . Sous Android 11 et versions ultérieures, les bibliothèques VNDK sont regroupé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} .

Définition des modules

Pour créer 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 modules, plusieurs propriétés de modules liées au VNDK et les contrôles de dépendances implémentés dans le système de build.

Modules fournisseurs

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 fournisseur doivent définir la propriété fournisseur ou propriétaire sur true . Dans les fichiers Android.mk , les modules du fournisseur doivent définir LOCAL_VENDOR_MODULE ou LOCAL_PROPRIETARY_MODULE sur true .

Si BOARD_VNDK_VERSION est défini, le système de build interdit les dépendances entre les modules fournisseur et les modules 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 , ainsi qu'à 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 du framework et du fournisseur partagent la même et la dernière implémentation. Pour chaque bibliothèque partagée LL-NDK, la cc_library contient une propriété llndk avec un fichier de symboles :

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

Le fichier de symboles décrit les symboles visibles par 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 construction génère une bibliothèque partagée stub pour les modules du fournisseur, qui sont liés à ces bibliothèques lorsque BOARD_VNDK_VERSION est activé. Un symbole est inclus dans la bibliothèque partagée stub uniquement s'il :

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

VNDK

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 supplier ) peuvent être construites. La variante principale doit être traitée comme un module de structure et la variante du fournisseur doit être traitée comme un module du fournisseur. Si certains modules du framework dépendent de ce module, la variante principale est construite. Si certains modules du fournisseur dépendent de ce module, la variante du fournisseur est construite. Le système de build applique les contrôles de dépendance suivants :

• La variante principale est toujours uniquement basée sur le 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 sur /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 build gère les variantes du fournisseur :

Extensions VNDK

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

Définir les extensions VNDK

Sous Android 9 et versions ultérieures, Android.bp prend en charge nativement les extensions VNDK. Pour créer une extension VNDK, définissez un autre module avec un 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 vendor:true , vndk.enabled:true et extends définit l'extension 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,
}

Utiliser les extensions VNDK

Si un module fournisseur dépend d'API supplémentaires définies par les 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, l'ajout ou la suppression d'une fonctionnalité de l'une des variantes) entre les trois bibliothèques partagées VNDK suivantes :

• Variante principale (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 )

Indicateurs conditionnels du compilateur

Le système de build Android définit par défaut __ANDROID_VNDK__ pour les variantes du fournisseur et les extensions VNDK. Vous pouvez protéger le code avec les protections 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 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 des codes 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 build génère des bibliothèques partagées avec les symboles exportés suivants :

Exigences sur les symboles exportés

Le vérificateur ABI VNDK compare l'ABI des variantes du fournisseur VNDK et des extensions VNDK aux dumps 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 aux surensembles) des symboles définis dans les dumps 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 dumps ABI.

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

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

Pour exclure les fichiers source de la variante du fournisseur, ajoutez-les à la exclude_srcs . De même, pour garantir que les bibliothèques partagées ne sont pas liées à la variante du fournisseur, ajoutez ces bibliothèques à la 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 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 VNDK 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 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 de manière incorrecte 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 aux cflags et lier les bibliothèques partagées avec shared_libs .

Par exemple, pour ajouter une nouvelle fonction membre Example2::get_b() à l'extension VNDK 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,
}

Paquets de produits

Dans le système de build 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 le périphérique.

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 du fournisseur est incluse dans l'ensemble d'installation transitive. Cependant, les variantes des modules du fournisseur 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 build (par exemple des bibliothèques partagées qui peuvent être ouvertes avec dlopen() au moment de l'exécution), vous devez spécifier les noms de modules 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