Leitfaden für Build-Regeln

Einführung

Die Sandboxed API (SAPI) kann mit dem Bazel Buildsystem von Google oder mit dem beliebten CMake Meta-Buildsystem 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 Buildsystem und lässt sich am einfachsten integrieren.

In Ihrer BUILD.bazel-Datei befindet sich eine Build-Regel zum Erstellen Ihres Host-Codes. Damit der Host-Code die Sandbox-Version einer Bibliothek verwenden kann, müssen Sie ein Build-Ziel vorbereiten, das von Ihrem Host-Code 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

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

• name-sapi: Sandbox-Bibliothek, ersetzt die normale cc_library als das Host-Code-Ziel. Besteht aus zlib_sapi.bin und Sandbox-Abhängigkeiten.
• name.interface: Generierte Bibliotheksschnittstelle.
• name.embed: cc_embed_data()-Ziel, das verwendet wird, um den Sandboxee in die Binärdatei einzubetten. Siehe bazel/embed_data.bzl.
  • name.bin: Sandboxee-Binärdatei, 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 Sandbox-C/C++ Bibliothek identifiziert. Weitere Informationen finden Sie unter dem Ausgabeziel name-sapi.
deps	Liste der Labels; optional Eine Liste anderer Bibliotheken, die in die Sandbox-C/C++ Bibliothek verknüpft werden sollen.
srcs	Liste der Labels; optional Eine Liste von C- und C++-Dateien, die verarbeitet werden, um die Sandbox- C/C++-Bibliothek zu erstellen. Dabei handelt es sich um C/C++-Quell- und Headerdateien, entweder nicht generiert (normaler Quellcode) oder generiert. Weitere Informationen finden Sie in der Erläuterung des Attributs „srcs“ in der cc_library-Dokumentation.
hdrs	Liste der Labels; optional Eine Liste von Headerdateien, die verarbeitet werden, um die Sandbox- C/C++-Bibliothek zu erstellen. Hier sollte die Sandbox-Definition (sandbox.h) stehen. Lassen Sie das Feld leer, wenn die eingebettete SAPI-Bibliothek verwendet wird und die Standard-Sandbox-Konfiguration (DefaultConfig, die DefaultPolicyBuilder, DefaultFlags, DefaultEnvironmentVariables, und DefaultLimits) ausreichend ist.
embed	Boolesch; optional; Standardwert ist „True“ Wenn „True“, sollte die Sandbox-Bibliothek in den Host Code eingebettet werden. So kann die SAPI-Sandbox mit dem ::sapi::Sandbox::Sandbox(FileToc*) Konstruktor initialisiert werden.
functions	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 Host-Code 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 soll. 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 verwendet wird, um die Bibliotheks funktionen aus dem Attribut „functions“ zu proxen. Alle Aufrufe der Funktion in der Sandbox-Bibliothek erfolgen über das SAPI-Objekt.
input_files	Liste der Labels; optional Eine Liste von C- und C++-Dateien, die während der internen Ausführung der sapi_interface-Regel verarbeitet werden. Der Generator durchsucht diese Dateien nach den Funktionsdeklarationen der C/C++-Bibliothek. Das ist meist nicht erforderlich, da die exportierten Header der C/C++-Bibliothek immer gescannt werden.
namespace	String; optional; Standardwert ist „sapigen“ Eine C++-Namespace-Kennung, in die das durch 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 Header Datei verwendet werden soll. Wenn Sie den Code automatisch generieren möchten, verwenden Sie dieses Attribut nicht
add_default_deps	Boolesch; optional; Standardwert ist „True“ VERWORFEN
limit_scan_depth	Boolesch; optional; Standardwert ist „False“ Bei komplexen Bibliotheken kann die Dateianzahl für Bazel erreicht werden und der Buildprozess schlägt fehl. Dieses Attribut ist eine Notlösung für diese komplexen Situationen. Verwenden Sie es nur, wenn es unbedingt erforderlich ist.
tags	Informationen zu Tags finden Sie in der Bazel-Dokumentation.
visibility	Informationen zur Sichtbarkeit finden Sie in der Bazel-Dokumentation.

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