Nesta seção, definimos vários termos e conceitos comuns a muitas funções ou regras de compilação.
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
- Destinos de saída implícitos
Tokenização de shell Bourne
Certos 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.
Esses atributos que estão sujeitos a essa tokenização são explicitamente indicados como tal nas definições deste documento.
Atributos sujeitos à expansão de variável "Make" e à tokenização de shell 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 de palavras opcionais específicas da configuração.
Expansão de rótulos
Alguns atributos de string de poucas regras estão sujeitos à expansão de rótulo: se essas strings contiverem um rótulo válido como 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.
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 mais detalhes.
Atributos típicos definidos pela maioria das regras de build
Esta seção descreve os atributos definidos por muitas regras de build, mas não todas.
| Atributo | Descrição |
|---|---|
data |
Lista de rótulos. O padrão é Arquivos necessários para esta regra no momento da execução. Pode listar destinos de arquivos ou regras. Geralmente, permite qualquer destino.
As saídas e os arquivos de execução padrão dos destinos no atributo
Novas regras precisarão definir um atributo |
deps |
Lista de rótulos. O padrão é
Dependências deste destino. Em geral, deve listar apenas destinos de regras. Algumas regras permitem que os arquivos sejam listados diretamente em 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 do 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 é
São os arquivos processados ou incluídos por esta regra. Geralmente, lista arquivos diretamente, mas pode listar destinos de regras (como Regras específicas de linguagem 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 implicitamente adicionados a todas as regras de build.
| Atributo | Descrição |
|---|---|
compatible_with |
Lista de rótulos;
não configuráveis; o padrão é A lista de ambientes para os quais este destino pode ser criado, além de ambientes compatíveis por padrão. Isso faz parte do sistema de restrições do Bazel, que permite aos usuários declarar quais destinos podem ou não 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 esse destino. Normalmente, isso é usado para notificar os usuários de que um destino se tornou obsoleto ou foi substituído por outra regra, é particular a um pacote ou talvez seja considerado nocivo por algum motivo. É uma boa ideia incluir algumas referências (como uma página da Web, um número de bug ou exemplo 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, é recomendável 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 As dependências dentro do pacote estão isentas desse aviso para que, por exemplo, a criação dos testes de uma regra descontinuada não receba um aviso. Se um destino descontinuado depender de outro, nenhuma mensagem de aviso será emitida. Depois que as pessoas pararem de usá-lo, o alvo poderá ser removido. |
distribs |
Lista de strings; não configurável;
o padrão é Uma lista de strings do 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áveis; 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 no nível da plataforma e no nível do destino, o valor será retirado do destino. |
features |
Lista de strings de atributos. 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áveis; o padrão é É a lista de ambientes para os quais o destino pode ser criado, em vez de ambientes compatíveis com o padrão.
Isso faz parte do sistema de restrições do Bazel. Consulte
|
tags |
Lista de strings; não configurável;
o padrão é
As tags podem ser usadas em qualquer regra. Tags em regras de teste e
O Bazel modifica o comportamento do código de sandbox quando encontra as seguintes
palavras-chave no atributo
As tags nos 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 de C++ e Python, que não têm a capacidade de anotação de tempo de execução. O uso de tags e elementos de tamanho oferece flexibilidade na criação 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 pulados na criação e nos testes. Uma lista vazia (que é o padrão) significa que o destino é compatível com todas as plataformas.
Todas as regras, exceto Workspace Rules, aceitam esse
atributo.
Para algumas regras, esse atributo não tem efeito. Por exemplo, especificar
Consulte a página Plataformas para mais informações sobre saltos de destino incompatíveis. |
testonly |
Booleano, não configurável. O padrão é
Se for
Igualmente, uma regra que não é
Testes (regras Esse atributo significa que o destino não pode estar contido em binários lançados para produção. Como o testonly é aplicado no tempo de build, não no de execução, e se propaga rapidamente 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 podem ser marcados como somente teste. Por outro lado, regras que são perigosas para se vincular, talvez porque substituem incondicionalmente o comportamento normal, precisam ser marcadas como somente teste. |
toolchains |
Lista de rótulos;
não configuráveis; o padrão é
O conjunto de destinos cujas Make variables esse destino tem permissão para acessar. Esses destinos são instâncias de regras que fornecem
Observe que 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 |
visibility |
Lista de rótulos;
não configuráveis;
o padrão é
O atributo |
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 |
Lista de strings; sujeita à substituição de
$(location) e
"Make variables" 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 $(location) e "Make variables". O padrão é
Especifica outras variáveis de ambiente 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 outras variáveis de ambiente para herdar do ambiente externo quando o teste é executado por
Esse atributo só se aplica a regras nativas, como |
||||||||||||||||||||
size |
String Especifica o "peso" de um destino de teste: por 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 de ponta a ponta 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 dos testes correspondem aos seguintes tempos limite padrão e presumidos usos de recursos locais de pico:
A variável de ambiente |
||||||||||||||||||||
timeout |
String 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 vai ser baseado no tamanho do teste. O tempo limite
do teste pode ser substituído pela sinalização
Para outros momentos, o tempo limite do teste pode ser substituído pela sinalização 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 com falha apenas em caso de falha. Por padrão, esse atributo é definido como falso, e o teste é executado apenas uma vez. O uso desse atributo geralmente não é recomendado. Os testes precisam passar de forma 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 substituirá qualquer heurística usada para determinar o número de fragmentos paralelos com que 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 Se a fragmentação de testes estiver ativada, a variável de ambiente A fragmentação exige que o executor de testes ofereça suporte ao protocolo de fragmentação de testes. Se não tiver, o mais provável é que ele execute todos os testes em todos os fragmentos, o que não é o que você quer. Consulte Fragmentação de testes na Enciclopédia de testes para ver detalhes sobre a fragmentação. |
||||||||||||||||||||
local |
Booleano, não configurável. O padrão é Força o teste a ser executado localmente, sem sandbox. Definir isso como "True" é equivalente a fornecer "local" como uma tag
( |
Atributos comuns a todas as regras binárias (*_binário)
Esta seção descreve os atributos comuns a todas as regras binárias.
| Atributo | Descrição |
|---|---|
args |
Lista de strings; sujeito à substituição de
$(location) e
"Make variables", e
tokenização de shell Bourne;
não configurável;
o padrão é
Argumentos de linha de comando que o Bazel passa para o destino quando é 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 $(location) e "Make variables". 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 que esse binário gera. 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", o que significa que os valores deles 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 com a 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 origens diferentes para arquiteturas de destino distintas. A execução de bazel build :multiplatform_lib --cpu x86
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 satisfaz.
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. As macros, por exemplo, não podem mudar
o comportamento com base na ramificação escolhida, e 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 como usar 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 internamente o valor dele antes de determinar como resolver um
select().
Consulte Atributos de build configuráveis para uma visão geral detalhada.
Destinos de saída implícitos
As saídas implícitas em C++ foram descontinuadas. Evite usá-la em outros idiomas sempre que possível. Ainda não temos um caminho de descontinuação, mas eles também vão ser descontinuados.
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 envolvem implicitamente um ou mais destinos de arquivo
de saída, com conteúdo e significado específicos da regra.
Por exemplo, ao declarar explicitamente uma
regra java_binary(name='foo', ...), você também
declara implicitamente o destino de 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 criação 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 podem ser observadas
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 todas as saídas implícitas envolvidas por uma declaração desse tipo de regra.
Uma distinção importante, mas um pouco sutil, entre os
dois namespaces usados pelo sistema de build:
os rótulos identificam destinos,
que podem ser regras ou arquivos, e os destinos de arquivo podem ser divididos em
destinos de arquivo de origem (ou de entrada) e de arquivo
derivado (ou de saída). Essas são as coisas 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 em disco que não tenham um destino correspondente. Por
exemplo, arquivos de objeto .o produzidos durante a compilação C++
não podem ser referenciados dentro de arquivos BUILD ou na linha de comando.
Dessa forma, a ferramenta de build pode ocultar certos detalhes de implementação de
como ela faz o trabalho dela. Isso é explicado mais detalhadamente na Referência do conceito BUILD.