Regras gerais

Regras

alias 

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

A regra alias cria outro nome que pode ser usado para se referir a uma regra.

A criação de pseudônimos só funciona para destinos "normais". Especificamente, package_group e test_suite não podem ter um 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, o teste no alias é ignorado; o teste da regra referenciada é usado) com algumas exceções menores:

  • 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.
  • Ao definir grupos de ambiente, os aliases para regras environment não são aceitos. 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

Name; required

Um nome exclusivo para essa segmentação.
actual

Label; required

O destino a que o alias se refere. Ele não precisa ser uma regra, também pode ser um arquivo de entrada.

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 selecionar para saber como usar essa regra e Atributos configuráveis para ter uma visão geral do recurso geral.

Exemplos

O exemplo a seguir 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 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 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 direcionado a uma plataforma com arquitetura x86_64 e glibc versão 2.25, considerando 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",
      ]
  )
Em todos esses casos, é possível que a configuração mude no 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 corresponder às flags de linha de comando de nível superior, ele ainda poderá corresponder a alguns destinos de build.

Observações

  • Consulte selecionar 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 em vez de -c), as definições de values precisam usar o formato completo. Elas correspondem automaticamente a invocações usando qualquer forma.
  • Se uma flag tiver vários valores (como --copt=-Da --copt=-Db ou uma flag do tipo lista Starlark), values = { "flag": "a" } vai corresponder se "a" estiver presente em qualquer lugar da lista.

    values = { "myflag": "a,b" } funciona da mesma maneira: ele 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 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 suas condições com cuidado para verificar as expectativas exatas.

  • Se você precisar definir condições que não sejam modeladas por flags de build integradas, use Flags definidas pelo Starlark. Você também pode 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

Atributos
name

Name; required

Um nome exclusivo para essa segmentação.
constraint_values

List of labels; optional; nonconfigurable

O conjunto mínimo de 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 valores de restrição adicionais que a plataforma tem são ignorados. Consulte Atributos de build configuráveis para mais detalhes.

Quando dois config_settings correspondem ao mesmo select, esse atributo não é considerado para determinar se um dos config_settings é uma especialização do outro. Em outras palavras, um config_setting não pode corresponder a uma plataforma com mais força do que outra.

define_values

Dictionary: String -> String; optional; nonconfigurable

É igual a values, mas especificamente para a flag --define.

--define é especial porque a sintaxe (--define KEY=VAL) significa que KEY=VAL é um valor do ponto de vista de uma flag do Bazel.

Isso significa: 

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

não funciona porque a mesma chave (define) aparece duas vezes no dicionário. Este atributo resolve esse problema: 

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

corresponde corretamente a bazel build //foo --define a=1 --define b=2.

O --define ainda pode aparecer em values com a sintaxe de flag normal, e pode ser misturado livremente com esse atributo, desde que as chaves do dicionário permaneçam distintas.

flag_values

Dictionary: label -> String; optional; nonconfigurable

O mesmo que values, mas para flags de build definidas pelo usuário.

Esse é um atributo distinto porque as flags definidas pelo usuário são referenciadas como rótulos, enquanto as flags integradas são referenciadas como strings arbitrárias.

values

Dictionary: String -> String; optional; nonconfigurable

O conjunto de valores de configuração que correspondem a essa regra (expresso como flags de build)

Essa regra herda a configuração do destino configurado que a referencia em uma instrução select. Ele é considerado como "corresponder" a uma invocação do Bazel se, para cada entrada no dicionário, a configuração corresponder ao valor esperado da entrada. Por exemplo, values = {"compilation_mode": "opt"} corresponde às invocações bazel build --compilation_mode=opt ... e bazel build -c opt ... nas regras configuradas para o destino.

Para sua conveniência, os valores de configuração são especificados como flags de build (sem "--" anterior). Mas lembre-se de que os dois não são iguais. Isso acontece porque os destinos podem ser criados em várias configurações no mesmo build. Por exemplo, a configuração "cpu" de um host corresponde ao valor de --host_cpu, não de --cpu. Assim, instâncias diferentes do mesmo config_setting podem corresponder à mesma invocação de forma diferente, dependendo da configuração da regra que as usa.

Se uma flag 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, apenas a última instância será usada. Se uma chave faz referência a uma flag que pode ser definida várias vezes na linha de comando (por exemplo, bazel build --copt=foo --copt=bar --copt=baz ...), uma correspondência ocorre se qualquer dessas configurações corresponder.

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

Recomendamos o uso de filegroup em vez de referenciar diretórios diretamente. O segundo 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 ser recriado quando esses arquivos mudarem. Quando combinado com glob, o 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 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 a 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

Name; required

Um nome exclusivo para essa segmentação.
srcs

List of labels; optional

A lista de destinos que são membros do grupo de arquivos.

