Definições comuns

Informar um problema Ver código de origem

Nesta seção, definimos vários termos e conceitos comuns a muitas funções ou regras de compilação.

Índice

Tokenização Bourne de shell

Alguns atributos de string de algumas regras são divididos em várias palavras de acordo com as regras de tokenização do shell de Bourne: espaços sem aspas delimitam palavras separadas, e aspas simples e duplas são usadas para evitar a tokenização.

Os atributos que estão sujeitos a essa tokenização são explicitamente indicados como tal nas definições neste documento.

Atributos sujeitos à expansão de variável "Make" e à tokenização de shell do Bourne normalmente são usados para transmitir opções arbitrárias a compiladores e outras ferramentas. Exemplos desses atributos são cc_library.copts e java_library.javacopts. Juntas essas substituições permitem que uma única variável de string se expanda em uma lista específica de configuração de palavras de opção.

Expansão de rótulos

Alguns atributos de strings de poucas regras estão sujeitos à expansão do rótulo: se essas strings contiverem um rótulo válido como uma substring, como //mypkg:target, e esse rótulo for um pré-requisito declarado da regra atual, ele será expandido no nome do caminho do arquivo representado pelo //mypkg:target de destino //mypkg:target.

Os atributos de exemplo incluem genrule.cmd e cc_binary.linkopts. Os detalhes podem variar significativamente em cada caso, por exemplo, se os rótulos relativos são expandidos, como os rótulos que se expandem para vários arquivos são tratados etc. Consulte a documentação de atributos de regra para detalhes.

Atributos típicos definidos pela maioria das regras de compilação

Nesta seção, descrevemos os atributos definidos por muitas regras de build, mas não todas.

Atributo Descrição
data

List of labels ; optional

Arquivos necessários para esta regra no momento da execução. Pode listar os destinos de arquivo ou de regra. Geralmente, permite qualquer destino.

As saídas padrão e os arquivos de execução dos destinos no atributo data precisam aparecer na área *.runfiles de qualquer executável que seja resultado ou tenha uma dependência de ambiente de execução nesse destino. Isso pode incluir arquivos de dados ou binários usados quando o srcs do destino é executado. Consulte a seção de dependências de dados para mais informações sobre como depender de e usar arquivos de dados.

As novas regras precisam definir um atributo data se processarem entradas que possam usar outras no momento da execução. As funções de implementação das regras também precisam preencher os arquivos de execução de destino das saídas e dos arquivos de execução de qualquer atributo data, bem como os arquivos de execução de qualquer atributo de dependência que forneça código-fonte ou dependências de ambiente de execução.

deps

List of labels ; optional

Dependências para este destino. Geralmente, lista apenas os destinos de regra. Embora algumas regras permitam que os arquivos sejam listados diretamente em deps, isso deve ser evitado sempre que possível.

As regras específicas da linguagem geralmente limitam os destinos listados aos com provedores específicos.

A semântica precisa do que significa um destino depender de outro usando deps é específica para o tipo de regra, e a documentação específica da regra entra em mais detalhes. Para regras que processam código-fonte, deps geralmente especifica dependências de código usadas pelo código em srcs.

Na maioria das vezes, uma dependência deps é usada para permitir que um módulo use símbolos definidos em outro módulo escrito na mesma linguagem de programação e compilado separadamente. Dependências de linguagem cruzada também são permitidas em muitos casos: por exemplo, um destino java_library pode depender do código C++ em um destino cc_library, listando o último no atributo deps. Consulte a definição de dependências para mais informações.

licenses

List of strings; optional; nonconfigurable

Uma lista de strings de tipo de licença a ser usada para esse destino específico. Isso faz parte de uma API de licenciamento descontinuada que o Bazel não usa mais. Não use esse recurso.

srcs

List of labels ; optional

São os arquivos processados ou incluídos por essa regra. Geralmente, lista os arquivos diretamente, mas pode listar os destinos de regras (como filegroup ou genrule) para incluir as saídas padrão.

As regras específicas da linguagem geralmente exigem que os arquivos listados tenham extensões de arquivo específicas.

Atributos comuns a todas as regras de compilação

Esta seção descreve atributos que são implicitamente adicionados a todas as regras de build.

Atributo Descrição
compatible_with

