Esta seção define vários termos e conceitos comuns a muitas funções ou regras de build.
Índice
- Tokenização do 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
- Metas de saída implícitas
Tokenização do shell Bourne
Alguns atributos de string de certas 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 aspas simples e duplas e barras invertidas são usadas para evitar a tokenização.
Os atributos sujeitos a essa tokenização são explicitamente indicados como tal nas definições deste documento.
Os atributos sujeitos à expansão da variável "Make" e à tokenização do shell Bourne geralmente 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 seja expandida em uma lista de palavras de opção específica da configuração.
Expansão de rótulos
Alguns atributos de string de pouquíssimas regras estão sujeitos à expansão de rótulos: 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 para o nome do caminho do arquivo representado pelo //mypkg:target target.
Exemplos de atributos incluem genrule.cmd e cc_binary.linkopts. Os detalhes podem variar muito 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 saber mais detalhes.
Atributos típicos definidos pela maioria das regras de build
Esta seção descreve atributos 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 tempo de execução. Pode listar destinos de arquivos ou regras. Geralmente permite qualquer destino.
As saídas e os runfiles padrão das metas no atributo
As novas regras precisam definir um atributo |
deps |
Lista de rótulos. O padrão é
Dependências para essa meta. Geralmente, só deve listar destinos de regras de lista. Embora algumas regras permitam que os arquivos sejam listados diretamente em As regras específicas de idioma geralmente limitam os destinos listados àqueles 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ável;
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 esta regra. Geralmente lista arquivos diretamente, mas pode listar destinos de regras (como As regras específicas de idioma geralmente exigem que os arquivos listados tenham extensões de arquivo 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 |
|---|---|
aspect_hints |
Lista de rótulos. O padrão é Uma lista de rótulos arbitrários expostos a aspectos (em especial, aspectos invocados pelas dependências inversas desta regra), mas não à própria implementação da regra. Consulte a documentação para conjuntos de regras específicos da linguagem e saiba mais sobre o efeito de uma dica de aspecto específica. Pense em uma dica de aspecto como uma alternativa mais completa a uma tag: enquanto uma tag transmite apenas um estado booleano (a tag está presente ou ausente na lista Na prática, as dicas de aspecto são usadas para interoperabilidade entre diferentes conjuntos de regras específicos de linguagem. Por exemplo, imagine que você tenha uma meta Para um exemplo concreto, consulte
Práticas recomendadas:
|
compatible_with |
Lista de marcadores;
não configuráveis; o padrão é A lista de ambientes para os quais esse destino pode ser criado, além dos ambientes padrão compatíveis. Isso faz parte do sistema de restrições do Bazel, que permite aos usuários declarar quais targets podem e não podem depender uns dos outros. Por exemplo, 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 essa meta. Normalmente, isso é usado para notificar os usuários de que um destino ficou obsoleto, foi substituído por outra regra, é particular a um pacote ou é considerado prejudicial por algum motivo. É uma boa ideia 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 fácil descobrir quais mudanças são necessárias para evitar a mensagem. Se houver um novo destino que possa ser usado como substituição, é uma boa ideia migrar todos os usuários do destino antigo.
Esse atributo não afeta a 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 intra pacote estão isentas desse aviso. Por exemplo, a criação dos testes de uma regra descontinuada não gera um aviso. Se um destino descontinuado depender de outro, nenhuma mensagem de aviso será emitida. Quando as pessoas pararem de usar, o destino poderá ser removido. |
exec_compatible_with |
Lista de marcadores;
não configuráveis; o padrão é
Uma lista de
|
exec_group_compatible_with |
Dicionário de strings para listas de marcadores;
nonconfigurable; o padrão é
Um dicionário de nomes de grupos de execução para listas 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á extraído do destino. As chaves podem ter como prefixo o nome de um grupo de execução seguido por um |
features |
Lista de strings de recursos. 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 regra em si. Esse atributo |
package_metadata |
Lista de rótulos;
nonconfigurable; o padrão é o Uma lista de rótulos que são metadados associados sobre essa meta. Normalmente, os rótulos são regras simples que retornam um provedor de valores constantes. As regras e os aspectos podem usar esses rótulos para realizar uma análise adicional no gráfico de build.
O caso de uso canônico é o de
rules_license.
Para esse caso de uso, |
restricted_to |
Lista de marcadores;
não configuráveis; o padrão é A lista de ambientes para os quais esse destino pode ser criado, em vez de ambientes compatíveis por padrão.
Isso faz parte do sistema de restrições do Bazel. Consulte
|
tags |
Lista de strings; não configurável;
o padrão é
Tags podem ser usadas em qualquer regra. As tags em regras de teste e
O Bazel modifica o comportamento do código de isolamento em sandbox se encontrar as seguintes palavras-chave no atributo
As tags em testes geralmente são usadas para anotar a função de um teste no seu 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 do codebase.
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 também são considerados incompatíveis. Eles também são ignorados para criação e testes. 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 rejeição de destino incompatível. |
testonly |
Booleano; não configurável; o padrão é
Se
Da mesma forma, uma regra que não seja
Os testes (regras Esse atributo significa que o destino não deve estar contido em binários lançados para produção. Como o testonly é aplicado no momento da criação, não no momento da 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, regras que são perigosas até mesmo para vincular, talvez porque substituam incondicionalmente o comportamento normal, devem ser marcadas como testonly. |
toolchains |
Lista de marcadores;
não configuráveis; o padrão é
O conjunto de destinos que podem acessar as Variáveis de criação. 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 marcadores; não configuráveis; o padrão varia
O atributo
Para destinos declarados diretamente em um arquivo BUILD ou em macros legadas chamadas de
um arquivo BUILD, o valor padrão é o |
Atributos comuns a todas as regras de teste (*_test)
Esta seção descreve atributos comuns a todas as regras de teste.
| Atributo | Descrição | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
Lista de strings sujeita à substituição $(location) e "Criar variável" e à tokenização do shell Bourne. O padrão é Argumentos de linha de comando que o Bazel transmite ao destino quando ele é
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 "Criar variável". O padrão é
Especifica variáveis de ambiente adicionais a serem definidas quando o teste é executado por
Esse atributo só se aplica a regras nativas, como |
||||||||||||||||||||
env_inherit |
Lista de strings. O padrão é Especifica variáveis de ambiente adicionais a serem herdadas do ambiente externo quando o teste é executado por
Esse atributo só se aplica a regras nativas, como |
||||||||||||||||||||
size |
String Especifica a "intensidade" de um destino de teste: quanto tempo/recursos ele precisa para ser executado. Os testes de unidade são considerados "pequenos", os de integração "médios" e os completos "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 usos máximos presumidos de recursos locais:
A variável de ambiente
|
||||||||||||||||||||
timeout |
String 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 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 horários, o tempo limite do teste pode ser substituído pela 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 falhar 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 aprovados de maneira confiável 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 qualquer heurística usada para determinar o número de
fragmentos paralelos com que executar o teste. Em 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 testes seja compatível com o protocolo de fragmentação de testes. Caso contrário, provavelmente todos os testes serão executados em todos os fragmentos, o que não é o ideal. Consulte Test Sharding na Enciclopédia de testes para mais detalhes sobre o sharding. |
||||||||||||||||||||
local |
Booleano; não configurável;
o padrão é Força a execução do teste localmente, sem isolamento em sandbox. Definir como "True" é equivalente a fornecer "local" como uma tag ( |
Atributos comuns a todas as regras binárias (*_binary)
Esta seção descreve atributos comuns a todas as regras binárias.
| Atributo | Descrição |
|---|---|
args |
Lista de strings, sujeita à substituição $(location) e "Make variable" e à tokenização do 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, ao executar manualmente o binário em
|
env |
Dicionário de strings. Os valores estão sujeitos à substituição de $(location) e "Criar variável". O padrão é Especifica outras variáveis de ambiente a serem definidas quando o destino é
executado por
Esse atributo só se aplica 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 podem mudar quando o destino é criado de maneiras diferentes. Especificamente, os atributos configuráveis podem variar de acordo com as flags transmitidas à linha de comando do Bazel ou com a dependência downstream que 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. Executar bazel build :multiplatform_lib --cpu x86
vai criar o destino usando x86_impl.cc, enquanto substituir
--cpu arm vai fazer 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 de config_setting
ou constraint_value
a configuração da meta atende.
O Bazel avalia atributos configuráveis após o processamento de macros e antes das regras de processamento (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 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.
Os 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 internamente o valor dele antes de determinar como resolver um select().
Consulte Atributos de build configuráveis para uma visão geral detalhada.
Metas de saída implícitas
As saídas implícitas em C++ estão descontinuadas. Evite usar em outros idiomas, se possível. Ainda não temos um caminho de descontinuação, mas eles também serão 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 build também implicam um ou mais destinos de arquivo de saída, cujo conteúdo e significado são específicos da regra.
Por exemplo, quando você declara explicitamente uma regra java_binary(name='foo', ...), também está implicitamente declarando um destino de 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 outras metas, elas são criadas sob demanda, seja quando especificadas no comando de build de nível superior ou quando são pré-requisitos necessários para outras metas de build. Eles podem ser referenciados como dependências em arquivos BUILD e observados na saída de ferramentas de análise, como bazel query.
Para cada tipo de regra de build, a documentação contém uma seção especial que detalha os nomes e conteúdos de todas as saídas implícitas decorrentes de uma declaração desse tipo de regra.
Uma distinção importante, mas um pouco sutil, entre os dois namespaces usados pelo sistema de build: rótulos identificam destinos, que podem ser regras ou arquivos. Os destinos de arquivo podem ser divididos em destinos de arquivo de origem (ou entrada) e derivados (ou saída). Essas 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"), e 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, 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 determinados detalhes de implementação de
como ela faz o trabalho. Isso é explicado com mais detalhes na Referência de conceitos do BUILD.