Esta seção define diversos termos e conceitos comuns a muitas funções ou regras de build.
Índice
- 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ários palavras de acordo com as regras de tokenização do shell Bourne: espaços sem aspas delimitam palavras separadas, e caracteres simples e caracteres de aspas duplas e barras invertidas são usados para evitar a tokenização.
Os atributos sujeitos a essa tokenização são explicitamente indicado como tal nas suas definições neste documento.
Atributos sujeitos a "Marca" expansão variável e shell Bourne
a tokenização costuma ser usada para passar opções arbitrárias
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 para expandir em uma lista específica de configuração
de palavras de opção.
Expansão de rótulos
Alguns atributos de string de poucas regras estão sujeitos a rótulos,
expansão: se essas strings contiverem um rótulo válido como um
substring, como //mypkg:target, e esse rótulo é uma
declarado como pré-requisito da regra atual, ele é expandido na
nome do caminho do arquivo representado
target
//mypkg:target:
Exemplos de atributos incluem genrule.cmd e
cc_binary.linkopts. Os detalhes podem variar significativamente
cada caso, sobre problemas como: se os rótulos relativos estão
expandido; como os marcadores que se expandem para vários arquivos são
tratados etc. Consulte a documentação do atributo de regra para
especificidades.
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 todos.
| 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. Geral permite qualquer destino.
As saídas e os arquivos de execução padrão dos destinos no atributo
As novas regras precisam definir um atributo |
deps |
Lista de rótulos o padrão é
Dependências deste destino. Em geral, deve listar apenas destinos de regras. (Embora
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 alvo depender de outro usando
Na maioria das vezes, uma dependência |
licenses |
Lista de strings nonconfigurable;
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. O que não fazer use isso. |
srcs |
Lista de rótulos o padrão é
São os arquivos processados ou incluídos por esta regra. Geralmente, lista os arquivos diretamente,
pode listar destinos de regras (como As regras específicas de um idioma geralmente exigem que os arquivos listados tenham determinadas extensões de arquivo. |
Atributos comuns a todas as regras de build
Esta seção descreve os atributos que são implicitamente adicionados a todos os builds regras de firewall.
| Atributo | Descrição |
|---|---|
compatible_with |
Lista de rótulos
nonconfigurable; 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ções do Bazel, que permite aos usuários declarar quais podem e não podem depender uns dos outros. Por exemplo, implantações externas os binários não devem depender de bibliotecas com código secreto da empresa. Consulte ConstraintSemantics para mais detalhes. |
deprecation |
String; nonconfigurable; 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, seja substituído por outra regra, seja particular a um pacote ou seja considerados nocivos por algum motivo. É uma boa ideia incluir alguma referência (como uma página da Web, um número de bug ou exemplo de CLs de migração) para para que você possa descobrir facilmente quais alterações são necessárias para evitar a mensagem. Se houver um novo destino que possa ser usado como substituição, ele será É uma boa ideia migrar todos os usuários do destino antigo.
Esse atributo não afeta a forma como as coisas são construídas,
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. Assim, Por exemplo, criar os testes de uma regra descontinuada não encontrar um aviso. Se um destino descontinuado depender de outro destino descontinuado, nenhum aviso é emitida. Depois que as pessoas pararem de usá-lo, o alvo poderá ser removido. |
distribs |
Lista de strings nonconfigurable;
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. O que não fazer use isso. |
exec_compatible_with |
Lista de rótulos
nonconfigurable; 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 feature: o padrão é Um recurso é uma tag de string que pode ser ativada ou desativada em um destino. A significado de um atributo depende da própria regra. Esse atributo |
restricted_to |
Lista de rótulos
nonconfigurable; o padrão é A lista de ambientes para os quais o 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 nonconfigurable;
o padrão é
As tags podem ser usadas em qualquer regra. Tags no teste e
As regras
O Bazel modifica o comportamento do código de sandbox se encontrar o seguinte:
palavras-chave no atributo
As tags em testes geralmente são usadas para anotar a função de um teste na sua o processo de depuração e lançamento. Normalmente, as tags são mais úteis para C++ e Python testes, que não têm a capacidade de anotação de tempo de execução. O uso de tags e tamanhos oferece flexibilidade na montagem de conjuntos de testes baseados na base de código e a política de check-in.
O Bazel modifica o comportamento de execução do teste se encontrar as seguintes palavras-chave na
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 eles mesmos 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 as Regras do Workspace, têm suporte para isso.
.
Para algumas regras, esse atributo não tem efeito. Por exemplo, especificar
Consulte a Plataformas para mais informações sobre como pular destinos incompatíveis. |
testonly |
Booleano; nonconfigurable; o padrão é
Se for
Igualmente, uma regra que não seja
Testes ( Esse atributo significa que o destino não deve ser em binários lançados para produção. Como testonly é aplicado no tempo de build, não no ambiente de execução, e se propaga viralmente pela árvore de dependências, ela deve ser aplicada criteriosamente. Para 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 portanto, provavelmente não deve ser marcado como testonly. Por outro lado, regras que é perigoso até mesmo vincular, talvez porque eles incondicionalmente substituem o comportamento normal, precisam ser marcadas como somente teste. |
toolchains |
Lista de rótulos
nonconfigurable; o padrão é
O conjunto de destinos cujas Make variables esse destino está.
tem permissão de acesso. Essas metas são instâncias de regras que fornecem
Observe que isso é diferente do conceito de
resolução do conjunto de ferramentas
usado por implementações de regras para configuração dependente da plataforma. Não é possível usar
para determinar quais |
visibility |
Lista de rótulos
nonconfigurable;
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 sujeito a
$(location) e
Substituição "Make variables", e
Tokenização de shell Bourne o padrão é argumentos de linha de comando que o Bazel passa para o destino quando é
executada com
Esses argumentos são transmitidos antes de qualquer valor |
||||||||||||||||||||
env |
Dicionário de strings valores estão sujeitos a
$(location) e
Substituição "Make variables". o padrão é
Especifica as variáveis de ambiente adicionais a serem definidas quando o teste é executado pelo
Esse atributo só se aplica 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 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 completos são "grandes". ou
"enorme". O Bazel usa o tamanho para determinar um tempo limite padrão, que pode ser substituído usando o
Os tamanhos dos testes correspondem aos seguintes tempos limite padrão e recursos locais de pico presumidos de uso:
A variável de ambiente |
||||||||||||||||||||
timeout |
String Por quanto tempo o teste deve ser executado antes de retornar.
Enquanto o atributo de tamanho de um teste controla a estimativa de recursos, o
tempo limite pode ser definido de forma independente. Se não for especificado explicitamente, o
tempo limite é baseado no tamanho do teste. O teste
tempo limite pode ser substituído pela sinalização
Para horas diferentes dos acima, o tempo limite do teste pode ser substituído pelo valor-chave
Flag A variável de ambiente |
||||||||||||||||||||
flaky |
Booleano; nonconfigurable;
o padrão é Marca o teste como instável. Se definido, executa o teste até três vezes, marcando-o como com falha apenas se falha todas as vezes. Por padrão, esse atributo é definido como falso, e o teste é executada apenas uma vez. O uso deste atributo geralmente não é recomendado. os testes devem passar de maneira confiável quando as declarações forem mantidas. |
||||||||||||||||||||
shard_count |
Número inteiro não negativo menor ou igual a 50 o padrão é Especifica o número de fragmentos paralelos usar para executar o teste. Se definido, esse valor substituirá qualquer heurística usada para determinar o número de
os fragmentos paralelos com os quais executar o teste. Para alguns testes
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 teste para obter detalhes sobre fragmentação. |
||||||||||||||||||||
local |
Booleano; nonconfigurable;
o padrão é Força o teste a ser executado localmente, sem sandbox. Configurar esta opção como "True" é equivalente a fornecer informações "locais" 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 a
$(location) e
Substituição "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.
seja pelo comando
OBSERVAÇÃO: os argumentos não são passados quando você executa o comando
fora do Bazel (por exemplo, executando manualmente o binário
|
env |
Dicionário de strings valores estão sujeitos a
$(location) e
Substituição "Make variables". o padrão é Especifica as variáveis de ambiente adicionais a serem definidas quando o destino for
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
|
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. O que não fazer 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, atributos configuráveis podem variar de acordo com as flags passadas para a linha de comando do Bazel ou qual dependência downstream está solicitando o destino. Isso pode ser usado para exemplo, para personalizar o destino para várias plataformas ou modos de compilação.
O exemplo a seguir declara origens diferentes para cada destino
arquitetônicas. Executando bazel build :multiplatform_lib --cpu x86
vai criar o destino usando x86_impl.cc, substituindo
--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 que 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
regras de processamento (tecnicamente, entre as
de carregamento e análise).
Qualquer processamento anterior à avaliação de select() não sabe qual
ramificação escolhida pelo select(). Macros, por exemplo, não podem mudar
o comportamento com base na ramificação escolhida, e bazel query pode
só faz suposições conservadoras sobre as dependências configuráveis de um destino. Consulte
estas perguntas frequentes
para saber mais sobre como usar o select() com regras e macros.
Os atributos marcados com nonconfigurable na documentação não podem
usar esse recurso. Em geral, um atributo não é configurável porque o Bazel
internamente precisa saber seu valor 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, no futuro, elas também serão descontinuadas.
Quando você define uma regra de build em um arquivo BUILD, você é explicitamente
declarar um novo destino de regra nomeado em um pacote. Muitas regras de build
também implicam implicitamente um ou mais arquivos de saída
com conteúdos e significados específicos para cada regra.
Por exemplo, quando você declara explicitamente
java_binary(name='foo', ...) regra, você também
declarar implicitamente um arquivo de saída
segmente foo_deploy.jar como membro do mesmo pacote.
Esse destino específico é um arquivo Java independente adequado
para implantação.
Os alvos de saída implícitos são membros de primeira classe do
gráfico de destino. Assim como outros alvos, eles são criados sob demanda,
seja quando especificado no comando de criação de nível superior ou quando
são pré-requisitos necessários para outros destinos de build. Eles podem ser
referenciadas como dependências em arquivos BUILD e podem ser observadas em
o resultado de ferramentas de análise, como bazel query.
Para cada tipo de regra de compilação, a documentação da regra contém um seção especial, detalhando os nomes e conteúdos de quaisquer resultados resultantes 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, e os destinos dos arquivos podem ser divididos em
destinos de arquivo de origem (ou de entrada) e arquivo derivado (ou de saída)
de destino. Estes são os itens que podem ser mencionados
nos arquivos BUILD,
criar na linha de comando ou examinar usando bazel query;
este é o namespace de destino. Cada destino de arquivo corresponde
para um arquivo real no disco (o "namespace do sistema de arquivos"); cada regra
target pode corresponder a zero, um ou mais arquivos reais no disco.
Pode haver arquivos no disco que não tenham destino correspondente. para
exemplo, arquivos de objeto .o produzidos durante a compilação em 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 ele faz seu trabalho. Isso é explicado com mais detalhes
a Referência do conceito BUILD.