List of labels ; optional; nonconfigurable

A lista de ambientes para os quais esse destino pode ser criado, além dos ambientes com suporte padrão.

Isso faz parte do sistema de restrição do Bazel, que permite que os usuários declarem quais destinos podem ou não depender uns dos outros. Por exemplo, os binários implantáveis externamente não devem depender de bibliotecas com código da chave secreta da empresa. Consulte ConstraintSemantics para mais detalhes.

deprecation

String; optional; nonconfigurable

Uma mensagem de aviso explicativa associada ao destino. Normalmente, isso é usado para notificar os usuários de que um destino está obsoleto ou foi substituído por outra regra, é privado para um pacote ou é considerado nocivo por algum motivo. É recomendável incluir algumas referências (como uma página da Web, um número de bug ou exemplos de CLs de migração) para que seja fácil descobrir quais mudanças são necessárias para evitar a mensagem. Se houver um novo destino que possa ser usado como uma queda na substituição, convém migrar todos os usuários do destino antigo.

Esse atributo não afeta a maneira como as coisas são criadas, mas pode afetar a saída de diagnóstico de uma ferramenta de build. A ferramenta de build emite um aviso quando uma regra com um atributo deprecation é dependida por um destino em outro pacote.

As dependências dentro do pacote estão isentas desse aviso. Assim, por exemplo, criar os testes de uma regra descontinuada não vai encontrar um aviso.

Se um destino descontinuado depender de outro destino descontinuado, nenhuma mensagem de aviso vai ser emitida.

Quando as pessoas param de usá-lo, o destino pode ser removido.

distribs

List of strings; optional; nonconfigurable

Uma lista de strings de método de distribuição a ser usada para esse destino específico. Isso faz parte de uma API de licenciamento descontinuada que o Bazel não usa mais. Não use esse recurso.

exec_compatible_with

List of labels ; optional; nonconfigurable

Uma lista de constraint_values que precisa estar presente na plataforma de execução para esse destino. Isso complementa as restrições já definidas pelo tipo de regra. As restrições são usadas para restringir a lista de plataformas de execução disponíveis. Para mais detalhes, consulte a descrição da resolução do conjunto de ferramentas.

exec_properties

Dictionary of strings; optional

Um dicionário de strings que serão adicionadas ao exec_properties de uma plataforma selecionada para esse destino. Consulte exec_properties da regra platform.

Se houver uma chave nas propriedades da plataforma e no nível do destino, o valor será extraído do destino.

features

List of feature strings; optional

Um recurso é uma tag de string que pode ser ativada ou desativada em um destino. O significado de um recurso depende da própria regra.

Esse atributo features é combinado com o atributo features de nível do pacote. Por exemplo, se os recursos ["a", "b"] estiverem ativados no nível do pacote e o atributo features de um destino contiver ["-a", "c"], os recursos ativados para a regra serão "b" e "c". Veja o exemplo.

restricted_to

List of labels ; optional; nonconfigurable

A lista de ambientes para os quais esse destino pode ser criado em vez de ambientes padrão compatíveis.

Isso faz parte do sistema de restrição do Bazel. Consulte compatible_with para mais detalhes.

tags

List of strings; optional; nonconfigurable

As tags podem ser usadas em qualquer regra. Tags nas regras de teste e test_suite são úteis para categorizar os testes. Tags em destinos que não são de teste são usadas para controlar a execução no sandbox de ações genrule e Starlark e para análise por humanos e/ou ferramentas externas.

