Guía de reglas de compilación

Introducción

La API de Sandboxed (SAPI) se puede usar con el sistema de compilación Bazel de Google o con el popular sistema de metacomilación CMake. Esta página se centra 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 en espacio aislado de una biblioteca, debes preparar un destino de compilación que usará el 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: Biblioteca en espacio aislado, sustituye a la cc_library normal como destino del código de host. Consta de zlib_sapi.bin y dependencias de espacio aislado.
• name.interface: Interfaz de biblioteca generada.
• name.embed: Destino cc_embed_data() que se usa para incorporar el Sandboxee en el objeto binario. Consulta bazel/embed_data.bzl.
  • name.bin: Objeto binario de Sandboxee, consta de un pequeño stub de comunicación y la biblioteca que se encuentra en espacio aislado.

Argumentos

Atributos
nombre	Nombre; obligatorio Un nombre único para este destino. Esto identificará la biblioteca C/C++ en espacio aislado. 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++ en espacio aislado.
srcs	Lista de etiquetas; opcional Una lista de archivos C y C++ que se procesan para crear la biblioteca C/C++ en espacio aislado. Estos son archivos fuente y de encabezado de 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.
hdrs	Lista de etiquetas; opcional Una lista de archivos de encabezado que se procesan para crear la biblioteca C/C++ en espacio aislado. Aquí es donde debe ir la definición del espacio aislado (sandbox.h); déjalo vacío si se usa la biblioteca SAPI incorporada y la configuración predeterminada del espacio aislado (DefaultConfig, que usa DefaultPolicyBuilder, DefaultFlags, DefaultEnvironmentVariables, y DefaultLimits) es suficiente.
embed	Booleano; opcional; el valor predeterminado es True Si es verdadero, la biblioteca en espacio aislado debe incorporarse dentro del código de host. Esto permite que el espacio aislado de SAPI se inicialice con el ::sapi::Sandbox::Sandbox(FileToc*) constructor.
sin servidores	Lista de nombres de funciones; opcional Una lista de funciones de la biblioteca C/C++ para las que se genera una versión en espacio aislado y que luego se puede usar en el código de host. Una lista vacía intentará exportar y ajustar todas las funciones que se encuentran en la biblioteca.
lib	Cadena; obligatorio El nombre del destino de la biblioteca C/C++ que será la biblioteca en espacio aislado. Esto espera que tengas una regla de compilación cc_library para la biblioteca C/C++ en el proyecto.
lib_name	Cadena; obligatorio El nombre del objeto SAPI que se usa para proxy las funciones de la biblioteca del atributo functions. Cualquier llamada a la función en la biblioteca en espacio aislado se realizará a través del objeto SAPI.
input_files	Lista de etiquetas; opcional Una 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 funciones de la biblioteca C/C++. Por lo general, no es necesario, ya que siempre se analizan los encabezados exportados de la biblioteca C/C++.
espacio de nombres	Cadena; opcional; el valor predeterminado es sapigen Un identificador de espacio de nombres de C++ para colocar el objeto SAPI definido por lib_name. El espacio de nombres predeterminado es sapigen.
header	Cadena; opcional El nombre del archivo de encabezado que se usará en lugar del archivo de encabezado generado. Si deseas generar el código automáticamente, no uses este atributo
add_default_deps	Booleano; opcional; el valor predeterminado es True COMUNICACIONES OBSOLETAS
limit_scan_depth	Booleano; opcional; el valor predeterminado es False En el caso de bibliotecas complejas, se puede alcanzar el recuento de archivos para Bazel y el proceso de compilación no se realizará correctamente. Este atributo es una salida de escape 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 muestra 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 configuration (DefaultConfig) is sufficient.
    embed = True,  # This is the default
    functions = [
        "deflateInit_",
        "deflate",
        "deflateEnd",
    ],
    lib = "@zlib//:zlibonly",
    lib_name = "Zlib",
    namespace = "sapi::zlib",
)