Regras
alias
Ver origem da regraalias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)
A regra alias
cria outro nome para uma regra.
O alias só funciona para destinos "normais". Em particular, package_group
e test_suite
não podem ter alias.
A regra de alias tem sua própria declaração de visibilidade. Em todos os outros aspectos, ela se comporta como a regra a que se refere (por exemplo, testonly no alias é ignorada; a testtestness-ness da regra referenciada é usada) com algumas pequenas exceções:
-
Os testes não serão executados se o alias for mencionado na linha de comando. Para definir um alias
que execute o teste referenciado, use uma regra
test_suite
com um único destino no atributotests
. -
Ao definir grupos de ambiente, os aliases das regras
environment
nã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 esse destino. |
actual
|
|
Configuração de configuração
Ver origem da regraconfig_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 compilação ou restrições de plataforma) para acionar atributos configuráveis. Consulte selecionar para consumir essa regra e atributos configuráveis para ter 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 que segmente ARM e aplique 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 código a seguir corresponde a qualquer build que defina
sinalização definida pelo usuário
--//custom_flags:foo=1
(explicitamente na linha de comando ou implicitamente de
arquivos .bazelrc):
config_setting( name = "my_custom_flag_is_set", flag_values = { "//custom_flags:foo": "1" }, )
Veja a seguir qualquer build que segmente uma plataforma com uma arquitetura x86_64 e glibc
2.25, supondo que exista um constraint_value
com o rótulo
//example:glibc_2_25
. Uma plataforma ainda vai fazer a correspondência se definir outros
valores de restrição 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 precisar ser criado para uma plataforma diferente da dependência, isso significa que, mesmo quando um
config_setting
não corresponde às sinalizações de linha de comando de nível superior, ele ainda pode corresponder a
alguns destinos de build.
Observações
- Consulte selecione o que acontece quando vários
config_setting
s correspondem ao estado de configuração atual. - Para sinalizações compatíveis com formulários abreviados (por exemplo,
--compilation_mode
e-c
), as definições devalues
precisam usar o formato completo. Eles correspondem automaticamente às invocações usando qualquer um dos formulários. -
Se uma sinalização usar vários valores (como
--copt=-Da --copt=-Db
ou uma sinalização Starlark do tipo lista),values = { "flag": "a" }
corresponderá se"a"
estiver presente em qualquer lugar na lista.values = { "myflag": "a,b" }
funciona da mesma forma: corresponde a--myflag=a --myflag=b
,--myflag=a --myflag=b --myflag=c
,--myflag=a,b
e--myflag=c,b,a
. A semântica exata varia entre as sinalizações. Por exemplo,--copt
não oferece suporte a vários valores na mesma instância:--copt=a,b
produz["a,b"]
enquanto--copt=a --copt=b
produz["a", "b"]
(de modo quevalues = { "copt": "a,b" }
corresponde ao primeiro, mas não ao último). Mas--ios_multi_cpus
(para regras da Apple) faz:-ios_multi_cpus=a,b
eios_multi_cpus=a --ios_multi_cpus=b
produzem["a", "b"]
. Verifique as definições da sinalização e teste suas condições com cuidado para conferir as expectativas exatas. - Se você precisar definir condições que não são modeladas por sinalizações de compilação integradas, use
sinalizações definidas pelo Starlark. Também é possível usar
--define
, mas isso oferece suporte mais fraco e não é recomendado. Veja mais informações aqui. - Evite repetir definições de
config_setting
idênticas em pacotes diferentes. Em vez disso, faça referência a umconfig_setting
comum definido em um pacote canônico. values
,define_values
econstraint_values
podem ser usados em qualquer combinação no mesmoconfig_setting
, mas pelo menos um deles precisa ser definido para qualquerconfig_setting
específico.
Argumentos
Atributos | |
---|---|
name |
Um nome exclusivo para esse 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. Quaisquer outros valores de restrição da plataforma serão ignorados. Consulte
Atributos de build configuráveis para mais detalhes.
No caso em que 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
sinalizações 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 a referencia em uma instrução Para facilitar, 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 dela será usado.
Se uma chave aparecer várias vezes no dicionário, somente a última instância será usada.
Se uma chave faz referência a uma sinalização que pode ser definida várias vezes na linha de comando (por exemplo,
|
grupo de arquivos
Ver origem da regrafilegroup(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.
Eles podem ser referenciados em outras regras.
Use filegroup
em vez de referenciar diretórios diretamente.
Como o sistema de compilação não tem conhecimento completo de todos os arquivos abaixo do diretório, ele pode não ser recriado quando esses arquivos forem alterados. Quando combinado com o
glob, o filegroup
pode garantir que todos os arquivos sejam
conhecidos explicitamente pelo sistema de compilação.
Exemplos
Para criar um filegroup
composto por dois arquivos de origem, faça o seguinte:
filegroup( name = "mygroup", srcs = [ "a_file.txt", "some/subdirectory/another_file.txt", ], )
Ou use uma glob
para criar 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 esse 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, especificada na implementação dessa regra. |
Genquery
Ver origem da regragenquery(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 a versão consistente, a consulta pode acessar apenas o fechamento transitivo dos destinos especificados no atributo scope
. As consultas que violarem essa regra falharão durante a execução se
strict
não for especificado ou verdadeiro. Se strict
for falso,
os destinos fora do escopo vão ser 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.
Os motivos são dois: primeiro, porque genquery
precisa
especificar um escopo para evitar destinos fora do fechamento transitivo da
consulta para influenciar a saída. Em segundo lugar, 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
aplicar a saída determinística.
O nome do arquivo de saída é o nome da regra.
Exemplos
Este exemplo grava a lista de 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 esse destino. |
expression
|
:b nesse atributo no arquivo a/BUILD se refere 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 como na linha de comando de bazel query .
|
scope
|
|
strict
|
|
regra geral
Ver origem da regragenrule(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 compilação genéricas que você pode usar se não houver uma regra específica para a tarefa.
Por exemplo, é possível executar uma linha de frente do Bash. No entanto, se você precisar compilar arquivos C++, mantenha as regras cc_*
existentes, porque todo o trabalho pesado já foi feito para você.
A regra geral requer um shell para interpretar o argumento de comando. Também é fácil referenciar programas arbitrários disponíveis no PATH. No entanto, isso torna o comando não hermético e pode não ser reproduzível. Se você precisa executar apenas uma ferramenta, use run_binary.
Não use uma regra geral para executar testes. Há exceções especiais para testes e resultados
de testes, incluindo políticas de armazenamento em cache e variáveis de ambiente. Geralmente, os testes precisam ser executados após a conclusão da compilação e na arquitetura de destino, enquanto as regras gerais são executadas durante a criação e na arquitetura executiva (os dois podem ser diferentes). Se você precisar de uma regra de teste de uso geral, use sh_test
.
Considerações sobre a compilação cruzada
Consulte o manual do usuário para mais informações sobre a compilação cruzada.
As regras gerais são executadas durante a compilação, mas as saídas costumam ser usadas após a criação, para implantação ou teste. Considere o exemplo da compilação de código C para um microcontrolador: o compilador aceita arquivos de origem 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 compilador C (se compilado a partir da origem) precisa fazer isso.
O sistema usa a configuração exec para descrever as máquinas em que a versão é executada, e a configuração de destino para descrever as máquinas em que a saída da versão deve ser executada. Ele oferece opções para configurar cada um deles e segrega os arquivos correspondentes em diretórios separados para evitar conflitos.
Para regras gerais, o sistema de compilação garante que as dependências sejam criadas corretamente: srcs
são criados (se necessário) para a configuração target, tools
são criados para a configuração exec e a saída é considerada para a configuração target. Ele também fornece
variáveis "Make" que os comandos de regra geral podem transmitir para as ferramentas correspondentes.
É intencional que a regra geral não defina nenhum atributo deps
. Outras regras integradas usam
informações meta relacionadas ao 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
apenas no nível do arquivo e dos arquivos de execução.
Casos especiais
Compilação de executivo-executivo: em alguns casos, o sistema de compilação precisa executar regras gerais para que a saída também possa ser executada durante o build. Por exemplo, se uma regra geral cria algum compilador personalizado que é usado posteriormente por outra regra, o primeiro precisa produzir a saída para a configuração exec, porque é onde o compilador será executado na outra regra geral. Nesse caso,
o sistema de compilação faz a coisa certa automaticamente: ele cria o srcs
e
outs
da primeira regra para a configuração exec em vez da configuração
de destino. Consulte o manual do usuário para mais
informações.
Ferramentas JDK e C++: para usar uma ferramenta do pacote JDK ou C++, o sistema de compilação oferece um conjunto de variáveis para usar. Consulte 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 compilação 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 as versões sejam reproduzíveis, a maioria das variáveis definidas no ambiente shell do usuário
não são transmitidas ao comando da regra. No entanto, o Bazel passa o valor da variável de ambiente PATH
do usuário, mas não o Blaze.
Qualquer alteração no valor de PATH
fará com que o Bazel execute novamente o comando no próximo build.
Um comando de regra geral não pode acessar a rede, exceto para conectar processos que são filhos do próprio comando, mas isso não é obrigatório no momento.
O sistema de compilação exclui automaticamente todos os arquivos de saída existentes, mas cria os diretórios pai necessários antes de executar uma regra geral. Ele também remove todos os arquivos de saída em caso de falha.
Consultoria geral
- As ferramentas executadas por uma regra precisam ser determinísticas e herméticas. Eles não devem gravar carimbos de data/hora na saída e usar ordens estáveis para conjuntos e mapas, além de gravar apenas caminhos de arquivo relativos na saída, sem caminhos absolutos. Se você não seguir essa regra, um comportamento de compilação inesperado será gerado (o Bazel não reconstruirá uma regra geral, e isso não afetará a performance do cache).
- Use
$(location)
extensivamente para saídas, ferramentas e fontes. Devido à segregação de arquivos de saída para diferentes configurações, as regras gerais não podem depender de caminhos codificados e/ou absolutos. - Escreva uma macro Starlark comum caso outras regras iguais ou muito semelhantes sejam usadas em vários lugares. 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.
- Verifique se o código de saída indica corretamente o sucesso ou a falha da regra geral.
- Não grave mensagens informativas em stdout ou stderr. Embora seja útil para 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 precisa emitir mensagens de erro adequadas.
$$
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. O Bazel não copia na estrutura de diretórios/links simbólicos criado por genrules, e a verificação de dependência dos diretórios não é coerente.
- Ao fazer referência à regra de regra em outras regras, você pode usar o rótulo da regra de regra ou os rótulos de arquivos de saída individuais. Às vezes, uma abordagem é mais legível e outras
faz referência a saídas por nome no
srcs
de uma regra de consumo para evitar a seleção não intencional de outras saídas da regra, mas pode ser tediosa se a regra gerar muitas saídas.
Exemplos
Este exemplo gera foo.h
. Não há fontes, 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 funcionaria. Este exemplo usa o último para fins de 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 esse destino. É possível mencionar essa regra por nome na seção srcs ou deps de outras regras
BUILD . Se a regra gerar arquivos de origem, use o
atributo srcs .
|
srcs
|
Esses atributos não são adequados para listar ferramentas executadas pelo
O sistema de compilação garante que esses pré-requisitos sejam criados antes de executar o comando
genrule. Eles são criados usando a mesma configuração que a 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 ultrapassar os limites do pacote. Os nomes de arquivo de saída são interpretados como relativos ao pacote.
Se a sinalização
O comando "genrule" cria 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 comprimento da linha de comando exceder o limite da plataforma (64K no Linux/macOS, 8K no Windows), o genrule vai gravar o comando em um script e executá-lo. Isso
se aplica a todos os atributos cmd ( |
cmd_bash
|
Este atributo tem prioridade mais alta que |
cmd_bat
|
Esse atributo tem prioridade mais alta que
|
cmd_ps
|
Esse atributo tem prioridade mais alta que
Para facilitar o uso do Powershell e reduzir a propensão a erros, executamos os seguintes comandos para configurar o ambiente antes de executar o comando Powershell na regra.
|
exec_tools
|
tools .
Havia um período em que |
executable
|
Definir essa sinalização como "True" significa que a saída é um arquivo executável e pode ser executada usando o
comando Não há suporte para a declaração de dependências de dados para o executável gerado. |
local
|
Se definida como verdadeira, essa opção forçará essa
Isso equivale a fornecer "local" como uma tag ( |
message
|
Uma mensagem de progresso vai ser exibida quando esta etapa do build for executada. Por padrão, a
mensagem é "Gerando output" (ou gerando uma saída igualmente uniforme), mas é possível fornecer uma
mais específica. Use esse atributo em vez de |
output_licenses
|
common attributes
.
|
output_to_bindir
|
Se definida como "True", essa opção fará com que os arquivos de saída sejam gravados no diretório |
tools
|
O sistema de compilação garante que esses pré-requisitos sejam criados antes da execução do comando genrule.
Eles são criados usando a configuração
exec, já que essas ferramentas são executadas como parte do build. O caminho de um
Qualquer |
conjunto de testes
Ver origem da regratest_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 que são considerados "úteis" para as pessoas. Isso
permite que os projetos definam conjuntos de testes, como "testes que você precisa executar 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 temporariamente pelo destino //some/test:suite
(chamados
de "expansão de test_suite"). Em seguida, o Blaze cria e testa esses destinos.
Exemplos
Um conjunto de testes para executar todos os pequenos testes no pacote atual.
test_suite( name = "small_tests", tags = ["small"], )
Um conjunto de testes que executa um conjunto específico de testes:
test_suite( name = "smoke_tests", tests = [ "system_unittest", "public_api_unittest", ], )
Um conjunto de testes 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 esse destino. |
tags
|
As tags que começam com "-" são consideradas tags negativas. O caractere "-" anterior não é considerado parte da tag. Portanto, uma tag do conjunto "-small" corresponde ao tamanho "pequeno" de um teste. Todas as outras tags são consideradas tags positivas. Opcionalmente, para tornar as tags positivas mais explícitas, as tags também podem começar com o caractere "+", que não será avaliado como parte do texto da tag. Isso apenas facilita a leitura das diferenças positivas e negativas. Somente as regras de teste que corresponderem a todas as tags positivas e 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 pelas restrições de visibilidade).
A palavra-chave da tag
O
Se você precisar de um |
tests
|
Qualquer
Se o atributo |