Guide de création de règles

Introduction

L'API bac à sable (SAPI) peut être utilisée avec le système de compilation Bazel de Google ou avec le système de métacompilation CMake. Cette page se concentre sur Bazel, mais les mêmes fonctionnalités sont disponibles pour CMake. Bazel est le système de compilation recommandé et le plus facile à intégrer.

Dans votre fichier BUILD.bazel, vous trouverez une règle de compilation pour compiler votre code hôte. Pour que le code hôte utilise la version bac à sable d'une bibliothèque, vous devez préparer une cible de compilation que votre code hôte utilisera.

Règles de compilation SAPI

• sapi_library

sapi_library

sapi_library(name, deps, srcs, hdrs, embed, functions, lib, lib_name, input_files, namespace, header, add_default_deps, limit_scan_depth, visibility)

Cibles de sortie

La règle de compilation sapi_library() génère les cibles suivantes :

• name-sapi : bibliothèque sandboxée, remplace la bibliothèque cc_library normale en tant que cible du code hôte. Il se compose de zlib_sapi.bin et des dépendances du bac à sable.
• name.interface : interface de bibliothèque générée.
• name.embed : cc_embed_data() cible utilisée pour intégrer le Sandboxee dans le binaire. Voir bazel/embed_data.bzl.
  • name.bin : binaire Sandboxee, composé d'un petit stub de communication et de la bibliothèque mise en bac à sable.

Arguments

Attributs
nom	Name (obligatoire) Nom unique de cette cible. Cela permettra d'identifier la bibliothèque C/C++ en bac à sable. Consultez la cible de sortie name-sapi.
dépendances	Liste des libellés ; facultatif Liste des autres bibliothèques à inclure dans la bibliothèque C/C++ en bac à sable.
srcs	Liste des libellés ; facultatif Liste des fichiers C et C++ traités pour créer la bibliothèque C/C++ en bac à sable. Il s'agit de fichiers sources et d'en-tête C/C++, générés ou non (code source normal). Pour en savoir plus, consultez l'explication de l'attribut srcs dans la documentation cc_library.
hdrs	Liste des étiquettes (facultatif) Liste des fichiers d'en-tête traités pour créer la bibliothèque C/C++ en bac à sable. C'est là que la définition du bac à sable (sandbox.h) doit être placée. Laissez vide si la bibliothèque SAPI intégrée est utilisée et que la règle de bac à sable par défaut est suffisante.
intégrer	Booléen ; facultatif ; la valeur par défaut est "True" Si la valeur est "true", la bibliothèque sandboxée doit être intégrée au code hôte. Cela permet d'initialiser le bac à sable SAPI avec le constructeur ::sapi::Sandbox::Sandbox(FileToc*).
sans serveur	Liste des noms de fonctions (facultatif) Liste des fonctions de la bibliothèque C/C++ pour lesquelles une version en bac à sable est générée et qui peuvent ensuite être utilisées dans le code hôte. Une liste vide tentera d'exporter et d'encapsuler toutes les fonctions trouvées dans la bibliothèque.
lib	Chaîne ; obligatoire Nom de la cible de la bibliothèque C/C++ qui sera la bibliothèque sandboxée. Cela suppose que vous disposez d'une règle de compilation cc_library pour la bibliothèque C/C++ du projet.
lib_name	Chaîne ; obligatoire Nom de l'objet SAPI utilisé pour le proxy des fonctions de bibliothèque à partir de l'attribut "functions". Tout appel à la fonction dans la bibliothèque sandboxée se fera via l'objet SAPI.
input_files	Liste des étiquettes (facultatif) Liste des fichiers C et C++ traités lors de l'exécution interne de la règle sapi_interface. Le générateur analyse ces fichiers pour trouver les déclarations de fonction de la bibliothèque C/C++. Ce n'est généralement pas nécessaire, car les en-têtes exportés de la bibliothèque C/C++ sont toujours analysés.
espace de noms	Chaîne ; facultatif ; la valeur par défaut est "sapigen" Identifiant d'espace de noms C++ dans lequel placer l'objet SAPI défini par lib_name. L'espace de noms par défaut est sapigen.
en-tête	Chaîne ; facultatif Nom du fichier d'en-tête à utiliser au lieu du fichier d'en-tête généré. Si vous souhaitez générer automatiquement le code, n'utilisez pas cet attribut.
add_default_deps	Booléen ; facultatif ; la valeur par défaut est "True" OBSOLÈTE
limit_scan_depth	Booléen ; facultatif ; la valeur par défaut est "False" Pour les bibliothèques complexes, le nombre de fichiers pour Bazel peut être atteint et le processus de compilation échouera. Cet attribut est une porte de sortie pour ces situations complexes. Ne pas utiliser, sauf si nécessaire.
tags	Consultez la documentation Bazel pour en savoir plus sur les tags.
visibility	Consultez la documentation Bazel sur la visibilité.

Exemple d'utilisation

L'exemple zlib est un bon projet de référence qui montre comment la règle de compilation sapi_library est utilisée :

load(
    "//sandboxed_api/tools/generator:sapi_generator.bzl",
    "sapi_library",
)

sapi_library(
    name = "zlib-sapi",
    srcs = [],     # Extra code compiled with the SAPI library
    hdrs = [],     # Leave empty if embedded SAPI libraries are used, and the
                   # default sandbox policy is sufficient.
    embed = True,  # This is the default
    functions = [
        "deflateInit_",
        "deflate",
        "deflateEnd",
    ],
    lib = "@zlib//:zlibonly",
    lib_name = "Zlib",
    namespace = "sapi::zlib",
)