Regras gerais

Regras

• alias
• config_setting
• filegroup
• genquery
• genrule
• starlark_doc_extract
• test_suite

alias

alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

A regra alias cria outro nome para se referir a uma regra.

A criação de alias funciona apenas para destinos "regulares". Em especial, package_group e test_suite não podem ter alias.

O uso de alias pode ser útil em repositórios grandes, em que renomear um destino exigiria fazer mudanças em muitos arquivos. Você também pode usar a regra de alias para armazenar uma chamada de função select se quiser reutilizar essa lógica para vários destinos.

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 se refere (por exemplo, testonly no alias é ignorado; o testonly da regra referenciada é usado em vez disso) com algumas pequenas exceções:

• Os testes não são executados se o alias deles 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 atributo tests dela.
• Ao definir grupos de ambiente, os aliases para regras environment não são compatíveis. Elas 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

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 flags de build ou restrições de plataforma) para acionar atributos configuráveis. Consulte select para saber como usar essa regra e Atributos configuráveis para uma visão geral do recurso geral.

Exemplos

O seguinte corresponde a qualquer build que defina --compilation_mode=opt ou -c opt (explicitamente na linha de comando ou implicitamente nos arquivos .bazelrc):

  config_setting(
      name = "simple",
      values = {"compilation_mode": "opt"}
  )
  

O exemplo a seguir corresponde a qualquer build que tenha como destino o 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 seguinte corresponde a qualquer build que defina a flag definida pelo usuário --//custom_flags:foo=1 (explicitamente na linha de comando ou implicitamente nos arquivos .bazelrc):

  config_setting(
      name = "my_custom_flag_is_set",
      flag_values = { "//custom_flags:foo": "1" },
  )
  

O exemplo a seguir corresponde a qualquer build que tenha como destino 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. Uma plataforma ainda vai corresponder 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",
      ]
  )
  

Observações

• Consulte select para saber o que acontece quando vários config_settings correspondem ao estado de configuração atual.
• Para flags que aceitam formas abreviadas (por exemplo, --compilation_mode x -c), as definições de values precisam usar a forma completa. Elas correspondem automaticamente a invocações usando qualquer um dos formatos.
• Se uma flag aceitar vários valores (como --copt=-Da --copt=-Db ou uma flag do Starlark do tipo lista), values = { "flag": "a" } vai corresponder se "a" estiver presente em qualquer lugar na lista real.

  values = { "myflag": "a,b" } funciona da mesma forma: isso 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 flags. Por exemplo, --copt não aceita vários valores na mesma instância: --copt=a,b produz ["a,b"], enquanto --copt=a --copt=b produz ["a", "b"]. Portanto, values = { "copt": "a,b" } corresponde ao primeiro, mas não ao segundo. Mas --ios_multi_cpus (para regras da Apple) faz: -ios_multi_cpus=a,b e ios_multi_cpus=a --ios_multi_cpus=b produzem ["a", "b"]. Verifique as definições de flag e teste suas condições com cuidado para verificar as expectativas exatas.

• Se você precisar definir condições que não são modeladas por flags de build integradas, use flags definidas pelo Starlark. Também é possível usar --define, mas isso oferece suporte mais fraco e não é recomendado. Consulte este link para mais informações.
• Evite repetir definições idênticas de config_setting em pacotes diferentes. Em vez disso, faça referência a um config_setting comum definido em um pacote canônico.
• values, define_values e constraint_values podem ser usados em qualquer combinação no mesmo config_setting, mas pelo menos um precisa ser definido para qualquer config_setting.

Argumentos

            config_setting(
                name = "a_and_b",
                values = {
                    "define": "a=1",
                    "define": "b=2",
                })
          

            config_setting(
                name = "a_and_b",
                define_values = {
                    "a": "1",
                    "b": "2",
                })
          

filegroup

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. que podem ser referenciadas em outras regras.

Recomendamos usar filegroup em vez de referenciar diretórios diretamente. O último não é confiável porque o sistema de build não tem conhecimento completo de todos os arquivos abaixo do diretório. Portanto, ele pode não fazer rebuild quando esses arquivos mudam. Quando combinado com glob, filegroup pode garantir que todos os arquivos sejam explicitamente conhecidos pelo sistema de build.

