Guida alle regole di creazione

Introduzione

L'API Sandboxed (SAPI) può essere utilizzata con il sistema di build Bazel di Google o con il noto sistema di build CMake. Questa pagina è incentrata su Bazel, ma le stesse funzionalità sono disponibili per CMake. Bazel è il sistema di compilazione consigliato e il più facile da integrare.

Nel file BUILD.bazel sarà presente una regola di compilazione per creare il codice host. Affinché il codice host utilizzi la versione con sandbox di una libreria, devi preparare una destinazione di build che verrà utilizzata dal codice host.

Regole di creazione SAPI

• libreria_sapi

libreria_sapi

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

Target di output

La regola di compilazione sapi_library() genera i seguenti target:

• name-sapi: libreria con sandbox, sostituisce la normale cc_library come destinazione del codice host. Composto da zlib_sapi.bin e dipendenze sandbox.
• name.interface: interfaccia della libreria generata.
• name.embed: target cc_embed_data() utilizzato per incorporare il Sandboxee nel programma binario. Consulta bazel/embed_data.bzl.
• name.bin: il programma binario di Sandboxee, è costituito da un piccolo stub di comunicazione e dalla raccolta tramite sandbox.

Argomenti

Attributi
name	Nome; è obbligatorio Un nome univoco per questo target. Questo identificherà la libreria C/C++ con sandbox, vedi il target di output name-sapi.
dep	Elenco di etichette; facoltativo Un elenco di altre librerie da collegare nella libreria C/C++ con sandbox.
src	Elenco di etichette; facoltativo Un elenco dei file C e C++ che vengono elaborati per creare la libreria C/C++ con sandbox. Si tratta di file sorgente e intestazione C/C++, non generati (codice sorgente normale) o generati. Per ulteriori informazioni, consulta la spiegazione degli attributi src nella documentazione di cc_library.
hdr	Elenco di etichette; facoltativo Un elenco dei file di intestazione che vengono elaborati per creare la libreria C/C++ con sandbox. Qui deve essere la definizione di sandbox (sandbox.h); lascia vuota la pagina se viene utilizzata la libreria SAPI incorporata e se è sufficiente il criterio predefinito per la sandbox.
codice da incorporare	Booleano; facoltativo; il valore predefinito è True Se il valore è True, la libreria con sandbox deve essere incorporata nel codice host. Ciò consente l'inizializzazione della sandbox SAPI con il costruttore ::sapi::Sandbox::Sandbox(FileToc*).
funzioni	Elenco di nomi di funzioni; facoltativo Un elenco di funzioni della libreria C/C++ per le quali viene generata una versione con sandbox e che possono essere utilizzate nel codice host. L'elenco vuoto tenterà di esportare e eseguire il wrapping di tutte le funzioni trovate nella libreria.
lib	Stringa; obbligatorio Il nome della libreria C/C++ di destinazione che sarà la libreria con sandbox. È previsto che nel progetto sia presente una regola di compilazione cc_library per la libreria C/C++.
nome_libreria	Stringa; obbligatorio Il nome dell'oggetto SAPI utilizzato per eseguire il proxy delle funzioni della libreria dall'attributo Functions. Qualsiasi chiamata alla funzione nella libreria con sandbox avviene tramite l'oggetto SAPI.
file_input	Elenco di etichette; facoltativo Un elenco dei file C e C++ che vengono elaborati durante l'esecuzione interna della regola sapi_interface. Il generatore esegue la scansione di questi file alla ricerca di dichiarazioni sulle funzioni della libreria C/C++. Questo non è necessario perché le intestazioni esportate della libreria C/C++ sono sempre scansionate.
spazio dei nomi	Stringa; facoltativa; il valore predefinito è sapigen Un identificatore dello spazio dei nomi C++ in cui posizionare l'oggetto SAPI definito da lib_name. Lo spazio dei nomi predefinito è sapigen.
intestazione	Stringa; facoltativa Il nome del file di intestazione da utilizzare al posto del file di intestazione generato. Se vuoi generare automaticamente il codice, non utilizzare questo attributo
add_default_deps	Booleano; facoltativo; il valore predefinito è True OBSOLETO
profondità_di_scansione_limite	Booleano; facoltativo; il valore predefinito è False Per le librerie complesse, è possibile raggiungere il numero di file di Bazel e il processo di compilazione non riuscirà. Questo attributo è un'alternativa per queste situazioni complesse. Non utilizzare a meno che non sia necessario.
tag	Consulta la documentazione Bazel per i tag.
visibilità	Consulta la documentazione di Bazel per la visibilità

Esempio di utilizzo

L'esempio zlib è un buon progetto di riferimento che mostra come viene utilizzata la regola di compilazione 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",
)