É comum usar o resultado de uma expressão glob para o valor do atributo srcs.

data

List of labels; optional

A lista de arquivos necessários para essa regra no momento da execução.

Os destinos nomeados no atributo data serão adicionados ao runfiles desta regra filegroup. Quando o filegroup é referenciado no atributo data de outra regra, o runfiles dela é adicionado ao runfiles da regra dependente. Consulte a seção dependências de dados e a documentação geral de data para mais informações sobre como depender e usar arquivos de dados.

output_group

String; optional

O grupo de saída para coletar artefatos das origens. Se esse atributo for especificado, os artefatos do grupo de saída especificado das dependências serão exportados em vez do grupo de saída padrão.

Um "grupo de saída" é uma categoria de artefatos de saída de um destino, especificados na implementação da 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 do Blaze e armazena o resultado em um arquivo.

Para manter a consistência do build, a consulta só pode visitar a clausura transitiva das metas especificadas no atributo scope. As consultas que violam essa regra vão falhar durante a execução se strict for indefinido ou verdadeiro. Se strict for falso, os destinos fora do escopo serão ignorados com um aviso. A maneira mais fácil de garantir que isso não aconteça é mencionar os mesmos rótulos no escopo que na expressão da consulta.

A única diferença entre as consultas permitidas aqui e na linha de comando é que as consultas com especificações de destino de caractere curinga (por exemplo, //pkg:* ou //pkg:all) não são permitidas aqui. Isso acontece por dois motivos: primeiro, porque genquery precisa especificar um escopo para impedir que os destinos fora do fechamento transitivo da consulta influenciem a saída. Em segundo lugar, porque os arquivos BUILD não são compatíveis com dependências de curinga (por exemplo, deps=["//a/..."] não é permitido).

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

Name; required

Um nome exclusivo para essa segmentação.
expression

String; required

A consulta a ser executada. Ao contrário da linha de comando e de outros lugares nos arquivos BUILD, os rótulos aqui são resolvidos em relação ao diretório raiz do espaço de trabalho. Por exemplo, o rótulo :b neste atributo no arquivo a/BUILD se refere ao destino //:b.
opts

List of strings; optional

As opções transmitidas ao mecanismo de consulta. Elas correspondem às opções de linha de comando que podem ser transmitidas para 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

null; required

O escopo da consulta. A consulta não pode tocar em destinos fora do fechamento transitivo desses destinos.
strict

Boolean; optional; default is True

Se for verdadeiro, os destinos com consultas que escapam do fechamento transitivo dos escopos não serão criados. Se for falso, o Bazel vai mostrar um aviso e pular qualquer caminho de consulta que o levou para fora do escopo, enquanto conclui o restante da consulta.

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 genéricas de build podem ser usadas quando não há uma regra específica para a tarefa. Por exemplo, você pode executar um comando único 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ê.

Não use uma regra de geração para executar testes. Há dispensas especiais para testes e resultados de teste, 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 de geração são executadas durante o build e na arquitetura do host (as duas podem ser diferentes). Se você precisar de uma regra de teste 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.

Embora as regras de geração sejam executadas durante um build, as saídas delas são frequentemente usadas 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 obviamente não pode ser executado na CPU usada para criá-lo, mas o compilador C (se compilado da origem) precisa.

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 precisa ser executada. Ele oferece opções para configurar cada um deles e separa os arquivos correspondentes em diretórios separados para evitar conflitos.

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

A genrule não define nenhum atributo deps intencionalmente: outras regras integradas usam metainformações dependentes da linguagem transmitidas entre as regras para determinar automaticamente como processar regras dependentes, mas esse nível de automação não é possível para regras geradas. O Genrules funciona apenas no nível de arquivos e runfiles.

Casos especiais

Compilação entre hosts: em alguns casos, o sistema de build precisa executar regras de geração para que a saída também possa ser executada durante o build. Se, por exemplo, uma genrule criar um compilador personalizado que é usado posteriormente por outra genrule, a primeira precisa produzir a saída para a configuração do host, porque é lá que o compilador será executado na outra genrule. Nesse caso, o sistema de build faz a coisa certa automaticamente: ele gera o srcs e o outs da primeira genrule para a configuração do host 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 usar. Consulte Variável"Criar" 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 limpo 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 do 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 o comando novamente no próximo build.

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

O sistema de build exclui automaticamente todos os arquivos de saída existentes, mas cria todos 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.

Conselhos gerais

  • Garanta que as ferramentas executadas por uma regra geral sejam determinísticas e herméticas. Não é necessário gravar carimbos de data/hora na saída. Use ordenação estável para conjuntos e mapas, além de gravar apenas caminhos de arquivo relativos na saída, sem caminhos absolutos. Não seguir essa regra vai levar a um comportamento de build inesperado (o Bazel não recria uma genrule que você achava que ele recria) e vai degradar 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, o genrules não pode usar caminhos fixos e/ou absolutos.
  • Escreva uma macro Starlark comum caso as mesmas regras de geração ou regras muito semelhantes sejam usadas em vários lugares. Se a regra de geração for complexa, implemente-a 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 no stdout ou stderr. Embora seja útil para depuração, isso pode facilmente se tornar ruído. Uma genrule bem-sucedida precisa ser silenciosa. Por outro lado, uma genrule 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ência de diretórios é inválida.
  • Ao fazer referência à 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 em uma srcs de regra de consumo evita a seleção não intencional de outras saídas da regra, mas pode ser tedioso se a regra 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. O uso de $(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

Atributos
name

Name; required

Um nome exclusivo para essa segmentação.


Você pode se referir 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

List of labels; optional

Uma lista de entradas para essa regra, como arquivos de origem a serem processados.

Esse atributo não é adequado para listar ferramentas executadas pelo cmd. Use o atributo tools para elas.

O sistema de build garante que esses pré-requisitos sejam criados antes da execução do comando genrule. Eles são criados usando 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 $(SRCS). Como alternativa, o caminho de um destino srcs //x:y individual pode ser obtido usando $(location //x:y) ou $<, desde que seja a única entrada em srcs.

outs

List of filenames; required; nonconfigurable

Uma lista de arquivos gerados por essa regra.

Os arquivos de saída não podem cruzar os limites do pacote. Os nomes dos arquivos de saída são interpretados como relativos ao pacote.

Se a flag executable estiver definida, outs precisará conter exatamente um rótulo.

O comando genrule precisa criar cada arquivo de saída em um local predeterminado. O local está disponível em cmd usando variáveis "Make" específicas da regra geral ($@, $(OUTS), $(@D) ou $(RULEDIR)) ou usando a substituição $(location).

cmd

String; optional

O comando a ser executado. Sujeito à substituição de $(location) e da variável "Make".
  1. A primeira substituição $(location) é aplicada, substituindo todas as ocorrências de $(location label) e $(locations label) (e construções semelhantes usando variáveis relacionadas execpath, execpaths, rootpath e rootpaths).
  2. Em seguida, as variáveis"Make" são expandidas. As variáveis predefinidas $(JAVA), $(JAVAC) e $(JAVABASE) são expandidas na configuração host, para que as invocações Java executadas como parte de uma etapa de build possam carregar corretamente bibliotecas compartilhadas e outras dependências.
  3. Por fim, o comando resultante é executado usando o shell Bash. Se o código de saída for diferente de zero, o comando será considerado com falha.
Essa é a alternativa de cmd_bash, cmd_ps e cmd_bat, se nenhuma delas 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 executar esse script para contornar o problema. Isso se aplica a todos os atributos cmd (cmd, cmd_bash, cmd_ps, cmd_bat).

cmd_bash

String; optional

O comando Bash a ser executado.

Esse atributo tem prioridade maior que cmd. O comando é expandido e executado da mesma forma que o atributo cmd.

cmd_bat

String; optional

O comando em lote a ser executado no Windows.

Esse atributo tem prioridade maior que cmd e cmd_bash. O comando é executado de maneira semelhante ao atributo cmd, com as seguintes diferenças:

  • Esse atributo só se aplica ao Windows.
  • O comando é executado com cmd.exe /c e os seguintes argumentos padrão:
    • /S: remove as primeiras e últimas aspas e executa tudo o mais como está.
    • /E:ON: ativa o conjunto de comandos estendido.
    • /V:ON: ativa a expansão de variáveis atrasada.
    • /D: ignora as entradas de registro da AutoRun.
  • Após a substituição de $(location) e variável"Make", os caminhos serão expandidos para caminhos no estilo do Windows (com barra invertida).
cmd_ps

String; optional

O comando do PowerShell a ser executado no Windows.

Esse atributo tem prioridade maior que cmd, cmd_bash e cmd_bat. O comando é executado de maneira semelhante ao atributo cmd, mas com as seguintes diferenças:

  • Esse atributo só se aplica ao Windows.
  • O comando é executado com powershell.exe /c.

Para facilitar o uso do Powershell e reduzir a probabilidade de erros, executamos os seguintes comandos para configurar o ambiente antes de executar o comando do Powershell no genrule.

  • Set-ExecutionPolicy -Scope CurrentUser RemoteSigned: permite a execução de scripts não assinados.
  • $errorActionPreference='Stop': caso haja vários comandos separados por ;, a ação será encerrada imediatamente se um CmdLet do Powershell falhar, mas isso NÃO funciona para comandos externos.
  • $PSDefaultParameterValues['*:Encoding'] = 'utf8': muda a codificação padrão de utf-16 para utf-8.
exec_tools

List of labels; optional

Uma lista de dependências de ferramenta para essa regra. Esse comportamento é exatamente igual ao do atributo tools, exceto que essas dependências serão configuradas para a plataforma de execução da regra em vez da 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 particular, não é necessário 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 tools para usar a semântica exec_tools. Recomendamos que os usuários prefiram exec_tools a tools quando isso não causar problemas. Depois que a migração funcional for concluída, poderemos renomear exec_tools para tools. Você vai receber um aviso de descontinuação e instruções de migração antes que isso aconteça.

executable

Boolean; optional; nonconfigurable; default is False

Declare a saída como executável.

Definir essa flag como "true" significa que a saída é um arquivo executável e pode ser executada usando o comando run. Nesse caso, a genrule precisa produzir exatamente uma saída. Se esse atributo estiver definido, run vai tentar executar o arquivo, independentemente do conteúdo.

Não é possível declarar dependências de dados para o executável gerado.
local

Boolean; optional; default is False

Se definida como "True", essa opção força a execução da genrule usando a estratégia "local", o que significa que não há execução remota, sandboxing nem workers persistentes.

Isso é equivalente a fornecer "local" como uma tag (tags=["local"]).

message

String; optional

Uma mensagem de progresso.

Uma mensagem de progresso que será mostrada quando esta etapa de build for executada. Por padrão, a mensagem é "Gerando saída" (ou algo igualmente genérico), mas você pode fornecer uma mais específica. Use esse atributo em vez de echo ou outras instruções de impressão no comando cmd, porque isso permite que a ferramenta de build controle se essas mensagens de progresso são impressas ou não.

output_licenses

Licence type; optional

Consulte common attributes .
output_to_bindir

Boolean; optional; nonconfigurable; default is False

Se definida como "True", essa opção faz com que os arquivos de saída sejam gravados no diretório bin em vez do diretório genfiles.

tools

List of labels; optional

Uma lista de dependências de ferramenta para essa regra. Consulte a definição de dependências para mais informações.

O sistema de build garante que esses pré-requisitos sejam criados antes da execução do comando genrule. Eles são criados usando a configuração host, já que essas ferramentas são executadas como parte do build. O caminho de um alvo tools //x:y individual pode ser encontrado usando $(location //x:y).

Qualquer *_binary ou ferramenta a ser executada por cmd precisa aparecer nessa lista, não em srcs, para garantir que eles sejam criados na configuração correta.

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 que são 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 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 isso de "expansão do test_suite") e, em seguida, 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 especificado 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

Name; required

Um nome exclusivo para essa segmentação.
tags

List of strings; optional; nonconfigurable

Lista de tags de texto, como "pequeno", "banco de dados" ou "-instável". As tags podem ser qualquer string válida.

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 "-small" corresponde ao tamanho "small" de um teste. Todas as outras tags são consideradas tags positivas.

Opcionalmente, para tornar as tags positivas mais explícitas, elas também podem começar com o caractere "+", que não será avaliado como parte do texto da tag. Ele apenas facilita a distinção entre positivo e negativo.

Somente as regras de teste que correspondem a todas as tags positivas e nenhuma das tags negativas serão incluídas no conjunto de testes. Isso não significa que a verificação de erros para dependências de testes filtrados seja ignorada. As dependências de testes ignorados ainda precisam ser válidas (por exemplo, não bloqueadas por restrições de visibilidade).

A palavra-chave da tag manual é tratada de maneira diferente da anterior pela "expansão test_suite" realizada pelo comando blaze test em invocações que envolvem curingas padrões de destino. Nele, os segmentos test_suite marcados como "manual" são filtrados e, portanto, não são expandidos. Esse comportamento é consistente com a forma como blaze build e blaze test lidam com padrões de destino de caractere curinga em geral. Isso é explicitamente diferente do comportamento de blaze query 'tests(E)', já que os pacotes são sempre expandidos pela função de consulta tests, independentemente da tag manual.

O size de um teste é considerado uma tag para fins de filtragem.

Se você precisar de um test_suite que contenha testes com tags mutuamente exclusivas, como todos os testes pequenos e médios, será necessário criar três regras de test_suite: uma para todos os testes pequenos, outra para todos os testes médios e uma que inclua as duas anteriores.

tests

List of labels; optional; nonconfigurable

Uma lista de pacotes e destinos de teste de qualquer idioma.

Qualquer *_test é aceito aqui, independente do idioma. No entanto, nenhum alvo *_binary é aceito, mesmo que seja executado um teste. A filtragem por tags especificado é feita apenas para testes listados diretamente neste atributo. Se esse atributo contiver test_suites, os testes dentro deles não serão filtrados por esse test_suite (eles já são considerados filtrados).

Se o atributo tests não for especificado ou estiver vazio, a regra vai incluir por padrão todas as regras de teste no arquivo BUILD atual que não forem marcadas como manual. Essas regras ainda estão sujeitas à filtragem tag.