Regras
alias
alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)
A regra alias cria outro nome para o qual a regra pode ser referenciada.
A atribuição de aliases só funciona para destinos "normais". Em particular, package_group e test_suite não podem ter alias.
A regra de alias tem a própria declaração de visibilidade. Em todos os outros aspectos, ele se comporta como a regra a que faz referência (por exemplo, testonly no alias é ignorado, e a condição somente teste da regra referenciada é usada), com algumas pequenas exceções:
-
Os testes não são executados se o alias é mencionado na linha de comando. Para definir um alias
que execute o teste referenciado, use uma regra
test_suitecom um único destino no atributotests. -
Ao definir grupos de ambiente, os aliases para as regras
environmentnão são compatíveis. Eles também não são compatíveis com a opção de linha de comando--target_environment.
Exemplos
filegroup(
name = "data",
srcs = ["data.txt"],
)
alias(
name = "other",
actual = ":data",
)
Argumentos
| Atributos | |
|---|---|
name |
Um nome exclusivo para o destino. |
actual
|
|
config_setting
config_setting(name, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)
Corresponde a um estado de configuração esperado (expresso como sinalizações de build ou restrições de plataforma) para acionar atributos configuráveis. Consulte Selecionar para saber como consumir essa regra e Atributos configuráveis para uma visão geral do recurso geral.
Exemplos
O código a seguir corresponde a qualquer build que defina --compilation_mode=opt ou
-c opt (explicitamente na linha de comando ou implicitamente de arquivos .bazelrc):
config_setting(
name = "simple",
values = {"compilation_mode": "opt"}
)
O código a seguir corresponde a qualquer build destinado ao ARM e aplica a definição personalizada
FOO=bar (por exemplo, bazel build --cpu=arm --define FOO=bar ...):
config_setting(
name = "two_conditions",
values = {
"cpu": "arm",
"define": "FOO=bar"
}
)
O exemplo a seguir corresponde a qualquer build que defina
uma sinalização definida pelo usuário
--//custom_flags:foo=1, seja explicitamente na linha de comando ou implicitamente de
arquivos .bazelrc:
config_setting(
name = "my_custom_flag_is_set",
flag_values = { "//custom_flags:foo": "1" },
)
O exemplo a seguir corresponde a qualquer build destinado a uma plataforma com arquitetura x86_64 e glibc
versão 2.25, supondo a existência de um constraint_value com o rótulo
//example:glibc_2_25. Observe que uma plataforma ainda corresponde se define valores de restrição adicionais além desses dois.
config_setting(
name = "64bit_glibc_2_25",
constraint_values = [
"@platforms//cpu:x86_64",
"//example:glibc_2_25",
]
)
Em todos esses casos, é possível que a configuração mude dentro do build, por exemplo, se
um destino precisa ser criado para uma plataforma diferente da dependência dele. Isso significa que, mesmo quando um
config_setting não corresponde às flags de linha de comando de nível superior, ele ainda pode corresponder
a alguns destinos de build.
Observações
- Consulte select para saber o que acontece quando vários
config_settings correspondem ao estado de configuração atual. - Para flags compatíveis com formas abreviadas (por exemplo,
--compilation_modex-c), as definições devaluesprecisam usar o formato completo. Elas fazem correspondência automática com as invocações usando qualquer um dos formatos. -
Se uma flag assumir vários valores, como
--copt=-Da --copt=-Dbou uma flag Starlark do tipo lista,values = { "flag": "a" }vai fazer a correspondência se"a"estiver presente em qualquer lugar da lista real.values = { "myflag": "a,b" }funciona da mesma maneira: isso corresponde a--myflag=a --myflag=b,--myflag=a --myflag=b --myflag=c,--myflag=a,be--myflag=c,b,a. A semântica exata varia entre as sinalizações. Por exemplo,--coptnão oferece suporte a vários valores na mesma instância:--copt=a,bproduz["a,b"]enquanto--copt=a --copt=bproduz["a", "b"]. Portanto,values = { "copt": "a,b" }corresponde ao primeiro, mas não ao último. Mas--ios_multi_cpus(para regras da Apple) faz:-ios_multi_cpus=a,beios_multi_cpus=a --ios_multi_cpus=bproduzem["a", "b"]. Verifique as definições de sinalização e teste suas condições com cuidado para analisar as expectativas exatas. - Se você precisar definir condições que não sejam modeladas por flags de build integradas, use
flags definidas pelo Starlark. Também é possível usar
--define, mas isso oferece um suporte mais fraco e não é recomendado. Clique aqui para ver mais informações. - Evite repetir definições de
config_settingidênticas em pacotes diferentes. Em vez disso, referencie umconfig_settingcomum definido em um pacote canônico. values,define_valueseconstraint_valuespodem ser usados em qualquer combinação no mesmoconfig_setting, mas pelo menos um deles precisa ser definido para qualquerconfig_setting.
Argumentos
| Atributos | |
|---|---|
name |
Um nome exclusivo para o destino. |
constraint_values
|
constraint_values que a plataforma de destino precisa especificar para corresponder a esse config_setting. A plataforma de execução não é considerada aqui. Todos os outros valores de restrição que a plataforma tiver são ignorados. Consulte
Atributos de build configuráveis para saber mais detalhes.
Quando dois |
define_values
|
values, mas
especificamente para a sinalização --define.
Isso significa que:
config_setting(
name = "a_and_b",
values = {
"define": "a=1",
"define": "b=2",
})
não funciona porque a mesma chave (
config_setting(
name = "a_and_b",
define_values = {
"a": "1",
"b": "2",
})
corresponde corretamente a
|
flag_values
|
values, mas
para
flags de build definidas pelo usuário.
Esse é um atributo distinto, porque as sinalizações definidas pelo usuário são referenciadas como rótulos, enquanto as sinalizações integradas são referenciadas como strings arbitrárias. |
values
|
Essa regra herda a configuração do destino configurado que
o referencia em uma instrução Por conveniência, os valores de configuração são especificados como sinalizações de compilação (sem o Se uma sinalização não for definida explicitamente na linha de comando, o valor padrão será usado.
Se uma chave aparecer várias vezes no dicionário, somente a última instância será usada.
Se uma chave se referir a uma sinalização que pode ser definida várias vezes na linha de comando (por exemplo,
|
grupo de arquivos
filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)
Use filegroup para dar um nome conveniente a uma coleção de destinos.
Elas podem ser referenciadas em outras regras.
É recomendável usar filegroup em vez de referenciar diretórios diretamente.
O segundo não é confiável, porque o sistema de compilação não tem conhecimento total de todos os arquivos
abaixo do diretório. Portanto, ele pode não ser recompilado quando esses arquivos forem alterados. Quando combinado com o
glob, o filegroup pode garantir que todos os arquivos sejam
explicitamente conhecidos pelo sistema de build.
Exemplos
Para criar um filegroup que consiste em dois arquivos de origem,
filegroup(
name = "mygroup",
srcs = [
"a_file.txt",
"some/subdirectory/another_file.txt",
],
)
Ou use um glob para monitorar um diretório de dados de teste:
filegroup(
name = "exported_testdata",
srcs = glob([
"testdata/*.dat",
"testdata/logs/**/*.log",
]),
)
Para usar essas definições, faça referência ao filegroup com um rótulo de qualquer regra:
cc_library(
name = "my_library",
srcs = ["foo.cc"],
data = [
"//my_package:exported_testdata",
"//my_package:mygroup",
],
)
Argumentos
| Atributos | |
|---|---|
name |
Um nome exclusivo para o destino. |
srcs
|
É comum usar o resultado de uma expressão glob para
o valor do atributo |
data
|
Os destinos nomeados no atributo |
output_group
|
Um "grupo de saída" é uma categoria de artefatos de saída de um destino, especificado na implementação dessa regra. |
Genquery
genquery(name, deps, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)
genquery() executa uma consulta especificada na linguagem de consulta Blaze e despeja o resultado em um arquivo.
Para manter o build consistente, a consulta só pode visitar o fechamento transitivo dos destinos especificados no atributo scope. As consultas que violam essa regra falharão durante a execução se
strict não for especificado ou for verdadeiro. Se strict for falso,
os destinos fora do escopo serão simplesmente ignorados com um aviso. A maneira mais fácil de garantir que isso não aconteça é mencionar os mesmos rótulos no escopo e na expressão de consulta.
A única diferença entre as consultas permitidas aqui e na linha de comando é que as consultas que contêm especificações de destino de caracteres curinga (por exemplo, //pkg:* ou //pkg:all) não são permitidas aqui.
Há dois motivos para isso: primeiro, porque genquery precisa especificar um escopo para evitar que destinos fora do fechamento transitivo da consulta influenciem a saída e, segundo, porque os arquivos BUILD não são compatíveis com dependências de caracteres curinga (por exemplo, deps=["//a/..."] não é permitido).
A saída do genquery é ordenada usando --order_output=full para impor a saída determinística.
O nome do arquivo de saída é o nome da regra.
Exemplos
Neste exemplo, gravamos a lista dos rótulos no fechamento transitivo do destino especificado em um arquivo.
genquery(
name = "kiwi-deps",
expression = "deps(//kiwi:kiwi_lib)",
scope = ["//kiwi:kiwi_lib"],
)
Argumentos
| Atributos | |
|---|---|
name |
Um nome exclusivo para o destino. |
expression
|
:b nesse atributo no arquivo a/BUILD se referirá ao
destino //:b.
|
opts
|
bazel query. Algumas opções de consulta não são permitidas aqui: --keep_going, --query_file, --universe_scope, --order_results e --order_output. As opções não especificadas aqui terão os valores padrão, assim como na linha de comando de bazel query.
|
scope
|
|
strict
|
|
regra geral
genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, exec_tools, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)
Um genrule gera um ou mais arquivos usando um comando Bash definido pelo usuário.
As regras gerais são regras de criação genéricas que podem ser usadas se não houver uma regra específica para a tarefa.
Por exemplo, é possível executar um Bash de uma linha. No entanto, se você precisar compilar arquivos C++, siga as regras cc_* existentes, porque todo o trabalho pesado já foi feito para você.
Não use uma regra geral para executar testes. Há distribuições especiais para testes e resultados de testes, incluindo políticas de armazenamento em cache e variáveis de ambiente. Os testes geralmente precisam ser executados
após a conclusão da build e na arquitetura de destino, enquanto as regras gerais são executadas durante
a criação e na arquitetura host (as duas podem ser diferentes). Se você precisar de uma regra de teste
de uso geral, use sh_test.
Considerações sobre compilação cruzada
Consulte o manual do usuário para mais informações sobre a compilação cruzada.
Enquanto as regras gerais são executadas durante uma build, as saídas delas geralmente são usadas após a criação, para implantação ou teste. Considere o exemplo de compilação de código C para um microcontrolador: o compilador aceita arquivos-fonte C e gera um código que é executado em um microcontrolador. Obviamente, o código gerado não pode ser executado na CPU usada para criá-lo, mas o próprio compilador C (se compilado da origem) precisará fazer isso.
O sistema de build usa a configuração do host para descrever as máquinas em que o build é executado e a configuração de destino para descrever a(s) máquina(s) em que a saída da build será executada. Ele oferece opções para configurar cada um deles e segrega os arquivos correspondentes em diretórios separados para evitar conflitos.
Para genrules, o sistema de build garante que as dependências sejam criadas corretamente:
srcs são criadas (se necessário) para a configuração de destino,
tools são criadas para a configuração de host e a saída é considerada
para a configuração de destino. Ele também fornece
variáveis "Make" que os comandos de regra possam passar para as ferramentas correspondentes.
É intencional que a regra geral não defina nenhum atributo deps: outras regras integradas usam metainformações dependentes de idioma transmitidas entre as regras para determinar automaticamente como lidar com regras dependentes, mas esse nível de automação não é possível para regras gerais. As regras gerais funcionam
exclusivamente no nível de arquivo e de arquivos de execução.
Casos especiais
Compilação host-host: em alguns casos, o sistema de build precisa executar regras gerais de maneira que a
saída também possa ser executada durante o build. Se, por exemplo, uma regra geral criar um compilador personalizado que será usado posteriormente por outra regra, o primeiro precisará produzir a saída para a configuração do host, porque é nele que o compilador será executado na outra regra. Nesse caso, o sistema de compilação faz a coisa certa automaticamente: ele cria o srcs e o outs da primeira genrule para a configuração do host, em vez da configuração de destino. Para mais informações, consulte o manual do usuário.
Ferramentas JDK e C++: para usar uma ferramenta do JDK ou do pacote do compilador C++, o sistema de build fornece um conjunto de variáveis para uso. Consulte a variável"Make" para mais detalhes.
Ambiente de regra geral
O comando genrule é executado por um shell Bash configurado para falhar quando um comando
ou um pipeline falha, usando set -e -o pipefail.
A ferramenta de build executa o comando Bash em um ambiente de processo limpo que
define apenas as principais variáveis, como PATH, PWD, TMPDIR e algumas outras.
Para garantir que os builds sejam reproduzíveis, a maioria das variáveis definidas no ambiente shell do usuário não é transmitida para o comando do genrule. No entanto, o Bazel (mas não o Blaze) transmite o valor da variável de ambiente PATH do usuário.
Qualquer alteração no valor de PATH fará com que o Bazel execute novamente o comando na próxima compilação.
Um comando genrule não pode acessar a rede, exceto para conectar processos que são filhos do próprio comando, embora isso não esteja aplicado no momento.
O sistema de compilação exclui automaticamente todos os arquivos de saída existentes, mas cria todos os diretórios pais necessários antes de executar uma regra geral. Ele também remove todos os arquivos de saída em caso de falha.
Recomendações gerais
- Certifique-se de que as ferramentas executadas por uma regra geral sejam deterministas e herméticas. Eles não podem gravar carimbos de data/hora na saída e precisam usar uma ordem estável para conjuntos e mapas, além de gravar somente caminhos de arquivo relativos para a saída, sem caminhos absolutos. Não seguir essa regra levará a um comportamento de compilação inesperado (o Bazel não recriará uma regra geral que você imaginava) e degradar o desempenho do cache.
- Use
$(location)extensivamente para saídas, ferramentas e fontes. Devido à segregação dos arquivos de saída para diferentes configurações, as regras gerais não podem depender de caminhos absolutos e/ou codificados. - Escreva uma macro Starlark comum caso as regras gerais iguais ou muito semelhantes sejam usadas em vários locais. Se a regra geral for complexa, considere implementá-la em um script ou como uma regra Starlark. Isso melhora a legibilidade e a capacidade de teste.
- Certifique-se de que o código de saída indique corretamente o sucesso ou a falha da regra geral.
- Não grave mensagens informativas em stdout ou stderr. Embora seja útil para a depuração, isso pode facilmente se tornar ruído. Uma regra geral bem-sucedida deve ser silenciosa. Por outro lado, uma regra geral com falha emite boas mensagens de erro.
$$evaluates to a$, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such asls $(dirname $x), one must escape it thus:ls $$(dirname $$x).- Evite criar links simbólicos e diretórios. Ele não copia a estrutura de diretório/link simbólico criada por regras gerais, e a verificação de dependências dos diretórios não é instável.
- Ao fazer referência à regra geral em outras regras, é possível usar o rótulo dela ou de arquivos de saída individuais. Às vezes, a única abordagem é mais legível, às vezes a outra: referenciar as saídas pelo nome no
srcsde uma regra de consumo evita a seleção não intencional de outras saídas da regra geral, mas pode ser tedioso se a regra geral produzir muitas saídas.
Exemplos
Este exemplo gera foo.h. Não há origens porque o comando não recebe
nenhuma entrada. O "binário" executado pelo comando é um script Perl no mesmo pacote que a regra geral.
genrule(
name = "foo",
srcs = [],
outs = ["foo.h"],
cmd = "./$(location create_foo.pl) > \"$@\"",
tools = ["create_foo.pl"],
)
O exemplo a seguir mostra como usar um filegroup
e as saídas de outro genrule. Observe que o uso de $(SRCS) em vez
de diretivas $(location) explícitas também funciona. Este exemplo usa as últimas para
demonstração.
genrule(
name = "concat_all_files",
srcs = [
"//some:files", # a filegroup with multiple files in it ==> $(locations)
"//other:gen", # a genrule with a single output ==> $(location)
],
outs = ["concatenated.txt"],
cmd = "cat $(locations //some:files) $(location //other:gen) > $@",
)
Argumentos
| Atributos | |
|---|---|
name |
Um nome exclusivo para o destino. Você pode fazer referência a essa regra pelo nome na seção srcs ou deps de outras regras BUILD. Se a regra gerar arquivos de origem, use o
atributo srcs.
|
srcs
|
Esse atributo não é adequado para listar ferramentas executadas pelo
O sistema de build garante que esses pré-requisitos sejam criados antes de executar o comando
genrule. Eles são criados com a mesma configuração da solicitação de build original. Os nomes dos arquivos desses pré-requisitos estão disponíveis para o comando como uma lista separada por espaços em |
outs
|
Os arquivos de saída não podem cruzar os limites do pacote. Os nomes de arquivo de saída são interpretados como relativos ao pacote.
Se a sinalização
Espera-se que o comando genrule crie cada arquivo de saída em um local predeterminado.
O local está disponível em |
cmd
|
$(location)
e variável"Make".
cmd_bash, cmd_ps e cmd_bat,
se nenhum deles for aplicável.
Se o tamanho da linha de comando exceder o limite da plataforma (64 K no Linux/macOS, 8K no Windows),
a genrule gravará o comando em um script e o executará para solucionar o problema. Isso
se aplica a todos os atributos de cmd ( |
cmd_bash
|
Esse atributo tem prioridade mais alta que |
cmd_bat
|
Esse atributo tem prioridade mais alta do que
|
cmd_ps
|
Esse atributo tem prioridade mais alta que
Para tornar o PowerShell mais fácil de usar e menos propenso a erros, executamos os seguintes comandos para configurar o ambiente antes de executar o comando do PowerShell em genrule.
|
exec_tools
|
tools, exceto pelo fato de que essas dependências
serão configuradas para a plataforma de execução da regra, e não para a configuração do host.
Isso significa que as dependências em exec_tools não estão sujeitas às mesmas
limitações que as dependências em tools. Em especial, elas não precisam
usar a configuração do host para as próprias dependências transitivas. Consulte
tools para mais detalhes.
A equipe do Blaze está migrando todos os usos de |
executable
|
Definir essa flag como verdadeira significa que a saída é um arquivo executável e pode ser executado usando o
comando Não há suporte à declaração de dependências de dados do executável gerado. |
local
|
Se definida como "True", essa opção forçará a execução do
Isso é equivalente a fornecer "local" como uma tag ( |
message
|
Uma mensagem de progresso que vai ser mostrada quando esta etapa do build for executada. Por padrão, a mensagem é "Gerando a saída" (ou algo igualmente sem sentido), mas você pode fornecer uma mais específica. Use esse atributo em vez de |
output_licenses
|
common attributes
.
|
output_to_bindir
|
Se definida como verdadeira, essa opção fará com que os arquivos de saída sejam gravados no diretório |
tools
|
O sistema de build garante que esses pré-requisitos sejam criados antes de executar o comando genrule.
Eles são criados usando a configuração de
host, já que essas ferramentas são executadas como parte do build. O caminho de um
Qualquer |
test_suite
test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, tests, visibility)
Uma test_suite define um conjunto de testes considerados "úteis" para humanos. Isso
permite que os projetos definam conjuntos de testes, como "testes que precisam ser executados antes do check-in", "testes
de estresse do nosso projeto" ou "todos os testes pequenos". O comando blaze test respeita esse tipo
de organização: para uma invocação como blaze test //some/test:suite, o Blaze primeiro
enumera todos os destinos de teste incluídos transitivamente pelo destino //some/test:suite (chamamos
de "expansão test_suite"). Em seguida, o Blaze cria e testa esses destinos.
Exemplos
Um pacote para executar todos os testes pequenos no pacote atual.
test_suite(
name = "small_tests",
tags = ["small"],
)
Um pacote que executa um conjunto específico de testes:
test_suite(
name = "smoke_tests",
tests = [
"system_unittest",
"public_api_unittest",
],
)
Um pacote para executar todos os testes no pacote atual que não são instáveis.
test_suite(
name = "non_flaky_test",
tags = ["-flaky"],
)
Argumentos
| Atributos | |
|---|---|
name |
Um nome exclusivo para o destino. |
tags
|
As tags que começam com um caractere "-" são consideradas negativas. O caractere "-" anterior não é considerado parte da tag. Portanto, uma tag de pacote de "-small" corresponde ao tamanho "pequeno" de um teste. Todas as outras tags são consideradas positivas. Opcionalmente, para tornar as tags positivas mais explícitas, as tags também podem começar com o caractere "+", que não é avaliado como parte do texto da tag. Isso apenas torna a distinção positiva e negativa mais fácil de ler. Somente as regras de teste que corresponderem a todas as tags positivas e a nenhuma das tags negativas serão incluídas no pacote de testes. Isso não significa que a verificação de erros para dependências em testes filtrados é ignorada. As dependências em testes ignorados ainda precisam ser legais (por exemplo, não bloqueadas por restrições de visibilidade).
A palavra-chave da tag
O
Se você precisar de um |
tests
|
Qualquer
Se o atributo |