O Bazel modifica o comportamento do código de sandbox se encontrar as seguintes palavras-chave no atributo tags de qualquer teste ou destino genrule ou as chaves de execution_requirements para qualquer ação do Starlark.

  • A palavra-chave no-sandbox resulta na ação ou no teste de nunca colocar o app em sandbox. Ele ainda pode ser armazenado em cache ou executado remotamente. Para isso, use no-cache ou no-remote.
  • A palavra-chave no-cache faz com que a ação ou o teste nunca sejam armazenados em cache (remotamente ou localmente)
  • A palavra-chave no-remote-cache faz com que a ação ou o teste nunca sejam armazenados em cache remotamente (mas pode ser armazenado em cache localmente ou pode ser executado remotamente). Observação: para os fins dessa tag, o cache de disco é considerado local, enquanto os caches http e gRPC são considerados remotos. Se uma combinação de cache de disco local e cache remoto for usada (combinado), ele será tratado como um cache remoto e desativado completamente, a menos que --incompatible_remote_results_ignore_disk esteja definido. Nesse caso, os componentes locais serão usados.
  • A palavra-chave no-remote-exec faz com que a ação ou o teste nunca sejam executados remotamente (mas pode ser armazenado em cache remotamente).
  • A palavra-chave no-remote impede que a ação ou o teste seja executado remotamente ou armazenado em cache remotamente. Isso equivale a usar no-remote-cache e no-remote-exec.
  • A palavra-chave no-remote-cache-upload desativa o upload de parte do armazenamento em cache remoto de um spawn. não desativa a execução remota.
  • A palavra-chave local impede que a ação ou o teste seja armazenado em cache remotamente, executado remotamente ou executado dentro do sandbox. Para regras gerais e testes, a marcação da regra com o atributo local = True tem o mesmo efeito.
  • A palavra-chave requires-network permite acesso à rede externa de dentro do sandbox. Essa tag só tem efeito se o sandbox estiver ativado.
  • A palavra-chave block-network bloqueia o acesso à rede externa de dentro do sandbox. Nesse caso, somente a comunicação com o localhost é permitida. Essa tag só tem efeito se o sandbox estiver ativado.
  • requires-fakeroot executa o teste ou a ação como uid e gid 0 (ou seja, o usuário raiz). Isso só é compatível com o Linux. Essa tag tem prioridade sobre a opção de linha de comando --sandbox_fake_username.

Tags em testes geralmente são usadas para anotar o papel de um teste no processo de depuração e lançamento. Normalmente, as tags são mais úteis para testes em C++ e Python, que não têm recursos de anotação de ambiente de execução. O uso de tags e elementos de tamanho oferece flexibilidade na montagem de conjuntos de testes com base na política de check-in da base de código.

O Bazel modifica o comportamento de execução do teste se ele encontrar as seguintes palavras-chave no atributo tags da regra de teste:

  • exclusive forçará a execução do teste no modo "exclusivo", garantindo que nenhum outro teste seja executado ao mesmo tempo. Esses testes serão executados em série depois que toda a atividade do build e os testes não exclusivos forem concluídos. A execução remota está desativada para esses testes porque o Bazel não tem controle sobre o que está sendo executado em uma máquina remota.
  • exclusive-if-local forçará a execução do teste no modo "exclusivo" se for executado localmente, mas o executará em paralelo se for executado remotamente.
  • A palavra-chave manual excluirá o destino da expansão de caracteres curinga de padrão de destino (..., :*, :all etc.) e regras de test_suite que não listam o teste explicitamente ao calcular o conjunto de destinos de nível superior a ser criado/executado para os comandos build, test e coverage. Ela não afeta o caractere curinga de destino ou a expansão do conjunto de testes em outros contextos, incluindo o comando query. Observe que manual não implica que um destino não seja criado/executado automaticamente por sistemas de compilação/teste contínuos. Por exemplo, pode ser desejável excluir um destino de bazel test ... porque ele exige sinalizações específicas do Bazel, mas ainda assim incluí-lo em execuções de pré-envio ou teste contínuo configuradas corretamente.
  • A palavra-chave external forçará a execução do teste incondicionalmente, seja qual for o valor de --cache_test_results.
Consulte Convenções de tags na enciclopédia de teste para ver mais convenções sobre tags anexadas a destinos de teste.
target_compatible_with

List of labels ; optional

