Leitfaden für Build-Regeln

Einführung

Die Sandboxed API (SAPI) kann mit dem Bazel-Build-System von Google oder mit dem beliebten CMake-Meta-Build-System verwendet werden. Auf dieser Seite geht es hauptsächlich um Bazel, aber dieselben Funktionen sind auch für CMake verfügbar. Bazel ist das empfohlene Build-System und lässt sich am einfachsten einbinden.

In Ihrer BUILD.bazel-Datei haben Sie eine Build-Regel zum Erstellen Ihres Host-Codes. Damit der Hostcode die Sandbox-Version einer Bibliothek verwendet, müssen Sie ein Build-Ziel vorbereiten, das vom Hostcode verwendet wird.

SAPI-Build-Regeln

• 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)

Ausgabeziele

Durch die sapi_library()-Build-Regel werden die folgenden Ziele generiert:

• name-sapi: Sandboxed-Bibliothek, die die normale cc_library als Ziel für den Hostcode ersetzt. Besteht aus zlib_sapi.bin und Sandbox-Abhängigkeiten.
• name.interface: Generierte Bibliotheksschnittstelle.
• name.embed: cc_embed_data()-Ziel, das zum Einbetten des Sandboxee in die Binärdatei verwendet wird. Siehe bazel/embed_data.bzl.
  • name.bin: Sandboxee-Binärdatei, die aus einem kleinen Kommunikations-Stub und der Bibliothek besteht, die in der Sandbox ausgeführt wird.

Argumente

Attribute
name	Name: erforderlich Ein eindeutiger Name für dieses Ziel. Dadurch wird die Sandbox-C/C++-Bibliothek identifiziert. Sehen Sie sich das Ausgabeziel „name-sapi“ an.
deps	Liste mit Labels; optional Eine Liste anderer Bibliotheken, die in die C/C++-Bibliothek in der Sandbox eingebunden werden sollen.
srcs	Liste mit Labels; optional Eine Liste der C- und C++-Dateien, die zum Erstellen der Sandbox-C/C++-Bibliothek verarbeitet werden. Dies sind C/C++-Quell- und Headerdateien, die entweder nicht generiert (normaler Quellcode) oder generiert sind. Weitere Informationen finden Sie in der Dokumentation zu cc_library.
hdrs	Liste mit Labels; optional Eine Liste der Headerdateien, die zum Erstellen der Sandbox-C/C++-Bibliothek verarbeitet werden. Hier sollte die Sandbox-Definition (sandbox.h) eingefügt werden. Lassen Sie das Feld leer, wenn die eingebettete SAPI-Bibliothek verwendet wird und die Standardsandbox-Richtlinie ausreicht.
Einbetten	Boolescher Wert; optional; Standardwert ist „True“ Wenn „True“, sollte die Sandbox-Bibliothek in den Hostcode eingebettet werden. Dadurch kann die SAPI-Sandbox mit dem Konstruktor ::sapi::Sandbox::Sandbox(FileToc*) initialisiert werden.
Funktionen	Liste der Funktionsnamen (optional) Eine Liste der Funktionen aus der C/C++-Bibliothek, für die eine Sandbox-Version generiert wird und die dann im Hostcode verwendet werden kann. Bei einer leeren Liste wird versucht, alle in der Bibliothek gefundenen Funktionen zu exportieren und zu umschließen.
lib	String; erforderlich Der Name des C/C++-Bibliotheksziels, das die Sandbox-Bibliothek sein wird. Dazu ist eine cc_library-Build-Regel für die C/C++-Bibliothek im Projekt erforderlich.
lib_name	String; erforderlich Der Name des SAPI-Objekts, das zum Proxying der Bibliotheksfunktionen aus dem Attribut „functions“ verwendet wird. Jeder Aufruf der Funktion in der Sandbox-Bibliothek erfolgt über das SAPI-Objekt.
input_files	Liste mit Labels; optional Eine Liste der C- und C++-Dateien, die während des internen Laufs der sapi_interface-Regel verarbeitet werden. Der Generator durchsucht diese Dateien nach Funktionsdeklarationen der C/C++-Bibliothek. Das ist meistens nicht erforderlich, da die exportierten Header der C/C++-Bibliothek immer gescannt werden.
Namespace	String; optional; Standardwert ist sapigen Eine C++-Namespace-Kennzeichnung, in die das von lib_name definierte SAPI-Objekt eingefügt werden soll. Der Standard-Namespace ist sapigen.
Header	String; optional Der Name der Headerdatei, die anstelle der generierten Headerdatei verwendet werden soll. Wenn Sie den Code automatisch generieren lassen möchten, verwenden Sie dieses Attribut nicht.
add_default_deps	Boolescher Wert; optional; Standardwert ist „True“ EINGESTELLT
limit_scan_depth	Boolescher Wert; optional; Standardwert ist „False“ Bei komplexen Bibliotheken kann die Dateianzahl für Bazel erreicht werden und der Build-Prozess schlägt fehl. Dieses Attribut ist ein Ausweg für diese komplexen Situationen. Nicht verwenden, es sei denn, es ist unbedingt erforderlich.
Tags	Weitere Informationen finden Sie in der Bazel-Dokumentation unter Tags.
Sichtbarkeit	Weitere Informationen finden Sie in der Bazel-Dokumentation unter Sichtbarkeit.

Beispiel für die Verwendung

Das zlib-Beispiel ist ein gutes Referenzprojekt, das zeigt, wie die sapi_library-Build-Regel verwendet wird:

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