Regras gerais

Informar um problema Mostrar fonte Por noite · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

Regras

alias

Conferir origem da regra
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 atribuição de alias pode ser útil em repositórios grandes nos quais a renomeação de um destino exigiria fazer alterações em muitos arquivos. Também é possível usar a regra de alias para armazenar 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 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

Atributos
name

Nome; obrigatório

Um nome exclusivo para o destino.

actual

Rótulo obrigatório

O destino ao qual este alias se refere. Não precisa ser uma regra, pode ser uma entrada .

config_setting

Conferir origem da regra
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",
      ]
  )
  
Em todos esses casos, a configuração pode mudar no build, por exemplo, se um destino precisa ser criado para uma plataforma diferente da dependência dele. Isso significa que mesmo quando um config_setting não corresponde aos sinalizadores de linha de comando de nível superior, mas ainda pode corresponder alguns destinos de build.

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

Atributos
name

Nome; obrigatório

Um nome exclusivo para o destino.

constraint_values

Lista de rótulos nonconfigurable; o padrão é []

O conjunto mínimo de constraint_values que a plataforma de destino precisa especificar para corresponder a este config_setting. (A plataforma de execução não é considerados aqui. Quaisquer valores de restrição adicionais que a plataforma tenha são ignorados. Consulte Atributos de build configuráveis para detalhes.

Se duas config_settings corresponderem ao mesmo select e uma tiver todas as mesmas flags e constraint_settings das outras, além das outras, aquele com mais configurações é escolhido. Isso é conhecido como "especialização". Por exemplo: um config_setting correspondente a x86 e Linux é especializado um config_setting correspondente a x86.

Se duas config_settings forem correspondentes e ambas tiverem constraint_values não estiver presente no outro, isso será um erro.

define_values

Dicionário: String -> String; nonconfigurable; o padrão é {}

O mesmo que values, mas especificamente para a sinalização --define.

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

Isso significa que:

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

--define ainda podem aparecer em values com sintaxe de sinalização normal; e podem ser misturadas livremente com esse atributo, desde que as chaves do dicionário permaneçam diferentes.

flag_values

Dicionário: label -> String; nonconfigurable; o padrão é {}

O mesmo que values, mas para sinalizações de build definidas pelo usuário.

Este é um atributo distinto porque as sinalizações definidas pelo usuário são referenciadas como rótulos enquanto as flags integradas são referenciadas como strings arbitrárias.

values

Dicionário: String -> String; nonconfigurable; o padrão é {}

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

Essa regra herda a configuração do destino configurado que faz referência a ele em uma instrução select. Considera-se "corresponder" uma invocação do Bazel se, para cada entrada no dicionário, for corresponde 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 pelo destino.

Por conveniência, os valores de configuração são especificados como flags de compilação (sem o "--" anterior). Mas não se esqueça de que os dois não são a mesma coisa. Isso porque os destinos podem ser criados em várias configurações no mesmo ser construído. Por exemplo, a "cpu" de uma configuração exec corresponde ao valor de --host_cpu, e não --cpu. Portanto, instâncias diferentes O mesmo config_setting pode corresponder à mesma invocação de maneira diferente dependendo da configuração da regra que os utiliza.

Se um sinalizador não for definido explicitamente na linha de comando, o valor padrão será usado. Se uma chave aparecer várias vezes no dicionário, somente a última instância será usada. Se uma chave fizer referência a uma sinalização que pode ser definida várias vezes na linha de comando (por exemplo, bazel build --copt=foo --copt=bar --copt=baz ...), a correspondência será feita se qualquer uma dessas configurações corresponder.

grupo de arquivos

Conferir origem da regra
filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)

Usar filegroup para reunir as saídas de um conjunto de destinos em uma única rótulo.

filegroup não substitui a listagem de destinos na linha de comando ou em um atributo de outra regra, porque os destinos têm muitas propriedades e saídas, que não são coletadas da mesma forma. No entanto, ele ainda é útil em em alguns casos, por exemplo, no atributo srcs de uma regra geral ou o atributo data de uma regra *_binária.

É 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",
        "//a/library:target",
        "//a/binary:target",
    ],
)

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

Atributos
name

Nome; obrigatório

Um nome exclusivo para o destino.

srcs