Exemplos

Para criar um filegroup com dois arquivos de origem, faça o seguinte:

filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "some/subdirectory/another_file.txt",
    ],
)

Ou use um glob para rastrear um diretório testdata:

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

genquery

genquery(name, deps, data, compatible_with, compressed_output, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)

O genquery() executa uma consulta especificada na linguagem de consulta do Blaze e despeja o resultado em um arquivo.

Para manter a consistência do build, a consulta só pode visitar o fechamento transitivo das metas especificadas no atributo scope. As consultas que violarem essa regra vão falhar durante a execução se strict não for especificado ou for verdadeiro. Se strict for falso, os destinos fora do escopo serão ignorados com um aviso. A maneira mais fácil de evitar isso é 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 com 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 que destinos fora do fechamento transitivo da consulta influenciem a saída. Segundo, porque os arquivos BUILD não são compatíveis com dependências curinga (por exemplo, deps=["//a/..."] não é permitido).

A saída do genquery é ordenada lexicograficamente para impor uma saída determinística, com exceção de --output=graph|minrank|maxrank ou quando somepath é usado como a função de nível superior.

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

genrule

genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, 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 genrules são regras de build genéricas que podem ser usadas se não houver uma regra específica para a tarefa. Por exemplo, é possível executar um comando de uma linha do Bash. No entanto, se você precisar compilar arquivos C++, siga as regras cc_* atuais, porque todo o trabalho pesado já foi feito para você.

A genrule exige um shell para interpretar o argumento de comando. Também é fácil referenciar programas arbitrários disponíveis no PATH, mas isso torna o comando não hermético e pode não ser reproduzível. Se você só precisar executar uma ferramenta, use run_binary em vez disso.

