Guida alle regole di build

Introduzione

L'API in sandbox (SAPI) può essere utilizzata con il sistema di compilazione Bazel di Google o con il popolare sistema di compilazione meta CMake. Questa pagina si concentra su Bazel, ma le stesse funzionalità sono disponibili per CMake. Bazel è il sistema di compilazione consigliato e il più semplice da integrare.

Nel file BUILD.bazel avrai una regola di compilazione per compilare il codice host. Affinché il codice host utilizzi la versione in sandbox di una libreria, devi preparare una destinazione di compilazione che il codice host utilizzerà.

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

Destinazioni di output

La regola di compilazione sapi_library() genera le seguenti destinazioni:

• name-sapi: libreria in sandbox, sostituisce la normale cc_library come destinazione del codice host. È costituita da zlib_sapi.bin e dalle dipendenze della sandbox.
• name.interface: interfaccia della libreria generata.
• name.embed: destinazione cc_embed_data() utilizzata per incorporare Sandboxee nel file binario. Consulta bazel/embed_data.bzl.
  • name.bin: file binario Sandboxee, costituito da un piccolo stub di comunicazione e dalla libreria in sandbox.

Argomenti

Attributi
nome	Nome; obbligatorio Un nome univoco per questa destinazione. Identificherà la libreria C/C++ in sandbox, vedi la destinazione di output name-sapi.
dipendenze	Elenco di etichette; facoltativo Un elenco di altre librerie da collegare alla libreria C/C++ in sandbox.
srcs	Elenco di etichette; facoltativo Un elenco di file C e C++ elaborati per creare la libreria C/C++ in sandbox. Si tratta di file di origine e di intestazione C/C++, non generati (codice sorgente normale) o generati. Per ulteriori informazioni, consulta la spiegazione dell'attributo srcs in the cc_library documentation.
intestazioni	Elenco di etichette; facoltativo Un elenco di file di intestazione elaborati per creare la libreria C/C++ in sandbox. È qui che deve essere inserita la definizione della sandbox (sandbox.h); lascia vuoto se viene utilizzata la libreria SAPI incorporata e la configurazione della sandbox predefinita (DefaultConfig, che utilizza DefaultPolicyBuilder, DefaultFlags, DefaultEnvironmentVariables, e DefaultLimits) è sufficiente.
embed	Valore booleano; facoltativo; il valore predefinito è True Se è True, la libreria in sandbox deve essere incorporata nel codice host code. In questo modo, la sandbox SAPI può essere inizializzata con il ::sapi::Sandbox::Sandbox(FileToc*) costruttore.
funzioni	Elenco di nomi di funzioni; facoltativo Un elenco di funzioni della libreria C/C++ per le quali viene generata una versione in sandbox che può essere utilizzata nel codice host. Un elenco vuoto tenterà di esportare e eseguire il wrapping di tutte le funzioni trovate nella libreria.
lib	Stringa; obbligatorio Il nome della destinazione della libreria C/C++ che diventerà la libreria in sandbox. È previsto che tu abbia una regola di compilazione cc_library per la libreria C/C++ nel progetto.
lib_name	Stringa; obbligatorio Il nome dell'oggetto SAPI utilizzato per eseguire il proxy delle funzioni della libreria dall'attributo functions. Qualsiasi chiamata alla funzione in la libreria in sandbox avverrà 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 esegue la scansione di questi file per le dichiarazioni di funzioni della libreria C/C++. In genere non è necessario, poiché le intestazioni esportate della libreria C/C++ vengono sempre sottoposte a scansione.
spazio dei nomi	Stringa; facoltativo; il valore predefinito è sapigen Un identificatore dello spazio dei nomi C++ in cui inserire l'oggetto SAPI definito da lib_name into. Lo spazio dei nomi predefinito è sapigen.
intestazione	Stringa; facoltativo Il nome del file di intestazione da utilizzare al posto del file di intestazione generato file. Se vuoi generare automaticamente il codice, non utilizzare questo attributo.
add_default_deps	Valore booleano; facoltativo; il valore predefinito è True DEPRECATO
limit_scan_depth	Valore booleano; facoltativo; il valore predefinito è False Per le librerie complesse, il conteggio dei file per Bazel potrebbe essere raggiunto e il processo di compilazione non andrà a buon fine. Questo attributo è una soluzione di emergenza per queste situazioni complesse. Non utilizzare se non necessario.
tag	Consulta la documentazione di Bazel per tag.
visibilità	Consulta la documentazione di Bazel per visibility

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 configuration (DefaultConfig) is sufficient.
    embed = True,  # This is the default
    functions = [
        "deflateInit_",
        "deflate",
        "deflateEnd",
    ],
    lib = "@zlib//:zlibonly",
    lib_name = "Zlib",
    namespace = "sapi::zlib",
)