Lista de rótulos o padrão é []

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

Lista de rótulos o padrão é []

A lista de arquivos necessários para esta regra no tempo de execução.

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

output_group

String; o padrão é ""

O grupo de saída a partir do qual os artefatos das origens serão coletados. Se este 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, especificada na a implementação dessa regra.

genquery

Conferir origem da regra
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)

genquery() executa uma consulta especificada no Linguagem de consulta Bazel 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). O 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 lexicograficamente para impor a saída determinista, exceto --output=graph|minrank|maxrank ou quando somepath é usada como função de nível superior.

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

Atributos
name

Nome; obrigatório

Um nome exclusivo para o destino.

compressed_output

Booleano; o padrão é False

Se for True, a saída da consulta será gravada no formato de arquivo GZIP. Esta configuração pode ser usada para evitar picos no uso de memória do Bazel quando se espera que a saída da consulta seja grande. Júlio já compacta internamente saídas de consulta superiores a 220 bytes, independentemente da o valor dessa configuração. Portanto, defini-la como True pode não reduzir pilha de memória. No entanto, isso permite que o Bazel pule a descompactação ao gravar o arquivo de saída. o que pode consumir muita memória.
expression

String; obrigatório

A consulta a ser executada. Em contraste com a linha de comando e outros locais em arquivos BUILD, aqui são resolvidos em relação ao diretório raiz do espaço de trabalho. Por exemplo, o o rótulo :b neste atributo no arquivo a/BUILD se referirá ao //:b desejado.
opts

Lista de strings o padrão é []

As opções transmitidas ao mecanismo de consulta. Eles correspondem à linha de comando opções 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. Opções não especificadas aqui terão os valores padrão, assim como na linha de comando de bazel query.
scope

Lista de rótulos obrigatório

O escopo da consulta. A consulta não tem permissão para tocar em alvos fora do perímetro desses objetivos.
strict

Booleano; o padrão é True

Se verdadeiro, os destinos cujas consultas escapam do fechamento transitivo de seus escopos não conseguirão ser construído. Se for falso, o Bazel vai imprimir um aviso e pular o caminho de consulta que levou para fora escopo enquanto conclui o restante da consulta.

genrule

Conferir origem da regra
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.

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

Observe que a genrule exige um shell para interpretar o argumento do comando. Também é fácil referenciar programas arbitrários disponíveis no PATH, mas isso facilita não hermético e pode não ser reproduzível. Se você só precisa executar uma única ferramenta, considere usar run_binary como alternativa.

