Nesta seção, definimos vários termos e conceitos comuns a muitas funções ou regras de criação.
Conteúdo
- Tokenização do Bourne Shell (em inglês)
- 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 Bourne Shell
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 impedir a tokenização.
Os atributos sujeitos a essa tokenização são explicitamente indicados como tal nas definições neste documento.
Os atributos sujeitos à expansão de variável "Make" e à tokenização de Bourne Shell são normalmente usados para transmitir opções arbitrárias para 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 para uma lista específica da configuração de palavras de opçã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 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 de destino.
Os exemplos de atributos incluem genrule.cmd e
cc_binary.linkopts. Os detalhes podem variar significativamente em cada caso, em relação a problemas 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 ver 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 |
Arquivos necessários para esta regra no tempo de execução. Pode listar destinos de arquivos ou regras. Geralmente permite qualquer destino.
As saídas padrão e os arquivos de execução de destinos no atributo
As novas regras vão definir um atributo |
deps |
Dependências para esse destino. Em geral, deve listar apenas segmentações de regras. Embora
algumas regras permitam 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 exata do que significa um destino depender de outro usando
Na maioria das vezes, uma dependência |
licenses |
Uma lista de strings de tipo de licença a serem usadas para esse destino específico. Ela faz parte de uma API de licenciamento descontinuada que o Bazel não usa mais. Não use isso. |
srcs |
São os arquivos processados ou incluídos por esta regra. Geralmente, lista os arquivos diretamente, mas
pode listar destinos de regra (como As regras específicas de idioma 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 |
A lista de ambientes para que esse destino pode ser criado, além dos ambientes compatíveis com padrão. Isso faz parte do sistema de restrições do Bazel, que permite que os usuários declarem 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 ver mais detalhes. |
deprecation |
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, é privado para um pacote ou talvez seja considerado nocivo por algum motivo. É uma boa ideia incluir referência (como uma página da Web, um número de bug ou um exemplo de CLs de migração) para que seja possível descobrir facilmente quais alterações são necessárias para evitar a mensagem. Se houver um novo destino que possa ser usado como substituto, é recomendável migrar todos os usuários do destino antigo.
Esse atributo não tem efeito na criação, 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, de modo que, por exemplo, criar os testes de uma regra descontinuada não encontre um aviso. Se um destino descontinuado depender de outro, nenhuma mensagem de aviso será emitida. Depois que as pessoas param de usá-la, é possível remover a segmentação. |
distribs |
Uma lista de strings de método de distribuição a serem usadas para esse destino específico. Ela faz parte de uma API de licenciamento descontinuada que o Bazel não usa mais. Não use isso. |
exec_compatible_with |
Uma lista de
|
exec_properties |
Um dicionário de strings que serão adicionadas ao Se uma chave estiver presente nas propriedades no nível da plataforma e do destino, o valor será retirado do destino. |
features |
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. O atributo |
restricted_to |
A lista de ambientes para que esse destino pode ser criado, em vez de ambientes compatíveis com padrão.
Isso faz parte do sistema de restrições do Bazel. Consulte
|
tags |
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 encontra 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 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 proporciona 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 encontra as seguintes palavras-chave no atributo
|
target_compatible_with |
Uma lista de
Os destinos que dependem transitivamente de destinos incompatíveis também são considerados incompatíveis. Eles também são pulados para criação e teste. Uma lista vazia (que é a padrão) significa que o destino é compatível com todas as plataformas.
Todas as regras, exceto as regras do espaço de trabalho, 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 a opção de pular o destino incompatível. |
testonly |
Se for "True", apenas os destinos somente teste (como testes) poderão depender desse destino.
Equivalentemente, uma regra que não seja
Os testes (regras Esse atributo não pode estar contido em binários liberados para produção. Como o testonly é aplicado no tempo de build, não no tempo de execução, e se 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 devem ser marcados como somente teste. Por outro lado, regras perigosas para vincular, talvez porque substituem incondicionalmente o comportamento normal, precisam ser marcadas como somente teste. |
toolchains |
O conjunto de destinos em que Criar variáveis este destino tem permissão para acessar. Esses destinos são instâncias de regras que fornecem
Isso é diferente do conceito de resolução do conjunto de ferramentas, que é usado pelas implementações de regras para configuração dependente da plataforma. Não é possível usar esse
atributo para determinar qual |
visibility |
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 |
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 |
Especifica variáveis de ambiente extras a serem definidas quando o teste é executado por
Esse atributo só se aplica a regras nativas, como |
||||||||||||||||||||
env_inherit |
Especifica outras variáveis de ambiente a serem herdadas do
ambiente externo quando o teste é executado por
Esse atributo só se aplica a regras nativas, como |
||||||||||||||||||||
size |
Especifica o "peso" 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 são "médios" e os de ponta a ponta são "grandes" ou
"enormes". O Bazel usa o tamanho para determinar um tempo limite padrão, que pode ser modificado usando o
atributo Os tamanhos de teste correspondem aos seguintes tempos limite padrão e pressupõem o pico de uso de recursos locais:
A variável de ambiente |
||||||||||||||||||||
timeout |
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 forma 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 horários diferentes dos indicados acima, o tempo limite do teste pode ser substituído pela
flag A variável de ambiente |
||||||||||||||||||||
flaky |
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 falso 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 deles são mantidas. |
||||||||||||||||||||
shard_count |
Especifica o número de fragmentos paralelos a serem usados para executar o teste. Esse valor substituirá qualquer heurística usada para determinar o número de fragmentos paralelos que serão usados para executar o teste. Esse parâmetro pode ser necessário para ativar a fragmentação
em algumas regras de teste. 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. Se isso não acontecer, ele provavelmente vai executar todos os testes em cada fragmento, que não é o que você quer. Consulte Fragmentação de teste na enciclopédia de teste para ver mais detalhes sobre a fragmentação. |
||||||||||||||||||||
local |
Força o teste a ser executado localmente, sem sandbox. Definir como "verdadeiro" é equivalente 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 |
Argumentos de linha de comando que o Bazel vai transmitir para o 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 |
Especifica variáveis de ambiente extras 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 o binário em
|
output_licenses |
As licenças dos arquivos de saída que este binário gera. Ela 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 podem mudar quando o destino é criado de maneiras diferentes. Especificamente, os atributos configuráveis podem variar com base nas sinalizações 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 de várias plataformas ou modos de compilação.
O exemplo a seguir declara diferentes origens para diferentes arquiteturas de destino. 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 config_setting
ou constraint_value
atendidos pela configuração de destino.
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 delas com base na ramificação escolhida, e bazel query só faz 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. 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.
Destinos de saída implícitos
O uso das saídas implícitas em C++ foi descontinuado. Evite usá-la em outros idiomas sempre que possível. Ainda não temos um caminho de descontinuação, mas o uso deles também será suspenso.
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 compilação 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 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.
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 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 criação, a documentação da regra contém uma seção especial que detalha os nomes e conteúdos de todas as saídas implícitas envolvidas em 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 de arquivos podem ser divididos em
destinos de arquivos de origem (ou entrada) e de arquivos derivados (ou de saída). Esses 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"). O destino de cada regra
pode corresponder a zero, um ou mais arquivos reais no disco.
Pode haver arquivos no disco que não têm um destino correspondente. Por
exemplo, os arquivos de objeto .o produzidos durante a compilação em C++
não podem ser referenciados dentro dos 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 mais detalhadamente na Referência do conceito BUILD.