Não use uma genrule para executar testes. Há dispensas especiais para testes e resultados de testes, incluindo políticas de cache e variáveis de ambiente. Os testes geralmente precisam ser executados depois que o build é concluído e na arquitetura de destino, enquanto as genrules são executadas durante o build e na arquitetura de execução (os dois 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 compilação cruzada.

Embora as genrules sejam executadas durante um build, as saídas delas são usadas com frequência após o build, para implantação ou teste. Considere o exemplo de compilação de código C para um microcontrolador: o compilador aceita arquivos de origem C e gera código que é executado em um microcontrolador. O código gerado não pode ser executado na CPU usada para criá-lo, mas o compilador C (se compilado da origem) precisa ser.

O sistema de build usa a configuração de execução para descrever as máquinas em que o build é executado e a configuração de destino para descrever as máquinas em que a saída do build deve ser executada. Ele oferece opções para configurar cada um deles e separa os arquivos correspondentes em diretórios diferentes para evitar conflitos.

Para genrules, o sistema de build garante que as dependências sejam criadas adequadamente: srcs são criados (se necessário) para a configuração de destino, tools são criados para a configuração de exec, e a saída é considerada para a configuração de destino. Ela também fornece variáveis "Make" que os comandos genrule podem transmitir às ferramentas correspondentes.

É intencional que a genrule não defina nenhum atributo deps: outras regras integradas usam metainformações dependentes de linguagem transmitidas entre as regras para determinar automaticamente como processar regras dependentes, mas esse nível de automação não é possível para genrules. As genrules funcionam puramente no nível de arquivo e runfiles.

Casos especiais

Compilação exec-exec: em alguns casos, o sistema de build precisa executar genrules para que a saída também possa ser executada durante o build. Por exemplo, se uma genrule criar um compilador personalizado que será usado por outra genrule, a primeira precisará produzir a saída para a configuração de execução, porque é lá que o compilador será executado na outra genrule. Nesse caso, o sistema de build faz a coisa certa automaticamente: ele cria o srcs e o outs da primeira genrule para a configuração de execução em vez da configuração de destino. Consulte o manual do usuário para mais informações.

Ferramentas do JDK e C++: para usar uma ferramenta do JDK ou do conjunto de compiladores C++, o sistema de build fornece um conjunto de variáveis para uso. Consulte a variável"Make" para mais detalhes.

Ambiente Genrule

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 higienizado que define apenas variáveis principais, como PATH, PWD, TMPDIR e algumas outras. Para garantir que os builds sejam reproduzíveis, a maioria das variáveis definidas no ambiente de shell do usuário não é transmitida para o comando da genrule. No entanto, o Bazel (mas não o Blaze) transmite o valor da variável de ambiente PATH do usuário. Qualquer mudança no valor de PATH fará com que o Bazel execute novamente o comando no próximo build.

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 seja aplicado no momento.

O sistema de build exclui automaticamente todos os arquivos de saída existentes, mas cria os diretórios principais necessários antes de executar uma genrule. Ele também remove todos os arquivos de saída em caso de falha.

Recomendações gerais

• Verifique se as ferramentas executadas por uma genrule são determinísticas e herméticas. Eles não devem gravar carimbos de data/hora na saída e precisam usar ordenação estável para conjuntos e mapas, além de gravar apenas caminhos de arquivo relativos na saída, não caminhos absolutos. Não seguir essa regra vai resultar em um comportamento inesperado de build (o Bazel não vai recompilar uma genrule que você achava que seria) e vai prejudicar o desempenho do cache.
• Use $(location) extensivamente para saídas, ferramentas e fontes. Devido à segregação de arquivos de saída para diferentes configurações, as genrules não podem depender de caminhos absolutos e/ou codificados.
• Escreva uma macro Starlark comum caso as mesmas genrules ou genrules muito semelhantes sejam usadas em vários lugares. Se a genrule for complexa, considere implementá-la em um script ou como uma regra do 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 genrule.
• Não grave mensagens informativas em stdout ou stderr. Embora seja útil para depuração, isso pode facilmente se tornar ruído. Uma genrule bem-sucedida não deve gerar saída. Por outro lado, uma genrule com falha precisa emitir boas mensagens de erro.
• $$ evaluates to a $, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such as ls $(dirname $x), one must escape it thus: ls $$(dirname $$x).
• Evite criar links simbólicos e diretórios. O Bazel não copia a estrutura de diretório/symlink criada por genrules, e a verificação de dependência de diretórios não é confiável.
• Ao referenciar a genrule em outras regras, você pode usar o rótulo da genrule ou os rótulos de arquivos de saída individuais. Às vezes, uma abordagem é mais legível, às vezes a outra: referenciar saídas por nome no srcs de uma regra de consumo evita capturar sem querer outras saídas da genrule, mas pode ser tedioso se a genrule produzir 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 genrule.

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. Usar $(SRCS) em vez de diretivas $(location) explícitas também funciona. 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

starlark_doc_extract

starlark_doc_extract(name, deps, src, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility)

O starlark_doc_extract() extrai a documentação de regras, funções (incluindo macros), aspectos e provedores definidos ou reexportados em um determinado arquivo .bzl ou .scl. A saída dessa regra é um proto binário ModuleInfo, conforme definido em stardoc_output.proto na árvore de origem do Bazel.

Metas de saída implícitas

• name.binaryproto (a saída padrão): um proto binário A ModuleInfo.
• name.textproto (criado apenas se solicitado explicitamente): a versão proto de texto de name.binaryproto.

Aviso: não há garantia de que o formato de saída dessa regra seja estável. Ele é destinado principalmente ao uso interno pelo Stardoc.

Argumentos

test_suite

test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, tests, visibility)

Um test_suite define um conjunto de testes considerados "úteis" para humanos. 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 de forma transitiva pelo destino //some/test:suite (chamamos isso de "expansão test_suite"), depois o Blaze cria e testa esses destinos.

Exemplos

Um conjunto de testes para executar todos os testes pequenos no pacote atual.

test_suite(
    name = "small_tests",
    tags = ["small"],
)

Um pacote de testes que executa um conjunto especificado de testes:

test_suite(
    name = "smoke_tests",
    tests = [
        "system_unittest",
        "public_api_unittest",
    ],
)

Um pacote 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