Como qualquer outra ação, a ação criada pelas regras gerais não deve presumir nada sobre a diretório de trabalho. todas as garantias do Bazel é que as entradas declaradas estejam disponíveis no caminho que $(location) retorna para o rótulo. Por exemplo, se a ação for executada em um sandbox ou remotamente, a implementação do sandbox ou a execução remota determinará de trabalho atual. Se executado diretamente (usando a estratégia standalone), o modelo diretório será a raiz de execução, isto é, o resultado de bazel info execution_root.

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 "exec" (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 "exec" 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 exec, 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 Exec-exec: em alguns casos, o sistema de build 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 exec, porque é nela que o compilador será executado na outra regra gen. Nesse caso, o sistema de build faz a coisa certa automaticamente: ele cria a srcs e outs da primeira genrule para a configuração "exec" 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

Atributos
name

Nome; obrigatório

Um nome exclusivo para o destino.


É possível se referir a esta regra pelo nome no Seção srcs ou deps de outro BUILD regras de firewall. Se a regra gerar arquivos de origem, use a função srcs.
srcs

Lista de rótulos o padrão é []

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

Esse atributo não é adequado para listar ferramentas executadas pelo cmd. usam o atributo tools para eles.

O sistema de build garante que esses pré-requisitos sejam criados antes de executar a genrule comando eles são criados com a mesma configuração da solicitação de build original. O os nomes dos arquivos desses pré-requisitos estão disponíveis para o comando como lista separada por espaços em $(SRCS) ou o caminho de uma pessoa O destino //x:y do srcs pode ser encontrado usando $(location //x:y) ou $<, desde que seja a única entrada srcs.

outs

Lista de nomes de arquivos nonconfigurable; obrigatório

Uma lista de arquivos gerados por esta regra.

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

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

Espera-se que o comando genrule crie cada arquivo de saída em um local predeterminado. O local está disponível no cmd usando marcas específicas de genrule variáveis ($@, $(OUTS), $(@D) ou $(RULEDIR)) ou com $(location).

cmd

String; o padrão é ""

Comando a ser executado. Sujeito a $(location) e "Marca" variável.
  1. A primeira substituição $(location) é aplicada, substituindo todas as ocorrências de $(location label) e $(locations label) (e similares construções usando variáveis relacionadas execpath, execpaths, rootpath e rootpaths).
  2. A seguir, "Fazer" variáveis são expandidas. Observe que variáveis predefinidas $(JAVA), $(JAVAC) e $(JAVABASE) se expandem na configuração exec, então as invocações do Java executados como parte de uma etapa de versão podem carregar corretamente bibliotecas compartilhadas e outros 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.
Este é o substituto 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 (64 mil no Linux/macOS, 8 mil no Windows), então o genrule vai gravar o comando em um script e executar esse script para contorná-lo. Isso se aplica a todos os atributos cmd (cmd, cmd_bash, cmd_ps, cmd_bat).

cmd_bash

String; o padrão é ""

O comando Bash a ser executado.

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

cmd_bat

String; o padrão é ""

O comando Batch a ser executado no Windows.

Esse atributo tem prioridade mais alta do que cmd e cmd_bash. O comando é executado de forma semelhante ao atributo cmd, com o as seguintes diferenças:

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

String; o padrão é ""

O comando do PowerShell a ser executado no Windows.

Este atributo tem prioridade mais alta que cmd, cmd_bash e cmd_bat O comando é executado de forma semelhante à cmd. com as seguintes diferenças:

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

Para tornar o PowerShell mais fácil de usar e menos propenso a erros, executamos o comando a seguir: para configurar o ambiente antes de executar o comando do PowerShell no genrule.

  • Set-ExecutionPolicy -Scope CurrentUser RemoteSigned: permitir execução scripts não assinados.
  • $errorActionPreference='Stop': caso haja vários comandos separadas por ;, a ação é encerrada imediatamente se uma CmdLet do Powershell falhar, mas isso NÃO funciona para comando externo.
  • $PSDefaultParameterValues['*:Encoding'] = 'utf8': alterar o padrão codificação de utf-16 para utf-8.
executable

Booleano; nonconfigurable; o padrão é False

Declarar a saída como executável.

Definir esta flag como "True" significa que a saída é um arquivo executável que pode ser executada run. Nesse caso, a genrule precisa produzir exatamente uma saída. Se este atributo for definido, o run tentará executar o arquivo, independentemente seu conteúdo.

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

local

Booleano; o padrão é False

Se definida como "True", essa opção força o genrule a ser executado usando a propriedade "local" o que significa que não há execução remota, sandbox e workers persistentes.

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

message

String; o padrão é ""

Uma mensagem de progresso.

Uma mensagem de progresso que será impressa enquanto essa etapa de build é executada. Por padrão, o a mensagem "Gerando output" (ou algo igualmente sem graça), mas você pode fornecer algo mais específico. Use este atributo em vez de echo ou outra impressão no comando cmd, já que isso permite que a ferramenta de build controle se essas mensagens de progresso são impressas ou não.

output_licenses

Tipo de licença o padrão é ["none"]

Consulte common attributes .
output_to_bindir

Booleano; nonconfigurable; o padrão é False

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

tools

Lista de rótulos o padrão é []

Uma lista de dependências de tool para esta regra. Veja 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 o comando exec , já que essas ferramentas são executadas como parte do build. O caminho de uma //x:yo objetivo de tools individual pode ser encontrado usando $(location //x:y)

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

starlark_doc_extract

Conferir origem da regra
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)

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

Destinos de saída implícitos

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

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

Argumentos

Atributos
name

Nome; obrigatório

Um nome exclusivo para o destino.

deps

Lista de rótulos o padrão é []

Uma lista de destinos que envolvem os arquivos Starlark que são adicionados com load() por src. Em condições de uso normal, esses destinos devem ser bzl_library destinos, mas a regra starlark_doc_extract não impõe isso, e aceita qualquer destino que forneça arquivos Starlark no DefaultInfo.

