Guide de création de règles

Introduction

L'API en bac à sable (SAPI) peut être utilisée avec le système de compilation Bazel de Google ou avec le système de compilation Meta populaire 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 disposerez d'une règle de compilation permettant de créer votre code hôte. Pour que le code hôte utilise la version en 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 en bac à sable qui remplace la valeur normale cc_library comme cible du code hôte. Se compose de zlib_sapi.bin et de dépendances de bac à sable.
• name.interface: interface de la bibliothèque générée.
• name.embed: cible cc_embed_data() utilisée pour intégrer la Sandboxee dans le binaire. Voir bazel/embed_data.bzl.
• name.bin: binaire Sandboxee se compose d'un petit bouchon de communication et de la bibliothèque en bac à sable.

Arguments

Attributs
name	Nom ; obligatoire Nom unique pour cette cible. Cela permettra d'identifier la bibliothèque C/C++ en bac à sable (voir la cible de sortie name-sapi).
dépendances	Liste des libellés (facultatif) Liste des autres bibliothèques à associer à la bibliothèque C/C++ en bac à sable.
SRC	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++, qui ne sont ni générés (code source normal), ni générés. Pour en savoir plus, consultez la description de l'attribut srcs dans la documentation sur cc_library.
HDrs	Liste des libellés (facultatif) Liste des fichiers d'en-tête traités pour créer la bibliothèque C/C++ en bac à sable. C'est ici que la définition du bac à sable (sandbox.h) doit être placée. Laissez ce champ vide si la bibliothèque SAPI intégrée est utilisée et si la règle de bac à sable par défaut est suffisante.
intégrer une vidéo sur un site	Booléen ; facultatif ; la valeur par défaut est True Si la valeur est "True", la bibliothèque en bac à sable doit être intégrée dans le code de l'hôte. Cela permet d'initialiser le bac à sable SAPI avec le constructeur ::sapi::Sandbox::Sandbox(FileToc*).
functions	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 tente d'exporter et d'encapsuler toutes les fonctions trouvées dans la bibliothèque.
lib	Chaîne ; obligatoire Nom de la cible de bibliothèque C/C++ qui sera la bibliothèque en bac à sable. Vous devez disposer d'une règle de compilation cc_library pour la bibliothèque C/C++ dans le projet.
lib_name	Chaîne ; obligatoire Nom de l'objet SAPI qui est utilisé pour envoyer par proxy les fonctions de la bibliothèque à partir de l'attribut de fonctions. Tout appel à la fonction dans la bibliothèque en bac à sable est effectué via l'objet SAPI.
input_files	Liste des libellés (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 à la recherche des déclarations de fonction de la bibliothèque C/C++. Cela n'est surtout 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 à la place 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 un mécanisme de secours pour ces situations complexes. N'utilisez cette fonctionnalité que si nécessaire.
tags	Consultez la documentation Bazel pour plus d'informations sur les tags.
visibilité	Consulter la documentation Bazel pour plus d'informations sur la visibilité

Exemple d'utilisation

L'exemple zlib est un bon projet de référence qui illustre l'utilisation de la règle de compilation sapi_library:

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