Guida alle regole di build

Introduzione

L'API Sandboxed (SAPI) può essere utilizzata con il sistema di build Bazel di Google o con il popolare sistema di meta 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 hai una regola di build per creare il tuo codice host. Affinché l'host Code utilizzi la versione con sandbox di una libreria, devi preparare una destinazione di build che verrà utilizzata dall'host Code.

Regole di build 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)

Target di output

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

• name-sapi: la 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: cc_embed_data() target utilizzato per incorporare Sandboxee nel programma binario. Visita bazel/embed_data.bzl.
• name.bin: il programma binario Sandboxee è costituito da un piccolo stub di comunicazione e dalla libreria in fase di sandbox.

Argomenti

Attributi
nome	Nome; obbligatorio Un nome univoco per questo target. Questa operazione identificherà la libreria C/C++ con sandbox e visualizzerà la destinazione di output name-sapi.
Deps	Elenco di etichette; facoltativo Un elenco di altre librerie da collegare alla libreria C/C++ con sandbox.
Sr	Elenco di etichette; facoltativo Un elenco di file C e C++ che vengono elaborati per creare la libreria C/C++ con sandbox. Questi sono file di origine e di intestazione C/C++, non generati (codice sorgente normale) o generati. Per ulteriori informazioni, consulta la spiegazione degli attributi src nella documentazione cc_library.
hdrs	Elenco di etichette; facoltativo Un elenco di file di intestazione che vengono elaborati per creare la libreria C/C++ con sandbox. Questa è la posizione in cui deve essere inserita la definizione sandbox (sandbox.h); lascia vuoto il campo se viene utilizzata la libreria SAPI incorporata e sarà sufficiente il criterio della sandbox predefinito.
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 di inizializzare la 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. Un elenco vuoto proverà a esportare e a eseguire il wrapping di tutte le funzioni trovate nella libreria.
lib	Stringa; obbligatoria Il nome della libreria C/C++ di destinazione che diventerà la libreria con sandbox. Questo richiede una regola di build cc_library per la libreria C/C++ nel progetto.
lib_name	Stringa; obbligatoria Il nome dell'oggetto SAPI utilizzato per eseguire il proxy delle funzioni di libreria dall'attributo Functions. Qualsiasi chiamata alla funzione nella libreria con sandbox avviene tramite l'oggetto SAPI.
input_files	Elenco di etichette; facoltativo Un elenco di file C e C++ elaborati durante l'esecuzione interna della regola sapi_interface. Il generatore analizza questi file per trovare le dichiarazioni delle funzioni della libreria C/C++. Questa operazione non è per lo più necessaria poiché le intestazioni esportate della libreria C/C++ vengono sempre analizzate.
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
limit_scan_depth	Booleano; facoltativo; il valore predefinito è False Per le librerie complesse, potrebbe essere raggiunto il numero di file per Bazel e il processo di compilazione non avrà esito positivo. Questo attributo è un'alternativa per queste situazioni complesse. Non utilizzare se non è necessario.
tag	Consulta la documentazione di Bazel per i tag.
visibilità	Consulta la documentazione di Bazel per informazioni sulla visibilità

Esempio di utilizzo

L'esempio di 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",
)