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 compilación meta 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 del host use la versión en zona de pruebas de una biblioteca, debes preparar un destino de compilación que usará el código del host.

Reglas de compilación de la 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 zona de pruebas que sustituye a la cc_library normal como destino del código host. Consta de zlib_sapi.bin y dependencias de zona de pruebas.
• name.interface: Es la interfaz de la biblioteca generada.
• name.embed: Es el destino cc_embed_data() que se usa para incorporar el Sandboxee en el binario. Consulta bazel/embed_data.bzl.
  • name.bin: Es el binario de Sandboxee, que consta de un pequeño stub de comunicación y la biblioteca que se aísla en la zona de pruebas.

Argumentos

Atributos
nombre	Nombre: Obligatorio Es un nombre único para este destino. Esto identificará la biblioteca de C/C++ en zona de pruebas. Consulta el objetivo de salida name-sapi.
dependencias	Lista de etiquetas; opcional Es una lista de otras bibliotecas que se vincularán a la biblioteca de C/C++ en zona de pruebas.
srcs	Lista de etiquetas; opcional Es una lista de archivos C y C++ que se procesan para crear la biblioteca C/C++ en zona de pruebas. 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 Es una lista de archivos de encabezado que se procesan para crear la biblioteca de C/C++ en zona de pruebas. Aquí es donde debe ir la definición de zona de pruebas (sandbox.h); déjalo vacío si se usa la biblioteca de SAPI integrada y la política de zona de pruebas predeterminada es suficiente.
insertar	Booleano; opcional; el valor predeterminado es True Si es verdadero, la biblioteca en zona de pruebas debe incorporarse dentro del código del host. Esto permite que el entorno de pruebas de la SAPI se inicialice con el constructor ::sapi::Sandbox::Sandbox(FileToc*).
sin servidores	Lista de nombres de funciones (opcional) Una lista de funciones de la biblioteca de C/C++ para las que se genera una versión en zona de pruebas y que luego se puede usar en el código del host. Una lista vacía intentará exportar y unir todas las funciones que se encuentren en la biblioteca.
lib	Cadena; obligatorio Es el nombre del destino de la biblioteca de C/C++ que será la biblioteca en zona de pruebas. Esto supone que tienes una regla de compilación cc_library para la biblioteca de C/C++ en el proyecto.
lib_name	Cadena; obligatorio Nombre del objeto de la SAPI que se usa para proxy de 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 de la SAPI.
input_files	Lista de etiquetas; opcional Es 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 de C/C++. Esto no es necesario en la mayoría de los casos, ya que siempre se analizan los encabezados exportados de la biblioteca de C/C++.
espacio de nombres	Cadena; opcional; el valor predeterminado es sapigen Es un identificador de espacio de nombres de C++ para colocar el objeto de la SAPI definido por lib_name. El espacio de nombres predeterminado es sapigen.
encabezado	Cadena; opcional 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 OBSOLETO
limit_scan_depth	Booleano; opcional; el valor predeterminado es falso En el caso de las bibliotecas complejas, es posible que se alcance el recuento de archivos para Bazel y que el proceso de compilación no se complete correctamente. Este atributo es una salida de emergencia para estas situaciones complejas. No lo uses, a menos que sea necesario.
tags	Consulta la documentación de Bazel sobre las etiquetas.
visibilidad	Consulta la documentación de Bazel sobre la 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",
)