Os arquivos Starlark unidos precisam estar na árvore de origem. O Bazel não pode load() arquivos gerados.

src

Rótulo obrigatório

Um arquivo Starlark do qual extrair a documentação.

Observe que deve ser um arquivo na árvore de origem; O Bazel não pode load() arquivos gerados pelo servidor.

render_main_repo_name

Booleano; o padrão é False

Se verdadeiro, renderiza rótulos no repositório principal na documentação emitida com um componente repo Em outras palavras, //foo:bar.bzl será emitido como @main_repo_name//foo:bar.bzl).

O nome a ser usado para o repositório principal vem de module(name = ...) no arquivo MODULE.bazel do repositório principal (se Bzlmod estiver ativado) ou de workspace(name = ...) no arquivo WORKSPACE do repositório principal.

Esse atributo precisa ser definido como False ao gerar a documentação do Arquivos do Starlark que se destinam ao uso somente no mesmo repositório e para True ao gerar a documentação para arquivos do Starlark destinados a usados de outros repositórios.

symbol_names

Lista de strings o padrão é []

Uma lista opcional de nomes qualificados de funções, regras, provedores ou aspectos exportados (ou structs em que estão aninhados) para extrair documentação. Aqui, um objeto qualificado name significa o nome sob o qual uma entidade é disponibilizada para um usuário do módulo. incluindo os structs em que a entidade está aninhada para namespace.

starlark_doc_extract emite a documentação de uma entidade somente se

  1. cada componente do nome qualificado da entidade é público (em outras palavras, o primeiro o caractere de cada componente do nome qualificado é alfabético, não "_"; e
    1. ou a lista symbol_names está vazia (que é o padrão caso), ou
    2. o nome qualificado da entidade ou o nome qualificado de um struct em que a entidade está aninhada, está na lista symbol_names.

test_suite

Conferir origem da regra
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 bazel test respeita essa classificação da organização: para uma invocação como bazel test //some/test:suite, primeiro o Bazel é usado enumera todos os destinos de teste incluídos transitivamente pelo destino //some/test:suite (nós chamar de "expansão test_suite", o Bazel vai compilar e testar 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

Atributos
name

Nome; obrigatório

Um nome exclusivo para o destino.

tags

Lista de strings nonconfigurable; o padrão é []

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

Tags que começam com "-" são consideradas tags negativas. O "-" no início não é considerado parte da tag, de modo que uma tag pacote de "-pequeno" corresponde ao termo "pequeno" tamanho. 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 "+" , que não será avaliado como parte do texto da tag. Ela apenas torna a distinção positiva e negativa mais fácil de ler.

Teste somente as regras que correspondam a todas as tags positivas e a 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 que são filtrados é ignorada. as dependências em os testes ainda precisam ser legais (por exemplo, não bloqueados por restrições de visibilidade).

A palavra-chave da tag manual é tratada de forma diferente da mostrada acima pelo "expansão do pacote teste" executada pelo comando bazel test em invocações envolvendo caractere curinga padrões de segmentação. Lá, test_suite destino foi marcado como "manual" são filtrados (e, portanto, expandido). Esse comportamento é consistente com a forma como bazel build e Em geral, bazel test lida com padrões de destino curinga. Observe que este é explicitamente diferente de como o bazel query 'tests(E)' se comporta, já que os pacotes são sempre expandida 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 (por exemplo, em todos os testes pequenos e médios), você terá que criar três elementos test_suite regras: uma para todos os testes pequenos, uma para todos os testes médios e uma para todos os testes pequenos as duas anteriores.

tests

Lista de rótulos nonconfigurable; o padrão é []

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

Qualquer *_test é aceito aqui, independentemente do idioma. Não No entanto, os destinos *_binary são aceitos, mesmo que realizem um teste. A filtragem pelo tags especificado só é feita para testes listados diretamente na esse atributo. Se esse atributo contiver test_suites, os testes dentro dele eles não serão filtrados por esse test_suite (eles são considerados como já filtraram).

Se o atributo tests não for especificado ou estiver vazio, a regra será padronizada como incluindo todas as regras de teste no arquivo BUILD atual que não estão marcadas como manual. Essas regras ainda estão sujeitas à filtragem de tag.