Regras gerais

Regras

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

alias

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

A regra alias cria outro nome pelo qual uma regra pode ser referenciada.

A atribuição de alias só funciona para destinos "normais". Especificamente, 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 referenciada (por exemplo, testonly no alias é ignorado; o valor somente teste da regra referenciada é usado), com algumas exceções pequenas:

• 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 atributo tests.
• Ao definir grupos de ambiente, os aliases para as 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

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 da 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 exemplo a seguir corresponde a qualquer build direcionado 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 código a seguir corresponde a qualquer build que defina uma 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" },
  )
  

O exemplo a seguir corresponde a qualquer build direcionado 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. Uma plataforma ainda corresponde se define 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 selecionar para saber o que acontece quando várias config_settings correspondem ao estado de configuração atual.
• Para sinalizações compatíveis com formas abreviadas (por exemplo, --compilation_mode x -c), as definições de values precisam usar o formato completo. Elas fazem a correspondência automática de invocações usando qualquer um dos formatos.
• Se uma sinalização assumir vários valores (como --copt=-Da --copt=-Db ou uma flag Starlark), values = { "flag": "a" } fará a correspondência se "a" estiver presente em qualquer lugar na lista real.

  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 flags. 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"] (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,b e ios_multi_cpus=a --ios_multi_cpus=b produzem ["a", "b"]. Confira as definições de sinalização e teste as condições com cuidado para conferir 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 um suporte mais fraco e não é recomendado. Confira este link para mais informações.
• Evite repetir definições de config_setting idênticas em pacotes diferentes. Em vez disso, referencie 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",
                })
          

grupode 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.

Recomendamos o uso de filegroup em vez de referenciar diretórios diretamente. O segundo não é seguro, 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 compilado novamente quando esses arquivos são alterados. Quando combinado com glob, filegroup garante que todos os arquivos sejam explicitamente conhecidos pelo sistema de compilação.

Exemplos

Para criar um filegroup que consiste em dois arquivos de origem, faça

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

Ou use um glob para identificar 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, 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 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 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 caractere curinga (por exemplo, //pkg:* ou //pkg:all) não são permitidas aqui. Os motivos são duplos: primeiro, porque genquery precisa especificar um escopo para impedir que destinos fora do fechamento transitivo da consulta influenciem a saída e, segundo, porque arquivos BUILD não aceitam dependências de caractere curinga (por exemplo, deps=["//a/..."] não é permitido).

A saída da 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

Este exemplo grava 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

Genrule

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 uma linha de apresentação Bash. No entanto, se você precisar compilar arquivos C++, siga as regras cc_* já 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 do build e na arquitetura de destino, enquanto as regras gerais são executadas durante a criação e na arquitetura do host (as duas podem ser diferentes). Se você precisar de uma regra de teste de uso geral, use sh_test.

Considerações de compilação cruzada

Para mais informações sobre compilação cruzada, consulte o manual do usuário.

Embora as regras gerais sejam executadas durante uma criação, 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 de origem C e gera um código que é executado em um microcontrolador. O código gerado obviamente não pode ser executado na CPU usada para criá-lo, mas o compilador C (se compilado da fonte) precisa fazer isso.

O sistema de compilação usa a configuração do host 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 será executada. Ele fornece opções para configurar cada um deles e separa 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 criadas (se necessário) para a configuração target, tools são criadas para a configuração host e a saída é considerada para a configuração target. Ele também fornece variáveis "Make" que os comandos genrule podem passar para as ferramentas correspondentes.

É intencional que a regra geral não defina um atributo deps. Outras regras integradas usam metainformações que dependem da linguagem e são 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 puramente no nível de arquivo e runfiles.

Casos especiais

Compilação host-host: em alguns casos, o sistema de build precisa executar regras gerais para que a saída também possa ser executada durante a criação. Se, por exemplo, uma regra geral criar um compilador personalizado que será usado posteriormente por outra regra geral, o primeiro terá que produzir a saída para a configuração do host, porque é nesse local que o compilador será executado na outra regra geral. Nesse caso, o sistema de compilação faz a coisa certa automaticamente: ele cria srcs e 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 do JDK e C++: para usar uma ferramenta do JDK ou do pacote de compilador C++, o sistema de compilação fornece um conjunto de variáveis a serem usadas. Consulte a variável"Make" para mais detalhes.

Ambiente de regra de geração

O comando genrule é executado por um shell Bash configurado para falhar quando um comando ou 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 as versões sejam reproduzíveis, a maioria das variáveis definidas no ambiente shell do usuário não é transmitida para o comando da regra geral. 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 o comando novamente no build seguinte.

Um comando genrule não deve 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 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 arquivos de saída em caso de falha.

Recomendação geral

• Garanta que as ferramentas executadas por uma regra geral sejam determinísticas 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 apenas caminhos de arquivo relativos à 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ê esperava) e reduzirá o desempenho do cache.
• Use $(location) extensivamente para saídas, ferramentas e fontes. Devido à segregação dos arquivos de saída para configurações diferentes, as regras gerais não podem depender de caminhos absolutos e/ou codificados.
• Escreva uma macro Starlark comum caso regras genéricas 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 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 regra geral.
• Não grave mensagens informativas em stdout ou stderr. Embora útil para depuração, isso pode facilmente se tornar ruído. Uma regra geral bem-sucedida precisa ser silenciosa. Por outro lado, uma regra geral com falha deve 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/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, uma abordagem é mais legível e, outras vezes, a outra: referenciar as saídas pelo nome no srcs de 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 o genrule.

genrule(
    name = "foo",
    srcs = [],
    outs = ["foo.h"],
    cmd = "./$(location create_foo.pl) > \"$@\"",
    tools = ["create_foo.pl"],
)

O exemplo a seguir mostra como usar uma filegroup e as saídas de outro genrule. O uso de $(SRCS) em vez de diretivas $(location) explícitas também funciona. Este exemplo usa as últimas 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

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 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 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 estejam instáveis.

test_suite(
    name = "non_flaky_test",
    tags = ["-flaky"],
)

Argumentos