Guía de reglas de compilación

Introducción

La API de Sandboxed (SAPI) se puede usar con el sistema de compilación de Bazel de Google o con el popular sistema de metacompilación CMake. Esta página se enfoca en Bazel, pero las mismas funciones están disponibles para CMake. Bazel es el sistema de compilación recomendado y el más fácil de integrar.

En tu archivo BUILD.bazel, tendrás una regla de compilación para compilar tu código de host. Para que el código de host use la versión de zona de pruebas de una biblioteca, debes preparar un destino de compilación que usará tu código de host.

Reglas de compilación de 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)

Objetivos de salida

La regla de compilación sapi_library() genera los siguientes destinos:

• name-sapi: La biblioteca con zona de pruebas reemplaza la cc_library normal como el destino del código de host. Consiste en dependencias de zlib_sapi.bin y de la zona de pruebas.
• name.interface: Se generó la interfaz de la biblioteca.
• name.embed: destino cc_embed_data() que se usa para incorporar el objeto Sandboxee en el objeto binario Consulta bazel/embed_data.bzl.
• name.bin: El objeto binario de Sandboxee consta de un pequeño stub de comunicación y la biblioteca que se somete a una zona de pruebas.

Argumentos

Atributos
name	Name (obligatorio). Un nombre único para este destino. Esto identificará la biblioteca de C/C++ de zona de pruebas. Consulta el destino de salida name-sapi.
dependencias	Lista de etiquetas (opcional) Una lista de otras bibliotecas que se vincularán a la biblioteca C/C++ de la zona de pruebas.
srcs	Lista de etiquetas (opcional) Una lista de archivos C y C++ que se procesan para crear la biblioteca C/C++ de la zona de pruebas. Estos son archivos fuente y de encabezado C/C++, ya sean no generados (código fuente normal) o generados. Para obtener más información, consulta la explicación del atributo srcs en la documentación de cc_library.
en HD	Lista de etiquetas (opcional) Una lista de archivos de encabezado que se procesan para crear la biblioteca C/C++ de la zona de pruebas. Aquí es donde debe ir la definición de la zona de pruebas (sandbox.h). Deja el campo vacío si se usa la biblioteca SAPI incorporada y si la política de zona de pruebas predeterminada es suficiente.
insertar	Booleano; opcional; el valor predeterminado es True Si es verdadero, la biblioteca de la zona de pruebas debe estar incorporada dentro del código de host. Esto permite que la zona de pruebas de SAPI se inicialice con el constructor ::sapi::Sandbox::Sandbox(FileToc*).
functions	Lista de nombres de funciones (opcional) Una lista de funciones de la biblioteca C/C++ para las que se genera una versión de zona de pruebas y que luego se puede usar en el código de host. Una lista vacía intentará exportar y unir todas las funciones encontradas en la biblioteca.
lib	String; obligatoria El nombre de destino de la biblioteca C/C++ que será la biblioteca de la zona de pruebas. De esta manera, se espera que tengas una regla de compilación cc_library para la biblioteca C/C++ en el proyecto.
lib_name	String; obligatoria El nombre del objeto SAPI que se usa como proxy para las funciones de la biblioteca desde el atributo de funciones. Cualquier llamada a la función en la biblioteca de zona de pruebas se realizará a través del objeto SAPI.
input_files	Lista de etiquetas (opcional) Lista de archivos C y C++ que se procesan durante la ejecución interna de la regla sapi_interface. El generador analiza estos archivos en busca de las declaraciones de las funciones de la biblioteca C/C++. En general, esto no es necesario, ya que siempre se analizan los encabezados exportados de la biblioteca C/C++.
espacio de nombres	String; opcional; el valor predeterminado es sapigen Un identificador de espacio de nombres C++ en el que se colocará el objeto SAPI definido por lib_name. El espacio de nombres predeterminado es sapigen.
encabezado	String; opcional Es el nombre del archivo de encabezado que se usará en lugar del archivo de encabezado generado. Si quieres generar automáticamente el código, no uses este atributo
add_default_deps	Booleano; opcional; el valor predeterminado es True OBSOLETO
limit_scan_depth	Booleano; opcional; el valor predeterminado es False En el caso de las bibliotecas complejas, es posible que se alcance el recuento de archivos de Bazel y que el proceso de compilación no se realice de forma correcta. Este atributo es una solución para estas situaciones complejas. No lo uses, a menos que sea necesario.
tags	Consulta la documentación de Bazel para obtener etiquetas.
visibilidad	Consulta la documentación de Bazel para obtener visibilidad.

Ejemplo de uso

El ejemplo de zlib es un buen proyecto de referencia que demuestra cómo se usa la regla de compilación 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",
)