Regras gerais

Regras

• alias
• config_setting
• grupo de arquivos
• 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 para a regra.

A atribuição de alias só funciona para usuários de destino. 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 a que ela faz referência (por exemplo, somente teste no alias é ignorado. O argumento "testonly-ness" da regra referenciada é usada no lugar) 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 executa o teste referenciado, use um test_suite com um único destino na tests .
• Ao definir grupos de ambientes, os aliases das regras environment não são suporte. Eles não são compatíveis com a linha de comando --target_environment. também é possível fazer isso.

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 compilação ou restrições de plataforma) do para acionar atributos configuráveis. Consulte Selecionar para como consumir esta 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 comando 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 na .bazelrc):

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

O código abaixo 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 rótulo //example:glibc_2_25. Uma plataforma ainda corresponde se definir 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

• Acesse Selecionar para saber o que acontece quando vários config_settings correspondem ao estado de configuração atual.
• Para sinalizações compatíveis com formas abreviadas (por exemplo, --compilation_mode vs. -c), as definições de values precisam usar o formulário completo. Elas automaticamente fazer a correspondência das invocações usando um dos formatos.
• Se uma sinalização aceita vários valores, como --copt=-Da --copt=-Db ou um tipo de lista flag Starlark), values = { "flag": "a" } corresponde a quando "a" é presente em qualquer lugar da lista.

  values = { "myflag": "a,b" } funciona da mesma maneira: 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 de status. 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 sinalizações e teste as 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. Você também pode usar --define, mas essa opção oferece e não é recomendado. Consulte aqui para mais detalhes.
• Evite repetir definições de config_setting idênticas 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 usadas em qualquer combinação no mesmo config_setting, mas pelo menos uma deve 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",
                })
          

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 então ser referenciadas de outras regras.

É recomendável usar filegroup em vez de referenciar os diretórios diretamente. O segundo método não é seguro, uma vez que 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 mudarem. Quando combinado com glob, 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, faça o seguinte:

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

Ou use um glob para encontrar 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 no Linguagem de consulta Blaze e despeja o resultado. em um arquivo.

Para manter a consistência do build, a consulta só pode acessar o fechamento transitivo dos destinos especificados no scope. . As consultas que violam essa regra vão falhar durante a execução se strict não é especificado ou é verdadeiro (se strict for falso, as metas fora do escopo serão simplesmente ignoradas com um aviso). A a maneira mais fácil de garantir que isso não aconteça é mencionar os mesmos rótulos. no escopo como na expressão de consulta.

