Guia de regras de criação

Introdução

A API em sandbox (SAPI, na sigla em inglês) pode ser usada com o sistema de build do Bazel do Google ou com o popular sistema de meta build do CMake. Esta página se concentra no Bazel, mas os mesmos recursos estão disponíveis para o CMake. O Bazel é o sistema de build recomendado e o mais fácil de integrar.

No arquivo BUILD.bazel, você terá uma regra de build para criar o código do host. Para que o código do host use a versão em sandbox de uma biblioteca, é necessário preparar um destino de build que o código do host vai usar.

Regras de build da 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)

Destinos de saída

A regra de build sapi_library() gera os seguintes destinos:

• name-sapi: biblioteca em sandbox, substitui a cc_library normal como o destino do código do host. Consiste em zlib_sapi.bin e dependências de sandbox.
• name.interface: interface de biblioteca gerada.
• name.embed: destino cc_embed_data() usado para incorporar o Sandboxee no binário. Consulte bazel/embed_data.bzl.
  • name.bin: binário do Sandboxee, consiste em um pequeno stub de comunicação e a biblioteca que está sendo colocada em sandbox.

Argumentos

Atributos
nome	Nome; obrigatório Um nome exclusivo para esse destino. Isso vai identificar a biblioteca C/C++ em sandbox. Consulte o destino de saída name-sapi.
deps	Lista de rótulos; opcional Uma lista de outras bibliotecas a serem vinculadas à biblioteca C/C++ em sandbox.
srcs	Lista de rótulos; opcional Uma lista de arquivos C e C++ que são processados para criar a biblioteca C/C++ em sandbox. São arquivos de origem e de cabeçalho C/C++, não gerados (código-fonte normal) ou gerados. Para mais informações, consulte a explicação do atributo srcs em a documentação da cc_library.
hdrs	Lista de rótulos; opcional Uma lista de arquivos principais que são processados para criar a biblioteca C/C++ em sandbox. É aqui que a definição de sandbox (sandbox.h) precisa estar. Deixe em branco se a biblioteca SAPI incorporada for usada e a configuração de sandbox padrão (DefaultConfig, que usa DefaultPolicyBuilder, DefaultFlags, DefaultEnvironmentVariables, e DefaultLimits) for suficiente.
vídeo	Booleano; opcional; o padrão é verdadeiro Se for verdadeiro, a biblioteca em sandbox será incorporada ao código do host. Isso permite que o sandbox da SAPI seja inicializado com o ::sapi::Sandbox::Sandbox(FileToc*) construtor.
funções	Lista de nomes de funções; opcional Uma lista de funções da biblioteca C/C++ para as quais uma versão em sandbox é gerada e que pode ser usada no código do host. Uma lista vazia vai tentar exportar e encapsular todas as funções encontradas na biblioteca.
lib	String; obrigatório O nome do destino da biblioteca C/C++ que será a biblioteca em sandbox. Isso espera que você tenha uma regra de build cc_library para a biblioteca C/C++ no projeto.
lib_name	String; obrigatório O nome do objeto SAPI usado para representar as funções da biblioteca do atributo functions. Qualquer chamada para a função em a biblioteca em sandbox vai acontecer pelo objeto SAPI.
input_files	Lista de rótulos; opcional Uma lista de arquivos C e C++ que são processados durante a execução interna da regra sapi_interface. O gerador verifica esses arquivos para as declarações de função da biblioteca C/C++. Isso não é necessário na maioria das vezes, porque os cabeçalhos exportados da biblioteca C/C++ são sempre verificados.
namespace	String; opcional; o padrão é sapigen Um identificador de namespace C++ para colocar o objeto SAPI definido por lib_name. O namespace padrão é sapigen.
cabeçalho	String; opcional O nome do arquivo principal a ser usado em vez do arquivo principal gerado file. Se você quiser gerar o código automaticamente, não use esse atributo
add_default_deps	Booleano; opcional; o padrão é verdadeiro DESCONTINUADO
limit_scan_depth	Booleano; opcional; o padrão é falso Para bibliotecas complexas, a contagem de arquivos do Bazel pode ser atingida e o processo de build não será bem-sucedido. Esse atributo é uma saída de emergência para essas situações complexas. Não use a menos que seja necessário.
tags	Consulte a documentação do Bazel para tags.
visibilidade	Consulte a documentação do Bazel para visibilidade

Exemplo de uso

O exemplo zlib é um bom projeto de referência que demonstra como a regra de build sapi_library é usada:

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",
)