Leitfaden für Build-Regeln

Einführung

Die Sandboxed API (SAPI) kann mit dem Bazel von Google oder dem beliebten Meta-Build-System CMake verwendet werden. Auf dieser Seite liegt der Schwerpunkt auf Bazel. Dieselben Funktionen sind jedoch auch für CMake verfügbar. Bazel ist das empfohlene Build-System und das am einfachsten zu integrierende.

Die Datei build.bazel enthält eine Build-Regel zum Erstellen des Hostcodes. Damit der Hostcode die Sandbox-Version einer Bibliothek verwenden kann, müssen Sie ein Build-Ziel vorbereiten, das Ihr Hostcode nutzen 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

Die Build-Regel sapi_library() generiert die folgenden Ziele:

• name-sapi: In einer Sandbox ausgeführte Bibliothek; ersetzt die normale cc_library als Hostcodeziel. Besteht aus zlib_sapi.bin- und Sandbox-Abhängigkeiten.
• name.interface: Schnittstelle der generierten Bibliothek.
• name.embed: cc_embed_data()-Ziel, das zum Einbetten des Sandboxee in der Binärdatei verwendet wird. Siehe bazel/embed_data.bzl.
• name.bin: Sandboxee-Binärprogramm, besteht aus einem kleinen Kommunikations-Stub und der Bibliothek, die in der Sandbox ausgeführt wird.

Argumente

Attribute
name	Name; erforderlich Ein eindeutiger Name für dieses Ziel. Dadurch wird die in der Sandbox ausgeführte C/C++-Bibliothek identifiziert, siehe das Ausgabeziel „name-sapi“.
Abfahrten	Liste der Labels (optional) Eine Liste anderer Bibliotheken, die mit der in einer Sandbox ausgeführten C/C++-Bibliothek verknüpft werden sollen.
Quellen	Liste der Labels (optional) Eine Liste von C- und C++-Dateien, die verarbeitet werden, um die in einer Sandbox ausgeführte C/C++-Bibliothek zu erstellen. 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 in der Erläuterung der Attribut „srcs“.
HDRs	Liste der Labels (optional) Eine Liste der Headerdateien, die verarbeitet werden, um die in einer Sandbox ausgeführte C/C++-Bibliothek zu erstellen. Hier sollte die Sandbox-Definition (sandbox.h) eingefügt werden. Lasse das Feld leer, wenn die eingebettete SAPI-Bibliothek verwendet wird und die Standard-Sandbox-Richtlinie ausreicht.
Einbetten	Boolesch; optional; Standardwert ist „True“ Wenn „True“, sollte die in der Sandbox ausgeführte 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 von Funktionen aus der C/C++-Bibliothek, für die eine Sandbox-Version generiert wird und die dann im Hostcode verwendet werden können. 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 in der Sandbox ausgeführte Bibliothek sein soll. Es wird davon ausgegangen, dass Sie eine Build-Regel „cc_library“ für die C/C++-Bibliothek im Projekt haben.
lib_name	String; erforderlich Der Name des SAPI-Objekts, das als Proxy für die Bibliotheksfunktionen aus dem Funktionsattribut verwendet wird. Jeder Aufruf der Funktion in der in der Sandbox ausgeführten Bibliothek erfolgt über das SAPI-Objekt.
input_files	Liste der Labels (optional) Eine Liste der C- und C++-Dateien, die während der internen Ausführung der Regel "sapi_interface" verarbeitet werden. Der Generator scannt diese Dateien nach den Funktionsdeklarationen der C/C++-Bibliothek. Dies ist meist nicht erforderlich, da die exportierten Header der C/C++-Bibliothek immer gescannt werden.
Namespace	String; optional; Standardwert ist „sapigen“ Eine C++-Namespace-ID, in der das durch lib_name definierte SAPI-Objekt platziert 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 möchten, verwenden Sie dieses Attribut nicht.
add_default_deps	Boolesch; optional; Standardwert ist „True“ EINGESTELLT
limit_scan_depth	Boolesch; optional; Standardwert ist „Falsch“ Bei komplexen Bibliotheken ist die Anzahl der Dateien für Bazel möglicherweise erreicht und der Build-Prozess wird nicht erfolgreich sein. Dieses Attribut ist eine Notlösung für diese komplexen Situationen. Nur verwenden, wenn dies unbedingt erforderlich ist.
Tags	Weitere Informationen zu Tags finden Sie in der Balken-Dokumentation.
Sichtbarkeit	Informationen zur Sichtbarkeit finden Sie in der Bazel-Dokumentation.

Anwendungsbeispiel

Das zlib-Beispiel ist ein gutes Referenzprojekt, das zeigt, wie die Build-Regel sapi_library 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",
)