A única diferença entre as consultas permitidas aqui e no comando é que as consultas contendo especificações de destino de caractere curinga (por exemplo, //pkg:* ou //pkg:all) não são permitidos aqui. Os motivos são duplos: primeiro, porque genquery para especificar um escopo para evitar destinos fora do fechamento transitivo da consulta para influenciar o resultado, e, segundo, porque os arquivos BUILD não oferecem suporte a dependências de caracteres curinga (por exemplo, deps=["//a/..."] não é permitido).

A saída da genquery é ordenada usando --order_output=full na para aplicar a saída determinista.

O nome do arquivo de saída é o nome da regra.

Exemplos

Este exemplo grava a lista dos rótulos no fechamento transitivo da destino especificado para 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.

Regras gerais são regras de build genéricas que você pode usar se não houver uma regra específica para a tarefa. Por exemplo, você poderia executar um resumo do Bash. No entanto, se você precisar compilar arquivos C++, use às regras cc_* atuais, porque todo o trabalho pesado já foi feito. para você.

Não use uma regra geral para executar testes. Há disposições especiais para testes e testes incluindo políticas de armazenamento em cache e variáveis de ambiente. Geralmente, os testes precisam ser executados após a conclusão do build e na arquitetura final, enquanto as regras gerais são executadas durante do build e da arquitetura do host (os dois podem ser diferentes). Se você precisar de uma regra de teste, 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 regras gerais sejam executadas durante um build, as saídas delas costumam ser usadas depois do build, para implantação ou testes. Considere o exemplo de compilação de código C para um microcontrolador: o compilador aceita C arquivos-fonte e gera código que é executado em um microcontrolador. O código gerado, obviamente, não pode ser executado na CPU que foi usada para criá-lo, mas o compilador C (se compilado da origem) precisa fazer.

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 as máquinas em que a saída do build será para ser executada. Ele fornece opções para configurar cada uma delas e separa as arquivos correspondentes em diretórios separados para evitar conflitos.

No caso das regras gerais, o sistema de build 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 do host, e a saída é considerada como ser para a configuração target. Ele também fornece "Fazer" variáveis que os comandos genrule podem passar para as ferramentas correspondentes.

É intencional que "genrule" não defina nenhum atributo deps: outras regras integradas usam metainformações dependentes do idioma transmitidas entre as regras para determinar automaticamente como mas lidam com regras dependentes, mas esse nível de automação não é possível para regras gerais. Regras gerais funcionam apenas no nível do arquivo e dos arquivos de execução.

Casos especiais

Compilação host-host: em alguns casos, o sistema de compilação precisa executar regras gerais de modo que a também pode ser executada durante o build. Se, por exemplo, uma genrule criar um compilador personalizado que é usada posteriormente por outra regra geral, a primeira precisa produzir a saída para configuração do host, porque é nela que o compilador será executado na outra regra genuína. Nesse caso, o sistema de build faz a coisa certa automaticamente: ele cria a srcs e outs da primeira genrule para a configuração do host em vez do destino configuração do Terraform. Consulte o manual do usuário para mais informações. informações.

JDK e Ferramentas em C++: para usar uma ferramenta do JDK ou do pacote de compilador C++, o sistema de build fornece um conjunto de variáveis para uso. Consulte "Marca" variável para detalhes.

Ambiente de regra geral

O comando genrule é executado por um shell Bash configurado para falhar quando um comando ou um pipeline falhar, usando set -e -o pipefail.

A ferramenta de build executa o comando Bash em um ambiente de processo limpo que define apenas variáveis principais, como PATH, PWD TMPDIR e mais alguns. Para garantir que os builds sejam reproduzíveis, a maioria das variáveis definidas no shell do usuário não são transmitidos para o comando da genrule. No entanto, o Bazel (mas nã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 próximo build.

Um comando genrule não pode acessar a rede, exceto para conectar processos filhos do próprio comando, embora isso não seja aplicado no momento.

O sistema de compilação exclui automaticamente todos os arquivos de saída existentes, mas cria os arquivos pai necessários antes de executar uma regra geral. Ele também remove todos os arquivos de saída em caso de falha.

Recomendação geral

• Garantir que as ferramentas executadas por uma regra geral sejam determinísticas e herméticas. Eles não devem escrever carimbos de data/hora às saídas e devem usar a ordem estável para conjuntos e mapas, bem como gravar somente caminhos de arquivo relativos para a saída, sem caminhos absolutos. Não seguir essa regra levar a um comportamento de build inesperado (o Bazel não recria uma regra geral que você imaginava) e o desempenho do cache.
• Use $(location) extensivamente para saídas, ferramentas e fontes. Devido à de arquivos de saída para diferentes configurações, as regras gerais não podem depender de arquivos e/ou caminhos absolutos.
• Escreva uma macro Starlark comum caso regras gerais iguais ou muito semelhantes sejam usadas vários lugares. Se a regra for complexa, considere implementá-la em um script ou como um 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 a depuração, pode facilmente se tornar ruído; uma regra geral bem-sucedida deve ser silenciosa. Por outro lado, uma regra geral com falhas 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 pelo diretório/link simbólico criada pelas regras gerais e pela verificação de dependências dos diretórios não são consistentes.
• Ao fazer referência à regra geral em outras regras, é possível usar o rótulo dela ou rótulos de arquivos de saída individuais. Às vezes, a abordagem é mais legível, Outro: referenciar saídas por nome no srcs de uma regra de consumo evita coletar involuntariamente outras saídas da regra geral, mas pode ser entediante se ela gera muitas saídas.

Exemplos

Este exemplo gera foo.h. Não há fontes, porque o comando não leva qualquer entrada. O "binário" executado pelo comando é um script perl no mesmo pacote da 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 funcionaria. este exemplo usa a segunda para 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 que são considerados "úteis". para humanos. Isso permite que os projetos definam conjuntos de testes, como "testes que você deve executar antes do check-in", "nosso testes de estresse do projeto" ou "todos os testes pequenos". O comando blaze test respeita essa classificação da organização: para uma invocação como blaze test //some/test:suite, primeiro o Blaze enumera todos os destinos de teste incluídos transitivamente pelo destino //some/test:suite (nós chamar de "expansão test_suite" e, em seguida, o Blaze compila e testa esses destinos.

Exemplos

Um pacote de testes 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 não instáveis no pacote atual.

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

Argumentos