Esta seção define vários termos e conceitos comuns a muitas funções ou regras de build.
Conteúdo
- Tokenização de shell Bourne
- Expansão de rótulos
- Atributos típicos definidos pela maioria das regras de build
- Atributos comuns a todas as regras de build
- Atributos comuns a todas as regras de teste (*_test)
- Atributos comuns a todas as regras binárias (*_binary)
- Atributos configuráveis
- Alvos de saída implícitos
Tokenização do shell Bourne
Alguns atributos de string de algumas regras são divididos em várias palavras de acordo com as regras de tokenização do shell Bourne: espaços sem aspas delimitam palavras separadas, e caracteres de aspas simples e duplas e barras invertidas são usados para evitar a tokenização.
Os atributos sujeitos a essa tokenização são indicados explicitamente como tais nas definições deste documento.
Atributos sujeitos à expansão de variáveis "Make" e à tokenização do shell Bourne
são normalmente 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
variável de string seja expandida para uma lista de palavras de opção
específica da configuração.
Expansão de rótulos
Alguns atributos de string de poucas regras estão sujeitos à expansão
de rótulos: se essas strings contêm um rótulo válido como uma
substring, como //mypkg:target, e esse rótulo é um
pré-requisito declarado da regra atual, ele é expandido para o
caminho do arquivo representado pelo
target
//mypkg:target.
Exemplos de atributos incluem genrule.cmd e
cc_binary.linkopts. Os detalhes podem variar significativamente em
cada caso, em questões como: 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 do atributo de regra para
detalhes.
Atributos típicos definidos pela maioria das regras de build
Esta seção descreve os atributos que são definidos por muitas regras de build, mas não por todas.
| Atributo | Descrição |
|---|---|
data |
Lista de rótulos; o padrão é Arquivos necessários para essa regra no momento da execução. Pode listar os arquivos ou as regras de destino. Geralmente, permite qualquer alvo.
As saídas padrão e os runfiles de destinos no atributo
As novas regras precisam definir um atributo |
deps |
Lista de rótulos; o padrão é
Dependencias para esse destino. Geralmente, só lista os destinos da regra. Embora
algumas regras permitam que os arquivos sejam listados diretamente em As regras específicas de idioma geralmente limitam os destinos listados a aqueles com provedores específicos.
A semântica precisa do que significa um destino depender de outro usando
Na maioria das vezes, uma dependência |
licenses |
Lista de strings não configuráveis;
o padrão é Uma lista de strings de tipo de licença a serem usadas para esse destino específico. Isso faz parte de uma API de licenciamento descontinuada que o Bazel não usa mais. Não use isso. |
srcs |
Lista de rótulos; o padrão é
Arquivos processados ou incluídos por essa regra. Geralmente lista arquivos diretamente, mas
pode listar os destinos da regra (como As regras específicas da linguagem geralmente exigem que os arquivos listados tenham extensões específicas. |
Atributos comuns a todas as regras de build
Esta seção descreve os atributos que são adicionados implicitamente a todas as regras de build.
| Atributo | Descrição |
|---|---|
compatible_with |
Lista de rótulos;
não configurável; o padrão é 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 alvos podem e não podem depender uns dos outros. Por exemplo, os binários implantáveis externamente não podem depender de bibliotecas com código secreto da empresa. Consulte ConstraintSemantics para mais detalhes. |
deprecation |
String; não configurável; o padrão é Uma mensagem de aviso explicativa associada a esse destino. Normalmente, isso é usado para notificar os usuários de que um destino ficou obsoleto, foi substituído por outra regra, é privado para um pacote ou é considerado prejudicial por algum motivo. É recomendável incluir alguma referência (como uma página da Web, um número de bug ou exemplos de CLs de migração) para que seja possível descobrir facilmente quais mudanças são necessárias para evitar a mensagem. Se houver um novo destino que possa ser usado como substituição, é recomendado migrar todos os usuários do destino antigo.
Esse atributo não tem efeito na forma 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 As dependências intrapacote estão isentas desse aviso. Por exemplo, a criação de testes de uma regra descontinuada não encontra um aviso. Se um destino descontinuado depender de outro destino descontinuado, nenhuma mensagem de aviso será emitida. Quando as pessoas param de usar, o público-alvo pode ser removido. |
distribs |
Lista de strings não configuráveis;
o padrão é Uma lista de strings de método de distribuição a serem usadas para esse destino específico. Isso faz parte de uma API de licenciamento descontinuada que o Bazel não usa mais. Não use isso. |
exec_compatible_with |
Lista de rótulos;
não configurável; o padrão é
Uma lista de
|
exec_properties |
Dicionário de strings. O padrão é Um dicionário de strings que será adicionado ao Se uma chave estiver presente nas propriedades da plataforma e do nível de destino, o valor será retirado do destino. |
features |
Lista de strings de atributo; o padrão é 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 |
restricted_to |
Lista de rótulos;
não configurável; o padrão é A lista de ambientes para os quais esse destino pode ser criado, em vez de ambientes com suporte padrão.
Isso faz parte do sistema de restrições do Bazel. Consulte
|
tags |
Lista de strings não configuráveis;
o padrão é
As tags podem ser usadas em qualquer regra. As tags nas regras de teste e
O Bazel modifica o comportamento do código de sandbox se encontrar as seguintes
palavras-chave no atributo
As 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 capacidade de anotação de tempo 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 encontrar as seguintes palavras-chave no
atributo
|
target_compatible_with |
Lista de rótulos; o padrão é
Uma lista de
Os destinos que dependem transitivamente 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) significa que o destino é compatível com todas as plataformas.
Todas as regras, exceto as regras do Workspace, são compatíveis com esse
atributo.
Para algumas regras, esse atributo não tem efeito. Por exemplo, especificar
Consulte a página Plataformas para mais informações sobre a omissão de destino incompatível. |
testonly |
Booleano; não configurável; o padrão é
Se
Da mesma forma, uma regra que não é
Os testes (regras Esse atributo significa que o destino não pode ser contido em binários lançados para produção. Como o testonly é aplicado no momento de build, não de execução, e se propaga de forma viral pela árvore de dependências, ele precisa ser usado com cuidado. Por exemplo, stubs e fakes 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 devem ser marcados como "testonly". Por outro lado, as regras que são perigosas para vincular, talvez porque elas substituem incondicionalmente o comportamento normal, devem ser marcadas como "teste somente". |
toolchains |
Lista de rótulos;
não configurável; o padrão é
O conjunto de destinos que podem acessar as variáveis Make desta meta. Esses destinos são instâncias de regras que fornecem
Isso é diferente do conceito de
resolução de cadeia de ferramentas
usado por implementações de regras para configuração dependente da plataforma. Não é possível usar esse
atributo para determinar qual |
visibility |
Lista de rótulos; não configurável; o padrão varia
O atributo
Para destinos declarados diretamente em um arquivo BUILD ou em macros legados chamados em
um arquivo BUILD, o valor padrão é o |
Atributos comuns a todas as regras de teste (*_test)
Esta seção descreve os atributos comuns a todas as regras de teste.
| Atributo | Descrição | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
Lista de strings; sujeita a substituição de
$(location) e
"Make variable" e
tokenização de shell Bourne; o padrão é Argumentos de linha de comando que o Bazel transmite para o destino quando é
executado com
Esses argumentos são transmitidos antes de qualquer valor |
||||||||||||||||||||
env |
Dicionário de strings. Os valores estão sujeitos à substituição de
$(location) e
"Make variable". O padrão é
Especifica outras variáveis de ambiente a serem definidas quando o teste é executado por
Esse atributo se aplica apenas a regras nativas, como |
||||||||||||||||||||
env_inherit |
Lista de strings. O padrão é Especifica variáveis de ambiente adicionais para herdar do
ambiente externo quando o teste é executado por
Esse atributo se aplica apenas a regras nativas, como |
||||||||||||||||||||
size |
String Especifica a "dificuldade" de um destino de teste: quanto tempo/recursos ele precisa para ser executado. Os testes de unidade são considerados "pequenos", os testes de integração são "médios" e os testes completos são "grandes" ou
"enormes". O Bazel usa o tamanho para determinar um tempo limite padrão, que pode ser substituído usando o
atributo Os tamanhos de teste correspondem aos seguintes tempos limite padrão e aos usos de recursos locais de pico presumidos:
A variável de ambiente
|
||||||||||||||||||||
timeout |
String Quanto tempo o teste deve durar antes de retornar.
Embora o atributo de tamanho de um teste controle a estimativa de recursos, o tempo limite
dele pode ser definido de forma 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 com a flag
Para outros tempos, o tempo limite do teste pode ser substituído com a
flag
A variável de ambiente
|
||||||||||||||||||||
flaky |
Booleano; não configurável;
o padrão é Marca o teste como instável. Se definido, executa o teste até três vezes, marcando-o como falha apenas se ele falha todas as vezes. Por padrão, esse atributo é definido como "False", e o teste é executado apenas uma vez. O uso desse atributo geralmente não é recomendado. Os testes precisam ser confiáveis quando as declarações são mantidas. |
||||||||||||||||||||
shard_count |
Número inteiro não negativo menor ou igual a 50. O padrão é Especifica o número de fragmentos paralelos a serem usados para executar o teste. Se definido, esse valor vai substituir todas as heurísticas usadas para determinar o número de
fragmentos paralelos para executar o teste. Para algumas regras de teste, esse parâmetro pode ser necessário para ativar o sharding. Consulte também Se o sharding de teste estiver ativado, a variável de ambiente A fragmentação exige que o executor de teste ofereça suporte ao protocolo de fragmentação de teste. Caso contrário, provavelmente ele vai executar todos os testes em todos os fragmentos, o que não é o que você quer. Consulte Test Sharding na Enciclopédia de testes para saber mais detalhes sobre o sharding. |
||||||||||||||||||||
local |
Booleano; não configurável;
o padrão é Força o teste a ser executado localmente, sem sandbox. Definir esse valor como "True" equivale a fornecer "local" como uma tag
( |
Atributos comuns a todas as regras binárias (*_binary)
Esta seção descreve os atributos comuns a todas as regras binárias.
| Atributo | Descrição |
|---|---|
args |
Lista de strings; sujeita a
$(location) e
"Make variable" substituição e
tokenização de shell Bourne;
não configurável;
o padrão é
Argumentos de linha de comando que o Bazel vai transmitir ao destino quando ele for executado
pelo comando
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
|
env |
Dicionário de strings. Os valores estão sujeitos à substituição de
$(location) e
"Make variable". O padrão é Especifica variáveis de ambiente adicionais a serem definidas quando o destino é
executado por
Esse atributo se aplica apenas a regras nativas, como
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
|
output_licenses |
Lista de strings. O padrão é 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 isso. |
Atributos configuráveis
A maioria dos atributos é "configurável", ou seja, os valores deles podem mudar quando o destino é criado de maneiras diferentes. Especificamente, os atributos configuráveis podem variar com base nas flags transmitidas para a linha de comando do Bazel ou na dependência downstream que está solicitando o destino. Isso pode ser usado, por exemplo, para personalizar o destino para várias plataformas ou modos de compilação.
O exemplo a seguir declara fontes diferentes para diferentes arquiteturas
de destino. A execução de bazel build :multiplatform_lib --cpu x86
vai criar 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
nos critérios de config_setting
ou constraint_value
que a configuração do destino atende.
O Bazel avalia atributos configuráveis após 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
ramo a select() escolhe. Macros, por exemplo, não podem mudar
o comportamento com base na ramificação escolhida, e bazel query só pode
fazer estimativas conservadoras sobre as dependências configuráveis de um destino. Consulte
estas perguntas frequentes
para saber mais sobre como usar select() com regras e macros.
Atributos marcados como nonconfigurable na documentação não podem
usar esse recurso. Normalmente, um atributo não é configurável porque o Bazel
precisa saber o valor internamente antes de determinar como resolver um
select().
Consulte Atributos de build configuráveis para ter uma visão geral detalhada.
Alvos de saída implícitos
As saídas implícitas em C++ foram descontinuadas. Evite usá-lo em outros idiomas, quando possível. Ainda não temos um caminho de descontinuação, mas eles serão descontinuados em algum momento.
Ao definir uma regra de build em um arquivo BUILD, você declara explicitamente
um novo destino de regra nomeado em um pacote. Muitas funções de regra de build
também implicitamente implicam 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 arquivo de saída
foo_deploy.jar como membro do mesmo pacote.
Esse destino específico é um arquivo Java independente 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 especificados no comando de build de nível superior ou quando são
pré-requisitos necessários para outros destinos de build. Elas podem ser
referenciadas como dependências em arquivos BUILD e observadas na
saída de ferramentas de análise, como bazel query.
Para cada tipo de regra de build, a documentação dela contém uma seção especial que detalha os nomes e o conteúdo de todas as saídas implícitas incluídas em uma declaração desse tipo de regra.
Uma distinção importante, mas um tanto sutil, entre os
dois namespaces usados pelo sistema de build:
os rótulos identificam alvos,
que podem ser regras ou arquivos, e os alvos de arquivo podem ser divididos em
alvos de arquivo de origem (ou de entrada) e alvos de arquivo derivados (ou de saída). Estas são as coisas que você pode mencionar em arquivos BUILD,
criar na 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.
Talvez haja arquivos no disco que não tenham um destino correspondente. Por
exemplo, 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 build pode ocultar alguns detalhes de implementação de
como ela faz o trabalho. Isso é explicado mais detalhadamente na
Referência de conceito do BUILD.