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 Bazel do Google ou com o conhecido sistema de metabuild CMake. O foco desta página é o 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 compilação para criar o código de host. Para que o código de host use a versão em sandbox de uma biblioteca, você precisa preparar um destino de compilação que será usado pelo código de host.

Regras de criação do 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 criação sapi_library() gera os seguintes destinos:

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

Argumentos

Atributos
name	Name (obrigatório): obrigatório Um nome exclusivo para o destino. Isso identificará a biblioteca C/C++ no sandbox. Consulte o destino de saída name-sapi.
deps	Lista de rótulos (opcional) Uma lista de outras bibliotecas que serão vinculadas à biblioteca C/C++ no sandbox.
srcs	Lista de rótulos (opcional) Uma lista de arquivos C e C++ processados para criar a biblioteca C/C++ no modo 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 sobre os atributos "src" na documentação do cc_library.
HDR	Lista de rótulos (opcional) Uma lista de arquivos principais processados para criar a biblioteca C/C++ no sandbox. A definição do sandbox (sandbox.h) precisa ficar aqui. Deixe em branco se a biblioteca SAPI incorporada for usada e a política de sandbox padrão for suficiente.
incorporar	Booleano; opcional; o padrão é Verdadeiro Se for "True", a biblioteca no sandbox precisa ser incorporada ao código do host. Isso permite que o sandbox SAPI seja inicializado com o construtor ::sapi::Sandbox::Sandbox(FileToc*).
functions	Lista de nomes de funções (opcional) Uma lista de funções da biblioteca C/C++ para a qual uma versão em sandbox é gerada e que pode ser usada no código de host. Uma lista vazia vai tentar exportar e unir todas as funções encontradas na biblioteca.
lib	String; obrigatório O nome do destino da biblioteca C/C++ que será a biblioteca no modo sandbox. Isso espera que você tenha uma regra de criação 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 no atributo functions. Qualquer chamada para a função na biblioteca em sandbox acontecerá por meio do objeto SAPI.
input_files	Lista de rótulos (opcional) Uma lista de arquivos C e C++ processados durante a execução interna da regra sapi_interface. O gerador verifica esses arquivos em busca das declarações de função da biblioteca C/C++. Na maioria das vezes, isso não é necessário 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. 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 é False Para bibliotecas complexas, a contagem de arquivos do Bazel pode ser alcançada e o processo de compilação não será bem-sucedido. Esse atributo é uma saída 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 de zlib é um bom projeto de referência que demonstra como a regra de compilação 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 policy is sufficient.
    embed = True,  # This is the default
    functions = [
        "deflateInit_",
        "deflate",
        "deflateEnd",
    ],
    lib = "@zlib//:zlibonly",
    lib_name = "Zlib",
    namespace = "sapi::zlib",
)