Guia de regras de criação

Introdução

A API em sandbox (SAPI) pode ser usada com o sistema de build Bazel do Google ou com o popular sistema de build meta 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)

Metas 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: cc_embed_data() destino 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 essa segmentação. 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 na documentação cc_library.
hdrs	Lista de rótulos; opcional Uma lista de arquivos de cabeçalho processados para criar a biblioteca C/C++ em sandbox. É aqui que a definição do sandbox (sandbox.h) deve ser inserida. 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 é "True". Se for verdadeiro, a biblioteca isolada será incorporada ao código do host. Isso permite que o Sandbox da SAPI seja inicializado com o construtor ::sapi::Sandbox::Sandbox(FileToc*).
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 pressupõe 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 fazer proxy das funções da biblioteca do atributo "functions". Qualquer chamada para a função na biblioteca em sandbox vai acontecer pelo 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++. Isso geralmente não é necessário, já que 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 de cabeçalho a ser usado em vez do arquivo de cabeçalho gerado. Se você quiser gerar o código automaticamente, não use esse atributo.
add_default_deps	Booleano; opcional; o padrão é "True". DESCONTINUADO
limit_scan_depth	Booleano; opcional; o padrão é "False" Para bibliotecas complexas, a contagem de arquivos do Bazel pode ser atingida e o processo de build não será concluído. 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 sobre visibilidade

Exemplo de uso

O exemplo do 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 policy is sufficient.
    embed = True,  # This is the default
    functions = [
        "deflateInit_",
        "deflate",
        "deflateEnd",
    ],
    lib = "@zlib//:zlibonly",
    lib_name = "Zlib",
    namespace = "sapi::zlib",
)