Uma lista de constraint_values que precisa estar presente na plataforma de destino para que esse destino seja considerado compatível. Além das restrições já definidas pelo tipo de regra. Se a plataforma de destino não atender a todas as restrições listadas, o destino será considerado incompatível. Destinos incompatíveis são ignorados para criação e teste quando o padrão de destino é expandido (por exemplo, //..., :all). Quando especificados explicitamente na linha de comando, os destinos incompatíveis fazem com que o Bazel mostre um erro e cause uma falha no build ou teste.

Os destinos que dependem temporariamente de destinos incompatíveis são considerados incompatíveis. Eles também são ignorados para criação e teste.

Uma lista vazia, que é o padrão, indica que o destino é compatível com todas as plataformas.

Todas as regras, exceto as regras do espaço de trabalho, são compatíveis com este atributo. Para algumas regras, esse atributo não tem efeito. Por exemplo, especificar target_compatible_with para um cc_toolchain não é útil.

Consulte a página Plataformas para mais informações sobre como ignorar destinos incompatíveis.

testonly

Boolean; optional; default False except for test and test suite targets; nonconfigurable

Se for verdadeiro, somente os destinos somente de teste (como testes) poderão depender desse destino.

Da mesma forma, uma regra que não seja testonly não pode depender de nenhuma regra testonly.

Os testes (regras *_test) e os pacotes de testes (regras test_suite) são testonly por padrão.

Esse atributo significa que o destino não pode estar contido em binários que são lançados na produção.

Como o testonly é aplicado no tempo de compilação, não no ambiente de execução, e propaga viralmente pela árvore de dependências, ele precisa ser aplicado com cuidado. Por exemplo, stubs e falsificações que são úteis para testes de unidade também podem ser úteis para testes de integração envolvendo os mesmos binários que serão lançados para produção e, portanto, provavelmente não serão marcados apenas como teste. Por outro lado, as regras que são perigosas até mesmo para vincular, talvez porque substituam condicionalmente o comportamento normal, precisam ser marcadas como "somente teste".

toolchains

List of labels ; optional; nonconfigurable

O conjunto de destinos com as variáveis do Make que o destino pode acessar. Esses destinos são instâncias de regras que fornecem TemplateVariableInfo ou destinos especiais para tipos de conjuntos de ferramentas integrados ao Bazel. Entre elas estão:

  • @bazel_tools//tools/cpp:current_cc_toolchain
  • @bazel_tools//tools/jdk:current_java_runtime

Isso é diferente do conceito de resolução de conjunto de ferramentas, usado por implementações de regras para configuração dependente da plataforma. Não é possível usar esse atributo para determinar qual cc_toolchain ou java_toolchain específicos um destino vai usar.

visibility

List of labels ; optional; default default_visibility from package if specified, or //visibility:private otherwise; nonconfigurable

O atributo visibility em um destino controla se ele pode ser usado em outros pacotes. Consulte a documentação sobre visibilidade.

Atributos comuns a todas as regras de teste (*_test)

Nesta seção, descrevemos os atributos comuns a todas as regras de teste.

Atributo Descrição
args

List of strings; optional; subject to $(location) and "Make variable" substitution, and Bourne shell tokenization

Argumentos de linha de comando que o Bazel passa para o destino quando é executado com bazel test.

Esses argumentos são transmitidos antes de qualquer valor --test_arg especificado na linha de comando bazel test.

env

Dictionary of strings; optional; values are subject to $(location) and "Make variable" substitution

Especifica outras variáveis de ambiente a serem definidas quando o teste for executado por bazel test.

Esse atributo só se aplica a regras nativas, como cc_test, py_test e sh_test. Ele não se aplica às regras de teste definidas pelo Starlark. Para suas próprias regras do Starlark, adicione um atributo "env" e use-o para preencher um provedor TestEnvironment

env_inherit

List of strings; optional

Especifica outras variáveis de ambiente a serem herdadas do ambiente externo quando o teste é executado por bazel test.

Esse atributo só se aplica a regras nativas, como cc_test, py_test e sh_test. Ele não se aplica às regras de teste definidas pelo Starlark.

size

String "enormous", "large" "medium" or "small", default is "medium"; optional; nonconfigurable

Especifica a "intensidade" de um destino de teste: quanto tempo/recursos ele precisa executar.

Os testes de unidade são considerados "pequenos", os de integração "médios" e os de ponta a ponta "grandes" ou "grandes". O Bazel usa o tamanho para determinar um tempo limite padrão, que pode ser substituído usando o atributo timeout. O tempo limite é de todos os testes no destino BUILD, não para cada teste individual. Quando o teste é executado localmente, o size também é usado para fins de programação: o Bazel tenta respeitar o --local_{ram,cpu}_resources e não sobrecarregar a máquina local executando muitos testes pesados ao mesmo tempo.

Os tamanhos de teste correspondem aos seguintes tempos limite padrão e são presumidos como pico de uso dos recursos locais:

Tamanho RAM (em MB) CPU (em núcleos da CPU) Tempo limite padrão
pequeno 20 1 curto (1 minuto)
médio 100 1 moderado (5 minutos)
grande 300 1 longo (15 minutos)
enorme 800 1 eterno (60 minutos)

A variável de ambiente TEST_SIZE será definida como o valor desse atributo ao gerar o teste.

timeout

String "short", "moderate", "long", "eternal" (with the default derived from the test's size attribute); nonconfigurable

Por quanto tempo o teste deve ser executado antes de retornar.

Embora o atributo de tamanho de um teste controle a estimativa de recursos, o tempo limite de um teste pode ser definido de maneira independente. Se não for especificado explicitamente, o tempo limite será baseado no tamanho do teste. O tempo limite do teste pode ser substituído pela sinalização --test_timeout, por exemplo, para execução em determinadas condições conhecidas como lentas. Os valores de tempo limite do teste correspondem aos seguintes períodos:

Valor de tempo limite Período
short 1 minuto
moderado 5 minutos
long 15 minutos
eterno 60 minutos

Para tempos diferentes dos mencionados acima, o tempo limite do teste pode ser substituído pela sinalização bazel --test_timeout, por exemplo, para execução manual em condições conhecidas como lentas. Os valores de --test_timeout estão em segundos. Por exemplo, --test_timeout=120 definirá o tempo limite do teste como dois minutos.

A variável de ambiente TEST_TIMEOUT será definida como o tempo limite do teste (em segundos) ao gerar o teste.

flaky

Boolean; optional; default False; nonconfigurable

Marca o teste como irregular.

Se definido, executa o teste até três vezes, marcando-o como com falha apenas se falhar todas as vezes. Por padrão, esse atributo é definido como falso e o teste é executado apenas uma vez. Observe que o uso desse atributo geralmente não é recomendado. Os testes precisam ser confiáveis quando as declarações são mantidas.

shard_count

Non-negative integer less than or equal to 50; optional

Especifica o número de fragmentos paralelos a serem usados para executar o teste.

Esse valor substitui qualquer heurística usada para determinar o número de fragmentos paralelos para executar o teste. Observe que, para algumas regras de teste, esse parâmetro pode ser necessário para ativar a fragmentação em primeiro lugar. Consulte também --test_sharding_strategy.

Se a fragmentação de teste estiver ativada, a variável de ambiente TEST_TOTAL_SHARDS será definida como esse valor durante a geração do teste.

A fragmentação exige que o executor de teste seja compatível com o protocolo de fragmentação de teste. Caso contrário, ele provavelmente executará todos os testes em cada fragmento, o que não é o que você quer.

Consulte Fragmentação de testes na Enciclopédia de teste para ver detalhes sobre fragmentação.

local

Boolean; default False; nonconfigurable

Força o teste a ser executado localmente, sem sandbox.

Definir como "Verdadeiro" equivale a fornecer "local" como uma tag (tags=["local"]).

Atributos comuns a todas as regras binárias (*_binary)

Nesta seção, descrevemos os atributos comuns a todas as regras binárias.

Atributo Descrição
args

List of strings; optional; subject to $(location) and "Make variable" substitution, and Bourne shell tokenization; nonconfigurable

Argumentos de linha de comando que o Bazel vai transmitir ao destino quando forem executados pelo comando run ou como um teste. Esses argumentos são transmitidos antes dos especificados na linha de comando bazel run ou bazel test.

OBSERVAÇÃO: os argumentos não são transmitidos quando você executa o destino fora do Bazel. Por exemplo, executando manualmente o binário em bazel-bin/.

env

Dictionary of strings; optional; values are subject to $(location) and "Make variable" substitution

Especifica outras variáveis de ambiente a serem definidas quando o destino for executado por bazel run.

Esse atributo só se aplica a regras nativas, como cc_binary, py_binary e sh_binary. Ele não se aplica às regras executáveis definidas pelo Starlark.

OBSERVAÇÃO: as variáveis de ambiente não são definidas quando você executa o destino fora do Bazel (por exemplo, executando manualmente o binário em bazel-bin/).

output_licenses

List of strings; optional

As licenças dos arquivos de saída gerados por esse binário. Isso faz parte de uma API de licenciamento descontinuada que o Bazel não usa mais. Não use esse recurso.

Atributos configuráveis

A maioria dos atributos é "configurável", ou seja, os valores podem mudar quando o destino é criado de maneiras diferentes. Especificamente, os atributos configuráveis podem variar de acordo com as sinalizações transmitidas para a linha de comando do Bazel ou qual dependência downstream está solicitando o destino. Isso pode ser usado, por exemplo, para personalizar o destino de várias plataformas ou modos de compilação.

O exemplo a seguir declara diferentes fontes para diferentes arquiteturas de destino. A execução de bazel build :multiplatform_lib --cpu x86 cria o destino usando x86_impl.cc, enquanto a substituição de --cpu arm fará com que ele use arm_impl.cc.

cc_library(
    name = "multiplatform_lib",
    srcs = select({
        ":x86_mode": ["x86_impl.cc"],
        ":arm_mode": ["arm_impl.cc"]
    })
)
config_setting(
    name = "x86_mode",
    values = { "cpu": "x86" }
)
config_setting(
    name = "arm_mode",
    values = { "cpu": "arm" }
)

A função select() escolhe entre diferentes valores alternativos para um atributo configurável com base em quais critérios config_setting ou constraint_value atendem à configuração do destino.

O Bazel avalia atributos configuráveis depois de processar macros e antes de processar regras (tecnicamente, entre as fases de carregamento e análise). Qualquer processamento antes da avaliação de select() não sabe qual ramificação o select() escolhe. Por exemplo, as macros não podem mudar o comportamento com base na ramificação escolhida, e o bazel query só pode fazer suposições conservadoras sobre as dependências configuráveis de um destino. Consulte estas perguntas frequentes para saber mais sobre o uso de select() com regras e macros.

Os atributos marcados como nonconfigurable na documentação não podem usar esse recurso. Geralmente, um atributo não é configurável porque o Bazel precisa saber seu valor internamente antes de determinar como resolver um select().

Consulte Atributos de compilação configuráveis para uma visão geral detalhada.

Destinos de saída implícita

As saídas implícitas em C++ foram descontinuadas. Não use esse recurso em outros idiomas sempre que possível. Ainda não temos um caminho de descontinuação, mas eles vão ser descontinuados.

Ao definir uma regra de build em um arquivo BUILD, você está declarando explicitamente um novo destino de regra nomeado em um pacote. Muitas funções de regra de compilação também implícitas a um ou mais destinos de arquivo de saída, cujo conteúdo e significado são específicos da regra. Por exemplo, ao declarar explicitamente uma regra java_binary(name='foo', ...), você também declara implicitamente um destino de arquivo de saída foo_deploy.jar como membro do mesmo pacote. Esse destino específico é um arquivo Java independente e adequado para implantação.

Os destinos de saída implícitos são membros de primeira classe do gráfico de destino global. Assim como outros destinos, eles são criados sob demanda, quando especificado no comando de nível superior compilado, ou quando são pré-requisitos para outros destinos de build. Eles podem ser referenciados como dependências em arquivos BUILD e podem ser observados na saída de ferramentas de análise, como bazel query.

Para cada tipo de regra de build, a documentação da regra contém uma seção especial que detalha os nomes e o conteúdo de qualquer saída implícita implícita por uma declaração desse tipo.

Uma distinção importante, mas sutil, entre os dois namespaces usados pelo sistema de compilação: rótulos identificam destinos, que podem ser regras ou arquivos, e os destinos de arquivos podem ser divididos em destinos de arquivos de origem (ou entrada) e destinos de arquivos derivados (ou de saída). São os itens que você pode mencionar em arquivos BUILD, criar a partir da linha de comando ou examinar usando bazel query. Esse é o namespace de destino. Cada destino de arquivo corresponde a um arquivo real no disco (o "namespace do sistema de arquivos"). Cada destino de regra pode corresponder a zero, um ou mais arquivos reais no disco. Pode haver arquivos no disco sem um destino correspondente. Por exemplo, os arquivos de objeto .o produzidos durante a compilação em C++ não podem ser referenciados em arquivos BUILD ou na linha de comando. Dessa forma, a ferramenta de compilação pode ocultar determinados detalhes de implementação. Isso é explicado com mais detalhes na Referência de conceitos do BUILD