Comandos e opções

Informar um problemaopen_in_new Ver código-fonteopen_in_new

Esta página aborda as opções disponíveis com vários comandos do Bazel, como bazel build, bazel run e bazel test. Esta página é um complemento da lista de comandos do Bazel em Criar com o Bazel.

Sintaxe desejada

Alguns comandos, como build ou test, podem operar em uma lista de destinos. Elas usam uma sintaxe mais flexível que os rótulos, que está documentado em Como especificar destinos para a versão.

Opções

As seções a seguir descrevem as opções disponíveis durante uma versão. Quando --long é usado em um comando de ajuda, as mensagens de ajuda on-line fornecem informações resumidas sobre o significado, o tipo e o valor padrão de cada opção.

A maioria das opções só pode ser especificada uma vez. Quando especificada várias vezes, a última instância vence. As opções que podem ser especificadas várias vezes são identificadas na ajuda on-line com o texto "pode ser usado várias vezes".

Localização do pacote

--package_path

Essa opção especifica o conjunto de diretórios pesquisados para encontrar o arquivo BUILD de um determinado pacote.

O Bazel encontra os pacotes pesquisando o caminho dele. Esta é uma lista ordenada separada por dois-pontos de diretórios do Bazel, cada um sendo a raiz de uma árvore de origem parcial.

Para especificar um caminho de pacote personalizado usando a opção --package_path:

  % bazel build --package_path %workspace%:/some/other/root

Os elementos de caminho do pacote podem ser especificados em três formatos:

1. Se o primeiro caractere for /, o caminho será absoluto.
2. Se o caminho começar com %workspace%, ele será relativo ao diretório mais próximo do Bazel. Por exemplo, se o diretório de trabalho for /home/bob/clients/bob_client/bazel/foo, a string %workspace% no caminho do pacote será expandida para /home/bob/clients/bob_client/bazel.
3. Qualquer outra coisa é feita em relação ao diretório de trabalho. Geralmente, isso não é o que você quer fazer e pode se comportar de maneira inesperada se você usar o Bazel em diretórios abaixo do espaço de trabalho do Bazel. Por exemplo, se você usar o elemento . do caminho do pacote e cd no diretório /home/bob/clients/bob_client/bazel/foo, os pacotes serão resolvidos a partir do diretório /home/bob/clients/bob_client/bazel/foo.

Se você usar um caminho de pacote não padrão, especifique-o no arquivo de configuração do Bazel para facilitar.

O Bazel não exige que nenhum pacote esteja no diretório atual. Assim, você pode fazer uma versão a partir de um espaço de trabalho do Bazel vazio se todos os pacotes necessários estiverem em outro lugar no caminho do pacote.

Exemplo: criar a partir de um cliente vazio

  % mkdir -p foo/bazel
  % cd foo/bazel
  % touch WORKSPACE
  % bazel build --package_path /some/other/path //foo

--deleted_packages

Essa opção especifica uma lista separada por vírgulas de pacotes que o Bazel deve considerar excluídos e não tentar carregar de qualquer diretório no caminho do pacote. Isso pode ser usado para simular a exclusão de pacotes sem excluí-los. Essa opção pode ser passada várias vezes. Nesse caso, as listas individuais são concatenadas.

Erro ao verificar

Essas opções controlam a verificação de erros e/ou os avisos do Bazel.

--[no]check_visibility

Se esta opção for definida como falsa, as verificações de visibilidade serão rebaixadas para avisos. O valor padrão dessa opção é verdadeiro. Assim, por padrão, a verificação de visibilidade é feita.

--output_filter=regex

A opção --output_filter só exibirá avisos de compilação e compilação para destinos que correspondem à expressão regular. Se um destino não corresponder à expressão regular fornecida e sua execução for bem-sucedida, a saída e o erro padrão serão descartados.

Veja alguns valores típicos para essa opção:

`--output_filter='^//(primeiro/projeto|segundo/projeto):'`	Mostra a saída dos pacotes especificados.
`--output_filter='^//((?!(primeiro/bad_project|segundo/bad_project):).)*$'`	Não mostrar a saída dos pacotes especificados.
"--output_filter="	Mostrar tudo.
"--output_filter=DONT_MATCH_ANYTHING"	Não mostrar nada.

Sinalizadores de ferramentas

Essas opções controlam quais opções o Bazel passará para outras ferramentas.

--copt=cc-option

Essa opção usa um argumento que deve ser transmitido para o compilador. O argumento será transmitido ao compilador sempre que for invocado para pré-processamento, compilação e/ou montagem do código C, C++ ou assembler. Ele não será transmitido durante a vinculação.

Essa opção pode ser usada várias vezes. Por exemplo:

  % bazel build --copt="-g0" --copt="-fpic" //foo

compilará a biblioteca foo sem tabelas de depuração, gerando um código independente de posição.

--host_copt=cc-option

Essa opção usa um argumento que deve ser transmitido ao compilador para arquivos de origem compilados na configuração exec. Isso é análogo à opção --copt, mas aplica-se apenas à configuração de execução.

--host_conlyopt=cc-option

Essa opção usa um argumento que deve ser transmitido ao compilador para arquivos de origem C compilados na configuração exec. Isso é análogo à opção --conlyopt, mas aplica-se apenas à configuração exec.

--host_cxxopt=cc-option

Essa opção usa um argumento que deve ser transmitido ao compilador para arquivos de origem C++ compilados na configuração exec. Isso é análogo à opção --cxxopt, mas aplica-se apenas à configuração de execução.

--host_linkopt=linker-option

Essa opção usa um argumento que deve ser transmitido ao vinculador para arquivos de origem compilados na configuração exec. Isso é análogo à opção --linkopt, mas aplica-se apenas à configuração exec.

--conlyopt=cc-option

Essa opção usa um argumento que deve ser transmitido para o compilador ao compilar arquivos de origem C.

Isso é semelhante a --copt, mas se aplica somente à compilação em C, não à compilação ou vinculação em C++. Então, você pode transmitir opções específicas de C (como -Wno-pointer-sign) usando --conlyopt.

--cxxopt=cc-option

Essa opção usa um argumento que precisa ser transmitido para o compilador ao compilar arquivos de origem C++.

Isso é semelhante a --copt, mas se aplica somente à compilação em C++, não à compilação ou vinculação em C. Então, você pode transmitir opções específicas de C++ (como -fpermissive ou -fno-implicit-templates) usando --cxxopt.

Por exemplo:

  % bazel build --cxxopt="-fpermissive" --cxxopt="-Wno-error" //foo/cruddy_code

--linkopt=linker-option

Essa opção usa um argumento que deve ser passado para o compilador durante a vinculação.

Ele é semelhante a --copt, mas se aplica somente à vinculação, e não à compilação. Então, você pode transmitir opções do compilador que só fazem sentido no momento do link (como -lssp ou -Wl,--wrap,abort) usando --linkopt. Por exemplo:

  % bazel build --copt="-fmudflap" --linkopt="-lmudflap" //foo/buggy_code

As regras de criação também podem especificar opções de link nos atributos. As configurações dessa opção sempre têm precedência. Consulte também cc_library.linkopts.

--strip (always|never|sometimes)

Essa opção determina se o Bazel removerá as informações de depuração de todos os binários e bibliotecas compartilhadas, invocando o vinculador com a opção -Wl,--strip-debug. --strip=always significa sempre remover informações de depuração. --strip=never significa nunca remover informações de depuração. O valor padrão de --strip=sometimes significa retirar se --compilation_mode for fastbuild.

  % bazel build --strip=always //foo:bar

compilará o destino enquanto retira as informações de depuração de todos os binários gerados.

A opção --strip do Bazel corresponde à opção --strip-debug do ld: apenas as informações de depuração são removidas. Se, por algum motivo, você quiser remover todos os símbolos, e não apenas os símbolos debug, use a opção --strip-all do ld, transmitindo --linkopt=-Wl,--strip-all para o Bazel. Esteja ciente também de que definir a sinalização --strip do Bazel substituirá --linkopt=-Wl,--strip-all. Portanto, defina apenas uma ou outra.

Se você estiver criando apenas um binário e quiser que todos os símbolos sejam removidos, também é possível transmitir --stripopt=--strip-all e criar explicitamente a versão //foo:bar.stripped do destino. Conforme descrito na seção em --stripopt, isso aplica uma ação de remoção após o binário final ser vinculado em vez de incluir a remoção em todas as ações de link do build.

--stripopt=strip-option

Essa é uma opção adicional para transmitir ao comando strip ao gerar um binário *.stripped. O padrão é -S -p. Essa opção pode ser usada várias vezes.

--fdo_instrument=profile-output-dir

A opção --fdo_instrument permite a geração de saída de perfil FDO (otimização orientada a feedback) quando o binário C/C++ criado é executado. Para o GCC, o argumento fornecido é usado como prefixo de diretório para uma árvore de diretórios por arquivo de arquivos .gcda, contendo informações de perfil para cada arquivo .o.

Depois que a árvore de dados do perfil é gerada, ela precisa ser compactada e fornecida à opção --fdo_optimize=profile-zip do Bazel para ativar a compilação otimizada para FDO.

Para o compilador LLVM, o argumento também é o diretório em que os arquivos de dados brutos do perfil do LLVM são despejados. Por exemplo: --fdo_instrument=/path/to/rawprof/dir/.

As opções --fdo_instrument e --fdo_optimize não podem ser usadas ao mesmo tempo.

--fdo_optimize=profile-zip

A opção --fdo_optimize permite o uso das informações de perfil de arquivo por objeto para realizar otimizações de FDO (otimização direcionada a feedback) ao compilar. Para o GCC, o argumento fornecido é o arquivo ZIP que contém a árvore de arquivos .gcda gerada anteriormente contendo informações de perfil para cada arquivo .o.

Como alternativa, o argumento fornecido pode apontar para um perfil automático identificado pela extensão .afdo.

Para o compilador LLVM, o argumento fornecido deve apontar para o arquivo de saída do perfil LLVM indexado preparado pela ferramenta llvm-profdata e ter uma extensão .profdata.

As opções --fdo_instrument e --fdo_optimize não podem ser usadas ao mesmo tempo.

--java_language_version=version

Esta opção especifica a versão das fontes Java. Por exemplo:

  % bazel build --java_language_version=8 java/com/example/common/foo:all

compila e permite apenas construções compatíveis com a especificação Java 8. O valor padrão é 11. --> Os valores possíveis são: 8, 9, 10, 11, 14 e 15 e podem ser estendidos com o registro de conjuntos de ferramentas Java personalizados usando default_java_toolchain.

--tool_java_language_version=version

A versão da linguagem Java usada para criar ferramentas que são executadas durante uma compilação. O valor padrão é 11.

--java_runtime_version=version

Essa opção especifica a versão do JVM a ser usada para executar o código e os testes. Exemplo:

  % bazel run --java_runtime_version=remotejdk_11 java/com/example/common/foo:java_application

faz o download do JDK 11 de um repositório remoto e executa o aplicativo Java usando-o.

O valor padrão é local_jdk. Os valores possíveis são: local_jdk, local_jdk_version, remotejdk_11 e remotejdk_17. É possível estender os valores registrando uma JVM personalizada usando as regras de repositório local_java_repository ou remote_java_repository.

--tool_java_runtime_version=version

A versão da JVM usada para executar ferramentas necessárias durante uma compilação. O valor padrão é remotejdk_11.

--jvmopt=jvm-option

Essa opção permite que argumentos de opção sejam passados para a VM Java. Ele pode ser usado com um argumento grande ou várias vezes com argumentos individuais. Por exemplo:

  % bazel build --jvmopt="-server -Xms256m" java/com/example/common/foo:all

usará a VM do servidor para iniciar todos os binários do Java e definirá o tamanho de heap da inicialização para a VM como 256 MB.

--javacopt=javac-option

Esta opção permite que argumentos de opção sejam passados para javac. Ele pode ser usado com um argumento grande ou várias vezes com argumentos individuais. Por exemplo:

  % bazel build --javacopt="-g:source,lines" //myprojects:prog

recriará um java_binary com as informações de depuração padrão do javac (em vez do padrão bazel).

A opção é passada para javac depois das opções padrão integradas do Bazel para javac e antes das opções por regra. A última especificação de qualquer opção para javac ganha. As opções padrão para javac são:

  -source 8 -target 8 -encoding UTF-8

--strict_java_deps (default|strict|off|warn|error)

Esta opção controla se o javac verifica se há dependências diretas ausentes. Os destinos Java precisam declarar explicitamente todos os destinos usados diretamente como dependências. Essa sinalização instrui o javac a determinar os jars realmente usados para verificar o tipo de cada arquivo java e avisa/erro se eles não forem a saída de uma dependência direta do destino atual.

• off significa que a verificação está desativada.
• warn significa que javac gerará avisos Java padrão do tipo [strict] para cada dependência direta ausente.
• default, strict e error significam que javac gerará erros em vez de avisos, fazendo com que o destino atual não seja criado se alguma dependência direta ausente for encontrada. Esse também é o comportamento padrão quando a sinalização não é especificada.

Semântica da versão

Essas opções afetam os comandos de compilação e/ou o conteúdo do arquivo de saída.

--compilation_mode (fastbuild|opt|dbg) (-c)

A opção --compilation_mode, geralmente abreviada para -c, especialmente -c opt, usa um argumento de fastbuild, dbg ou opt e afeta várias opções de geração de código C/C++, como o nível de otimização e a integridade das tabelas de depuração. O Bazel usa um diretório de saída diferente para cada modo de compilação diferente. Assim, você pode alternar entre os modos sem precisar fazer uma recriação completa todas as vezes.

• fastbuild significa criar o mais rápido possível: gerar informações mínimas de depuração (-gmlt -Wl,-S) e não otimizar. Esse é o padrão. Observação: -DNDEBUG não será definido.
• dbg significa criar com a depuração ativada (-g) para que você possa usar gdb (ou outro depurador).
• opt significa criar com a otimização ativada e com chamadas assert() desativadas (-O2 -DNDEBUG). As informações de depuração não serão geradas no modo opt, a menos que você também transmita --copt -g.

--cpu=cpu

Essa opção especifica a arquitetura de CPU de destino a ser usada para a compilação de binários durante a criação.

--action_env=VAR=VALUE

Especifica o conjunto de variáveis de ambiente disponíveis durante a execução de todas as ações. As variáveis podem ser especificadas por nome, caso em que o valor será obtido do ambiente de invocação ou pelo par name=value, que define o valor independentemente do ambiente de invocação.

Essa sinalização --action_env pode ser especificada várias vezes. Se um valor for atribuído à mesma variável em várias sinalizações --action_env, a atribuição mais recente vencerá.

--experimental_action_listener=label

A opção experimental_action_listener instrui o Bazel a usar detalhes da regra action_listener especificada por label para inserir extra_actions no gráfico de build.

--[no]experimental_extra_action_top_level_only

Se essa opção for definida como verdadeira, as ações extras especificadas pela opção de linha de comando --experimental_action_listener serão programadas somente para destinos de nível superior.

--experimental_extra_action_filter=regex

A opção experimental_extra_action_filter instrui o Bazel a filtrar o conjunto de destinos para programar extra_actions.

Essa sinalização só é aplicável em combinação com a sinalização --experimental_action_listener.

Por padrão, todos os extra_actions no fechamento transitivo dos destinos de criação solicitados são programados para execução. --experimental_extra_action_filter restringirá a programação a extra_actions do qual o rótulo do proprietário corresponde à expressão regular especificada.

O exemplo a seguir limitará a programação de extra_actions para ser aplicado apenas a ações em que o rótulo do proprietário contém "/bar/":

% bazel build --experimental_action_listener=//test:al //foo/... \
  --experimental_extra_action_filter=.*/bar/.*

--host_cpu=cpu

Essa opção especifica o nome da arquitetura de CPU que será usada para criar ferramentas de host.

--fat_apk_cpu=cpu[,cpu]*

As CPUs para criar bibliotecas C/C++ no deps transitivo das regras android_binary. Outras regras C/C++ não são afetadas. Por exemplo, se uma cc_library aparecer no deps transitivo de uma regra android_binary e uma cc_binary, a cc_library será criada pelo menos duas vezes: uma para cada CPU especificada com --fat_apk_cpu para a regra android_binary e outra para a CPU especificada com --cpu para a regra cc_binary.

O padrão é armeabi-v7a.

Um arquivo .so é criado e empacotado no APK para cada CPU especificada com --fat_apk_cpu. O nome do arquivo .so prefixa o nome da regra android_binary com "lib". Por exemplo, se o nome de android_binary for "foo", o arquivo será libfoo.so.

--per_file_copt=[+-]regex[,[+-]regex]...@option[,option]...

Quando presente, qualquer arquivo C++ com um rótulo ou um caminho de execução correspondente a uma das expressões de inclusão de regex que não corresponda a nenhuma das expressões de exclusão será criado com as opções oferecidas. A correspondência de rótulo usa a forma canônica do rótulo (por exemplo, //package:label_name).

O caminho de execução é o caminho relativo para seu diretório de espaço de trabalho, incluindo o nome base (incluindo a extensão) do arquivo C++. Também inclui prefixos dependentes da plataforma.

Para corresponder aos arquivos gerados (como saídas de regra geral), o Bazel só pode usar o caminho de execução. Nesse caso, a regexp não deve começar com '//', já que isso não corresponde a nenhum caminho de execução. Os nomes de pacotes podem ser usados da seguinte maneira: --per_file_copt=base/.*\.pb\.cc@-g0. Isso corresponderá a todos os arquivos .pb.cc em um diretório chamado base.

Essa opção pode ser usada várias vezes.

A opção é aplicada independentemente do modo de compilação usado. Por exemplo, é possível compilar com --compilation_mode=opt e compilar seletivamente alguns arquivos com a otimização mais forte ativada ou com a otimização desativada.

Advertência: se alguns arquivos forem compilados seletivamente com símbolos de depuração, os símbolos poderão ser removidos durante a vinculação. Para evitar isso, defina --strip=never.

Sintaxe: [+-]regex[,[+-]regex]...@option[,option]..., em que regex representa uma expressão regular que pode ser prefixada com um + para identificar padrões de inclusão e com - para identificar padrões de exclusão. option significa uma opção arbitrária que é transmitida para o compilador C++. Se uma opção contiver um ,, ela precisará ser citada assim: \,. As opções também podem conter @, já que apenas o primeiro @ é usado para separar expressões regulares das opções.

Exemplo: --per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-O0,-fprofile-arcs adiciona as opções -O0 e -fprofile-arcs à linha de comando do compilador C++ para todos os arquivos .cc em //foo/, exceto file.cc.

--dynamic_mode=mode

Determina se os binários C++ serão vinculados dinamicamente, interagindo com o atributo linkstatic nas regras de build.

Modos:

• auto: traduz para um modo dependente da plataforma. default para linux e off para cygwin.
• default: permite que o Bazel escolha se quer vincular dinamicamente. Consulte linkstatic para mais informações.
• fully: vincula todos os destinos dinamicamente. Isso acelera o tempo de vinculação e reduz o tamanho dos binários resultantes.
• off: vincula todos os destinos no modo principalmente estático. Se -static for definido em linkopts, os destinos mudarão para totalmente estáticos.

--fission (yes|no|[dbg][,opt][,fastbuild])

Ativa a Fission, que grava informações de depuração de C++ em arquivos .dwo dedicados, em vez de arquivos .o, para onde isso seria. Isso reduz substancialmente o tamanho da entrada para links e pode reduzir os tempos de link.

Quando definido como [dbg][,opt][,fastbuild] (exemplo: --fission=dbg,fastbuild), a Fission é ativada apenas para o conjunto especificado de modos de compilação. Isso é útil para configurações do Bazelrc. Quando definido como yes, a Fission é ativada universalmente. Quando definido como no, a Fission é desativada universalmente. O padrão é no.

--force_ignore_dash_static

Se essa sinalização for definida, todas as opções -static nos links predefinidos dos arquivos BUILD de regras cc_* serão ignoradas. Isso é apenas uma solução alternativa para builds de aumento da proteção de C++.

--[no]force_pic

Se ativado, todas as compilações C++ produzem código independente de posição ("-fPIC"), os links preferem bibliotecas pré-criadas PIC em vez de bibliotecas não-PIC, e links produzem executáveis independentes de posição ("-pie"). O padrão é desativado.

--android_resource_shrinking

Seleciona se a redução de recursos para regras android_binary deve ser executada. Define o padrão para o atributo shrink_resources em regras android_binary. Consulte a documentação dessa regra para mais detalhes. O padrão é "desativado".

--custom_malloc=malloc-library-target

Quando especificada, sempre usa a implementação de malloc especificada, substituindo todos os atributos malloc="target", inclusive nos destinos que usam o padrão (sem especificar malloc).

--crosstool_top=label

Essa opção especifica a localização do conjunto de compiladores crosstool a ser usado para toda a compilação em C++ durante uma compilação. O Bazel procurará nesse local um arquivo CROSSTOOL e o usará para determinar automaticamente as configurações de --compiler.

--host_crosstool_top=label

Se não for especificado, o Bazel usará o valor de --crosstool_top para compilar o código na configuração exec, como ferramentas executadas durante a versão. O objetivo principal dessa sinalização é ativar a compilação cruzada.

--apple_crosstool_top=label

A ferramenta cruzada a ser usada para compilar regras C/C++ na deps transitiva das regras ojc*, ios* e apple*. Para esses destinos, essa sinalização substitui --crosstool_top.

--android_crosstool_top=label

A ferramenta cruzada a ser usada para compilar regras C/C++ no deps transitivo de regras android_binary. Isso é útil se outros destinos na versão exigirem uma ferramenta cruzada diferente. O padrão é usar a ferramenta cruzada gerada pela regra android_ndk_repository no arquivo WORKSPACE. Consulte também --fat_apk_cpu.

--compiler=version

Essa opção especifica a versão do compilador C/C++ (como gcc-4.1.0) a ser usada para a compilação de binários durante a criação. Se você quiser criar com uma ferramenta cruzada personalizada, use um arquivo CROSSTOOL em vez de especificar essa sinalização.

--android_sdk=label

Essa opção especifica o conjunto de ferramentas do SDK/plataforma Android e a biblioteca de ambiente de execução do Android que serão usados para criar qualquer regra relacionada ao Android.

O SDK do Android será selecionado automaticamente se uma regra android_sdk_repository for definida no arquivo WORKSPACE.

--java_toolchain=label

Essa opção especifica o rótulo do java_toolchain usado para compilar arquivos de origem Java.

--host_java_toolchain=label

Se não for especificado, o Bazel usará o valor de --java_toolchain para compilar o código na configuração exec, como para ferramentas executadas durante a versão. O objetivo principal dessa sinalização é ativar a compilação cruzada.

--javabase=(label)

Essa opção define o rótulo da instalação Java base a ser usada no bazel run, no bazel test e nos binários Java criados pelas regras java_binary e java_test. As variáveis"Make" JAVABASE e JAVA são derivadas dessa opção.

--host_javabase=label

Essa opção define o rótulo da instalação Java de base para usar na configuração do exec, por exemplo, para ferramentas de criação de host, incluindo JavaBuilder e Singlejar.

Isso não seleciona o compilador Java usado para compilar arquivos de origem Java. O compilador pode ser selecionado ao definir a opção --java_toolchain.

Estratégia de execução

Essas opções afetam como o Bazel executará a versão. Eles não devem ter nenhum efeito significativo sobre os arquivos de saída gerados pelo build. Normalmente, o principal efeito deles está na velocidade da versão.

--spawn_strategy=strategy

Essa opção controla onde e como os comandos são executados.

• standalone faz com que os comandos sejam executados como subprocessos locais. Esse valor está obsoleto. Em vez disso, use local
• sandboxed faz com que os comandos sejam executados dentro de um sandbox na máquina local. Isso exige que todos os arquivos de entrada, dependências de dados e ferramentas sejam listados como dependências diretas nos atributos srcs, data e tools. O Bazel ativa o sandbox local por padrão em sistemas compatíveis com a execução no sandbox.
• local faz com que os comandos sejam executados como subprocessos locais.
• worker faz com que os comandos sejam executados usando um worker permanente, se disponível.
• docker faz com que os comandos sejam executados dentro de um sandbox do Docker na máquina local. Isso requer a instalação do docker.
• remote faz com que os comandos sejam executados remotamente. Isso só está disponível se um executor remoto tiver sido configurado separadamente.

--strategy mnemonic=strategy

Esta opção controla onde e como os comandos são executados, modificando --spawn_strategy (e --genrule_strategy por mnemônica Genrule) em uma base mnemônica. Consulte --spawn_strategy para ver as estratégias compatíveis e os efeitos delas.

--strategy_regexp=<filter,filter,...>=<strategy>

Essa opção especifica qual estratégia precisa ser usada para executar comandos com descrições correspondentes a uma determinada regex_filter. Consulte --per_file_copt para detalhes sobre a correspondência de regex_filter. Consulte --spawn_strategy para ver as estratégias compatíveis e os efeitos delas.

O último regex_filter que corresponde à descrição é usado. Essa opção substitui outras sinalizações para especificar a estratégia.

• Exemplo: --strategy_regexp=//foo.*\\.cc,-//foo/bar=local significa executar ações usando a estratégia local se as descrições corresponderem a //foo.*.cc, mas não a //foo/bar.
• Exemplo: --strategy_regexp='Compiling.*/bar=local' --strategy_regexp=Compiling=sandboxed executa "Compilação de //foo/bar/baz" com a estratégia sandboxed, mas reverter a ordem o executa com local.
• Exemplo: --strategy_regexp='Compiling.*/bar=local,sandboxed' executa "Compilação de //foo/bar/baz" com a estratégia local e retorna para sandboxed em caso de falha.

--genrule_strategy=strategy

Esta é uma forma abreviada de --strategy=Genrule=strategy.

--jobs=n (-j)

Essa opção, que usa um argumento de número inteiro, especifica um limite para o número de jobs que devem ser executados simultaneamente durante a fase de execução da versão.

--progress_report_interval=n

O Bazel exibe periodicamente um relatório de progresso dos jobs que ainda não foram concluídos, como testes de longa duração. Esta opção define a frequência de relatórios. O progresso será impresso a cada n segundos.

O padrão é 0, o que significa um algoritmo incremental: o primeiro relatório será impresso após 10 segundos, depois 30 segundos e, após esse progresso, será relatado uma vez por minuto.

Quando o Bazel usa o controle de cursor, conforme especificado por --curses, o progresso é relatado a cada segundo.

--local_{ram,cpu}_resources resources or resource expression

Essas opções especificam a quantidade de recursos locais (RAM em MB e número de núcleos lógicos de CPU) que o Bazel pode considerar ao programar atividades de compilação e teste para execução local. Elas usam um número inteiro ou uma palavra-chave (HOST_RAM ou HOST_CPUS) opcionalmente seguidas por [-|*float] (por exemplo, --local_cpu_resources=2, --local_ram_resources=HOST_RAM*.5, --local_cpu_resources=HOST_CPUS-1). As sinalizações são independentes. Uma ou ambas podem ser definidas. Por padrão, o Bazel estima a quantidade de RAM e o número de núcleos de CPU diretamente da configuração do sistema local.

--[no]build_runfile_links

Essa opção, que é ativada por padrão, especifica se os links simbólicos do runfiles para testes e binários precisam ser criados no diretório de saída. O uso de --nobuild_runfile_links pode ser útil para validar se todos os destinos são compilados sem incorrer na sobrecarga para criar as árvores de arquivos de execução.

Quando os testes (ou aplicativos) são executados, as dependências de dados de tempo de execução são agrupadas em um só lugar. Dentro da árvore de saída do Bazel, essa árvore "runfiles" geralmente tem acesso root como um irmão do binário ou teste correspondente. Durante a execução do teste, os arquivos de execução podem ser acessados usando caminhos no formato $TEST_SRCDIR/workspace/packagename/filename. A árvore de arquivos de execução garante que os testes tenham acesso a todos os arquivos de que eles dependem e nada mais. Por padrão, a árvore de arquivos de execução é implementada construindo um conjunto de links simbólicos para os arquivos necessários. À medida que o conjunto de links cresce, aumenta o custo dessa operação e, para alguns builds grandes, ele pode contribuir significativamente para o tempo geral de compilação, especialmente porque cada teste (ou aplicativo) individual exige a própria árvore de arquivos de execução.

--[no]build_runfile_manifests

Essa opção, que é ativada por padrão, especifica se os manifestos dos arquivos de execução precisam ser gravados na árvore de saída. Desativá-lo implica --nobuild_runfile_links.

Ele pode ser desativado ao executar testes remotamente, já que as árvores dos arquivos de execução serão criadas remotamente a partir de manifestos na memória.

--[no]discard_analysis_cache

Quando essa opção é ativada, o Bazel descarta o cache de análise pouco antes do início da execução, liberando memória extra (cerca de 10%) para a fase de execução. A desvantagem é que outras compilações incrementais serão mais lentas. Consulte também o modo de economia de memória.

--[no]keep_going (-k)

Como no GNU Make, a fase de execução de uma compilação é interrompida quando o primeiro erro é encontrado. Às vezes, é útil tentar criar o máximo possível, mesmo diante de erros. Essa opção permite esse comportamento e, quando especificada, a compilação tentará criar todos os destinos cujos pré-requisitos foram criados com sucesso, mas ignorará erros.

Essa opção geralmente está associada à fase de execução de uma versão, mas ela também afeta a fase de análise: se vários destinos forem especificados em um comando de versão, mas apenas alguns deles puderem ser analisados, a versão será interrompida com um erro, a menos que --keep_going seja especificado. Nesse caso, a versão continuará para a fase de execução, mas apenas para os destinos que foram analisados.

--[no]use_ijars

Essa opção muda a maneira como os destinos java_library são compilados pelo Bazel. Em vez de usar a saída de um java_library para compilar destinos java_library dependentes, o Bazel cria jars de interface que contêm apenas as assinaturas de membros não privados (métodos e campos de acesso públicos, protegidos e padrão (pacote)) e usa os jars de interface para compilar os destinos dependentes. Isso evita a recompilação quando alterações são feitas apenas em corpos de método ou membros particulares de uma classe.

--[no]interface_shared_objects

Essa opção ativa objetos compartilhados na interface, o que torna binários e outras bibliotecas compartilhadas dependentes da interface de um objeto compartilhado, em vez da implementação. Quando apenas a implementação é alterada, o Bazel pode evitar a recriação de destinos que dependem da biblioteca compartilhada alterada desnecessariamente.

Seleção de saída

Essas opções determinam o que compilar ou testar.

--[no]build

Essa opção faz com que a fase de execução do build ocorra. Ela fica ativada por padrão. Quando está desativada, a fase de execução é ignorada e somente as duas primeiras fases, carregamento e análise, ocorrem.

Essa opção pode ser útil para validar arquivos BUILD e detectar erros nas entradas, sem criar nada.

--[no]build_tests_only

Se especificado, o Bazel criará somente o necessário para executar as regras *_test e test_suite que não foram filtradas devido ao tamanho, tempo limite, tag ou linguagem delas. Se especificado, o Bazel ignora outros destinos especificados na linha de comando. Por padrão, essa opção está desativada e o Bazel cria tudo que é solicitado, incluindo as regras *_test e test_suite filtradas dos testes. Isso é útil porque a execução de bazel test --build_tests_only foo/... pode não detectar todas as interrupções de build na árvore foo.

--[no]check_up_to_date

Essa opção faz com que o Bazel não realize uma versão, mas apenas verifica se todos os destinos especificados estão atualizados. Em caso afirmativo, a compilação será concluída normalmente. No entanto, se algum arquivo estiver desatualizado em vez de ser criado, um erro será relatado e a versão falhará. Essa opção pode ser útil para determinar se uma versão foi realizada mais recentemente do que uma edição de origem (por exemplo, para verificações de pré-envio) sem incorrer no custo de uma versão.

Consulte também --check_tests_up_to_date.

--[no]compile_one_dependency

Compile uma única dependência dos arquivos de argumentos. Isso é útil para verificar a sintaxe dos arquivos de origem em ambientes de desenvolvimento integrado, por exemplo, ao recriar um único destino que depende do arquivo de origem para detectar erros o mais cedo possível no ciclo de edição/criação/teste. Esse argumento afeta a maneira como todos os argumentos sem sinalização são interpretados: cada argumento precisa ser um rótulo de destino de arquivo ou um nome de arquivo simples em relação ao diretório de trabalho atual, e uma regra que depende de cada nome de arquivo de origem é criada. Para fontes C++ e Java, regras são priorizadas no mesmo espaço de linguagem. Para várias regras com a mesma preferência, aquela que aparece primeiro no arquivo BUILD é escolhida. Um padrão de destino explicitamente nomeado que não referencia um arquivo de origem resulta em erro.

--save_temps

A opção --save_temps faz com que as saídas temporárias do compilador sejam salvas. Isso inclui arquivos .s (código do assembler), .i (C pré-processado) e .ii (C++ pré-processado). Essas saídas geralmente são úteis para depuração. As temperaturas só serão geradas para o conjunto de destinos especificado na linha de comando.

No momento, a sinalização --save_temps funciona apenas para regras cc_*.

Para garantir que o Bazel imprima o local dos arquivos de saída adicionais, verifique se a configuração --show_result n é alta o suficiente.

--build_tag_filters=tag[,tag]*

Se especificado, o Bazel cria apenas destinos que têm pelo menos uma tag obrigatória (se alguma delas estiver especificada) e não tem tags excluídas. O filtro de tags de criação é especificado como uma lista de palavras-chave delimitada por vírgulas e pode ser precedido pelo sinal "-" usado para denotar tags excluídas. As tags obrigatórias também podem ter um sinal de "+" antes.

Ao executar testes, o Bazel ignora --build_tag_filters para destinos de teste, que são criados e executados mesmo que não correspondam a esse filtro. Para evitar a criação, filtre os destinos de teste usando --test_tag_filters ou excluindo-os explicitamente.

--test_size_filters=size[,size]*

Se especificado, o Bazel testará (ou compilará, se --build_tests_only também for especificado) apenas os destinos com o tamanho especificado. O filtro de tamanho do teste é especificado como uma lista delimitada por vírgulas dos valores permitidos (pequeno, médio, grande ou enorme), opcionalmente precedidos pelo sinal "-" usado para indicar os tamanhos de teste excluídos. Por exemplo:

  % bazel test --test_size_filters=small,medium //foo:all

e

  % bazel test --test_size_filters=-large,-enormous //foo:all

testará apenas testes pequenos e médios dentro de //foo.

Por padrão, a filtragem de tamanho de teste não é aplicada.

--test_timeout_filters=timeout[,timeout]*

Se especificado, o Bazel testará (ou compilará, se --build_tests_only também for especificado) apenas os destinos com o tempo limite determinado. O filtro de tempo limite do teste é especificado como uma lista separada por vírgulas de valores permitidos (curto, moderado, longo ou eterno), opcionalmente opcionalmente com o sinal "-" usado para indicar os tempos limite de teste excluídos. Consulte --test_size_filters para ver um exemplo de sintaxe.

Por padrão, a filtragem de tempo limite de teste não é aplicada.

--test_tag_filters=tag[,tag]*

Se especificado, o Bazel testará (ou criará se --build_tests_only também for especificado) testará apenas os destinos que têm pelo menos uma tag obrigatória (se houver alguma) e não têm tags excluídas. O filtro da tag de teste é especificado como uma lista de palavras-chave delimitada por vírgulas, opcionalmente precedida pelo sinal "-" usado para denotar tags excluídas. As tags obrigatórias também podem ter um sinal de "+" antes.

Por exemplo:

  % bazel test --test_tag_filters=performance,stress,-flaky //myproject:all

testará os destinos marcados com a tag performance ou stress, mas não com a tag flaky.

Por padrão, a filtragem de tags de teste não é aplicada. Também é possível filtrar as tags size e local do teste dessa maneira.

--test_lang_filters=string[,string]*

Especifica uma lista de strings separadas por vírgulas que se refere a nomes de classes de regras de teste. Para fazer referência à classe de regra foo_test, use a string "foo". O Bazel testará (ou compilará, se --build_tests_only também estiver especificado) apenas os destinos das classes de regras referenciadas. Para excluí-los, use a string "-foo". Por exemplo:

  % bazel test --test_lang_filters=foo,bar //baz/...

testará apenas destinos que são instâncias de foo_test ou bar_test em //baz/..., enquanto

  % bazel test --test_lang_filters=-foo,-bar //baz/...

testará todos os destinos em //baz/..., exceto as instâncias de foo_test e bar_test.

--test_filter=filter-expression

Especifica um filtro que o executor de testes pode usar para escolher um subconjunto de testes para execução. Todos os destinos especificados na invocação são criados, mas dependendo da expressão, apenas alguns deles podem ser executados. Em alguns casos, apenas determinados métodos de teste são executados.

A interpretação específica de filter-expression depende do framework de teste responsável por executar o teste. Pode ser glob, substring ou regexp. --test_filter é uma conveniência ao passar diferentes argumentos de filtro --test_arg, mas nem todos os frameworks são compatíveis com ele.

Verbosidade

Essas opções controlam o nível de detalhamento da saída do Bazel para o terminal ou para outros arquivos de registro.

--explain=logfile

Essa opção, que requer um argumento de nome de arquivo, faz com que o verificador de dependências na fase de execução do bazel build explique, para cada etapa da criação, por que ele está sendo executado ou que ele está atualizado. A explicação está gravada em logfile.

Se você estiver encontrando recriações inesperadas, essa opção pode ajudar a entender o motivo. Adicione-o ao seu .bazelrc para que o registro ocorra em todos os builds subsequentes e inspecione o registro quando vir uma etapa de execução executada inesperadamente. Essa opção pode ter uma pequena penalidade de desempenho. Sendo assim, convém removê-la quando ela não for mais necessária.

--verbose_explanations

Essa opção aumenta o nível de detalhes das explicações geradas quando a opção --explain está ativada.

Especificamente, se as explicações detalhadas estiverem ativadas e um arquivo de saída for recriado porque o comando usado para criá-lo foi alterado, a saída no arquivo de explicação incluirá os detalhes completos do novo comando (pelo menos para a maioria dos comandos).

O uso dessa opção pode aumentar significativamente a duração do arquivo de explicação gerado e a penalidade de desempenho do uso de --explain.

Se --explain não estiver ativado, --verbose_explanations não terá efeito.

--profile=file

Essa opção, que usa um argumento de nome de arquivo, faz com que o Bazel grave dados de criação de perfil em um arquivo. Em seguida, os dados podem ser analisados ou analisados usando o comando bazel analyze-profile. O perfil de versão pode ser útil para entender onde o comando build do Bazel passa o tempo.

--[no]show_loading_progress

Essa opção faz com que o Bazel envie mensagens de progresso de carregamento de pacotes. Se ela estiver desativada, as mensagens não serão exibidas.

--[no]show_progress

Essa opção faz com que as mensagens de progresso sejam exibidas. Ela fica ativada por padrão. Quando esse recurso está desativado, as mensagens de progresso são suprimidas.

--show_progress_rate_limit=n

Essa opção faz com que o Bazel exiba no máximo uma mensagem de progresso a cada n segundos, em que n é um número real. O valor padrão dessa opção é 0,02, o que significa que o Bazel limitará as mensagens de progresso a uma por 0,02 segundo.

--show_result=n

Essa opção controla a impressão das informações de resultados no final de um comando bazel build. Por padrão, se um único destino de versão tiver sido especificado, o Bazel exibirá uma mensagem informando se o destino foi atualizado e, em caso afirmativo, a lista de arquivos de saída criados pelo destino. Se vários destinos forem especificados, as informações do resultado não serão exibidas.

As informações dos resultados podem ser úteis para builds de um único destino ou de alguns, mas para builds grandes, como uma árvore de projeto de nível superior, essas informações podem sobrecarregar e distrair. Essa opção permite que elas sejam controladas. --show_result usa um argumento de número inteiro, que é o número máximo de destinos em que as informações de resultados completos precisam ser impressas. Por padrão, o valor é 1. Acima desse limite, nenhuma informação de resultado é exibida para os destinos individuais. Assim, zero faz com que as informações do resultado sejam sempre suprimidas e um valor muito grande faz com que o resultado seja sempre impresso.

Talvez os usuários queiram escolher um valor entre eles se alternarem regularmente entre a criação de um pequeno grupo de destinos (por exemplo, durante o ciclo de edição-teste) e um grande grupo de destinos (por exemplo, ao estabelecer um novo espaço de trabalho ou executar testes de regressão). No primeiro caso, as informações do resultado são muito úteis, enquanto que, no último caso, são menos. Como acontece com todas as opções, isso pode ser especificado implicitamente por meio do arquivo .bazelrc.

Os arquivos são impressos de modo que seja mais fácil copiar e colar o nome do arquivo no shell para executar executáveis criados. As mensagens "atualizadas" ou "com falha" de cada destino podem ser facilmente analisadas por scripts que geram uma versão.

--sandbox_debug

Essa opção faz com que o Bazel imprima informações extras de depuração ao usar o sandbox para a execução da ação. Essa opção também preserva os diretórios de sandbox, para que os arquivos visíveis para ações durante a execução possam ser examinados.

--subcommands (-s)

Essa opção faz com que a fase de execução do Bazel imprima a linha de comando completa de cada comando antes de executá-lo.

  >>>>> # //examples/cpp:hello-world [action 'Linking examples/cpp/hello-world']
  (cd /home/johndoe/.cache/bazel/_bazel_johndoe/4c084335afceb392cfbe7c31afee3a9f/bazel && \
    exec env - \
    /usr/bin/gcc -o bazel-out/local-fastbuild/bin/examples/cpp/hello-world -B/usr/bin/ -Wl,-z,relro,-z,now -no-canonical-prefixes -pass-exit-codes -Wl,-S -Wl,@bazel-out/local_linux-fastbuild/bin/examples/cpp/hello-world-2.params)

Sempre que possível, os comandos são impressos em uma sintaxe compatível com o shell Bourne para serem facilmente copiados e colados em um prompt de comando do shell. Os parênteses ao redor são fornecidos para proteger seu shell das chamadas cd e exec. Copie-os. No entanto, alguns comandos são implementados internamente no Bazel, como a criação de árvores de links simbólicos. Para esses itens, não há linha de comando a ser exibida.

--subcommands=pretty_print pode ser transmitido para exibir os argumentos do comando como uma lista, e não como uma única linha. Isso pode ajudar a tornar as linhas de comando longas mais legíveis.

Veja também --verbose_failures, abaixo.

Para registrar subcomandos em um arquivo em um formato compatível com ferramentas, consulte --execution_log_json_file e --execution_log_binary_file.

--verbose_failures

Essa opção faz com que a fase de execução do Bazel imprima a linha de comando completa para os comandos que falharam. Isso pode ser inestimável para depurar uma versão com falha.

Os comandos com falha são impressos em uma sintaxe compatível com o shell Bourne, adequado para copiar e colar em um prompt do shell.

Status do espaço de trabalho

Use essas opções para "marcar" os binários criados no Bazel: para incorporar informações adicionais aos binários, como a revisão de controle de origem ou outras informações relacionadas ao espaço de trabalho. Você pode usar esse mecanismo com regras compatíveis com o atributo stamp, como genrule, cc_binary e mais.

--workspace_status_command=program

Essa sinalização permite especificar um binário que o Bazel executa antes de cada compilação. O programa pode relatar informações sobre o status do espaço de trabalho, como a revisão atual de controle de origem.

O valor da sinalização precisa ser um caminho para um programa nativo. No Linux/macOS, isso pode ser qualquer executável. No Windows, esse deve ser um binário nativo, normalmente um arquivo ".exe", ".bat" ou ".cmd".

O programa imprimirá zero ou mais pares de chave-valor na saída padrão, uma entrada em cada linha e sairá com zero. Caso contrário, a compilação falhará. Os nomes das chaves podem ser qualquer coisa, mas só podem usar letras maiúsculas e sublinhados. O primeiro espaço após o nome da chave o separa do valor. O valor é o restante da linha (incluindo espaços em branco adicionais). Nem a chave nem o valor podem abranger várias linhas. As chaves não podem ser duplicadas.

O Bazel particiona as chaves em dois buckets: "estável" e "volátil". Os nomes "estável" e "volátil" são um pouco intuitivos, então não pense muito neles.

Em seguida, o Bazel grava os pares de chave-valor em dois arquivos:

• bazel-out/stable-status.txt contém todas as chaves e valores em que o nome da chave começa com STABLE_
• bazel-out/volatile-status.txt contém o restante das chaves e os respectivos valores

O contrato é:

• Os valores das chaves "estáveis" devem mudar raramente, se possível. Se o conteúdo de bazel-out/stable-status.txt for alterado, o Bazel invalidará as ações que dependem deles. Em outras palavras, se o valor de uma chave estável for alterado, o Bazel executará novamente as ações carimbadas. Portanto, o status estável não pode conter itens como carimbos de data/hora, porque eles mudam o tempo todo e fazem com que o Bazel execute novamente ações carimbadas em cada versão.

  O Bazel sempre gera as seguintes chaves estáveis:

  • BUILD_EMBED_LABEL: valor de --embed_label
  • BUILD_HOST: o nome da máquina host em que o Bazel está sendo executado
  • BUILD_USER: o nome do usuário em que o Bazel está sendo executado

• valores de chaves "voláteis" podem mudar com frequência. O Bazel espera que eles mudem o tempo todo, como os carimbos de data/hora, e atualiza devidamente o arquivo bazel-out/volatile-status.txt. No entanto, para evitar executar novamente ações carimbadas, o Bazel finge que o arquivo volátil nunca muda. Em outras palavras, se o arquivo de status volátil for o único com conteúdo alterado, o Bazel não invalidará as ações que dependem dele. Se outras entradas das ações tiverem sido alteradas, o Bazel executará novamente essa ação, e ela verá o status volátil atualizado. No entanto, somente a alteração do status não invalidará a ação.

  O Bazel sempre gera as seguintes chaves voláteis:

  • BUILD_TIMESTAMP: tempo da criação em segundos desde a Era Unix (o valor de System.currentTimeMillis() dividido por mil).
  • FORMATTED_DATE: horário do build formatado como yyyy MMM d HH mm ss EEE(por exemplo, 2023 2 jun 01 44 29 sex) em UTC.

No Linux/macOS, é possível transmitir --workspace_status_command=/bin/true para desativar a recuperação do status do espaço de trabalho, porque true não faz nada (saia com zero) e não gera nenhuma saída. No Windows, você pode transmitir o caminho de true.exe do MSYS para o mesmo efeito.

Se o comando de status do espaço de trabalho falhar (sair diferente de zero) por qualquer motivo, a compilação falhará.

Exemplo de programa no Linux usando o Git:

#!/bin/bash
echo "CURRENT_TIME $(date +%s)"
echo "RANDOM_HASH $(cat /proc/sys/kernel/random/uuid)"
echo "STABLE_GIT_COMMIT $(git rev-parse HEAD)"
echo "STABLE_USER_NAME $USER"

Transmita o caminho desse programa com --workspace_status_command. O arquivo de status estável incluirá as linhas STABLE e o arquivo de status volátil incluirá o restante das linhas.

--[no]stamp

Essa opção, em conjunto com o atributo de regra stamp, controla se as informações de compilação serão incorporadas em binários.

O carimbo pode ser ativado ou desativado explicitamente com base no atributo stamp. Consulte a Encyclopedia de compilação para ver detalhes. Quando uma regra define stamp = -1 (o padrão para regras *_binary), essa opção determina se o carimbo está ativado.

O Bazel nunca marca os binários criados para a configuração exec, independentemente dessa opção ou do atributo stamp. Para regras que definem stamp = 0 (o padrão para regras *_test), o carimbo é desativado independentemente de --[no]stamp. Especificar --stamp não força os destinos a serem recriados se as dependências deles não tiverem sido alteradas.

Geralmente, a configuração de --nostamp é desejada para o desempenho do build, porque reduz a volatilidade da entrada e maximiza o armazenamento em cache do build.

Plataforma

Use essas opções para controlar as plataformas de host e de destino que configuram como as versões funcionam e para controlar quais plataformas de execução e conjuntos de ferramentas estão disponíveis para as regras do Bazel.

Consulte as informações contextuais sobre Plataformas e Conjuntos de ferramentas.

--platforms=labels

Os rótulos das regras de plataforma que descrevem as plataformas de destino para o comando atual.

--host_platform=label

O rótulo de uma regra de plataforma que descreve o sistema host.

--extra_execution_platforms=labels

As plataformas disponíveis como plataformas de execução para executar ações. As plataformas podem ser especificadas pelo destino exato ou como um padrão de destino. Essas plataformas serão consideradas antes daquelas declaradas no arquivo WORKSPACE por register_execution_platforms(). Essa opção aceita uma lista de plataformas separada por vírgulas em ordem de prioridade. Se a sinalização for passada várias vezes, as substituições mais recentes.

--extra_toolchains=labels

As regras do conjunto de ferramentas a serem consideradas durante a resolução do conjunto de ferramentas. Os conjuntos de ferramentas podem ser especificados por destino exato ou como padrão de destino. Esses conjuntos de ferramentas serão considerados antes daqueles declarados no arquivo WORKSPACE por register_toolchains().

--toolchain_resolution_debug=regex

Imprimir informações de depuração ao encontrar conjuntos de ferramentas, se o tipo de conjunto de ferramentas corresponder ao regex. Várias regexes podem ser separadas por vírgulas. A regex pode ser negada usando um - no início. Isso pode ajudar os desenvolvedores de regras do Bazel ou do Starlark com falhas de depuração devido à falta de conjuntos de ferramentas.

Diversos

--flag_alias=alias_name=target_path

Uma sinalização de conveniência usada para vincular configurações de versão mais longas do Starlark a um nome mais curto. Para mais detalhes, consulte as Configurações do Starlark.

--symlink_prefix=string

Altera o prefixo dos symlinks de conveniência gerados. O valor padrão para o prefixo do symlink é bazel-, que criará os links simbólicos bazel-bin, bazel-testlogs e bazel-genfiles.

Se os links simbólicos não puderem ser criados por qualquer motivo, um aviso será emitido, mas o build ainda será considerado um sucesso. Em particular, isso permite que você crie em um diretório somente leitura ou em um que você não tenha permissão para gravar. Todos os caminhos impressos em mensagens informativas após a conclusão de um build só usarão a forma abreviada relativa a symlink se os links simbólicos apontarem para o local esperado. Em outras palavras, é possível confiar na correção desses caminhos, mesmo que não seja possível confiar na criação de symlinks.

Alguns valores comuns dessa opção:

• Suprimir criação de symlinks: --symlink_prefix=/ fará com que o Bazel não crie nem atualize links simbólicos, incluindo os links simbólicos bazel-out e bazel-<workspace>. Use essa opção para suprimir a criação do symlink inteiramente.

• Reduza a sobrecarga: --symlink_prefix=.bazel/ fará com que o Bazel crie links simbólicos chamados bin (etc.) dentro de um diretório oculto .bazel.

--platform_suffix=string

Adiciona um sufixo ao nome abreviado da configuração, que é usado para determinar o diretório de saída. Definir essa opção com valores diferentes coloca os arquivos em diretórios diferentes, por exemplo, para melhorar as taxas de ocorrência em cache para compilações que clonam arquivos de saída uns dos outros ou para mantê-los para comparações.

--default_visibility=(private|public)

Sinalização temporária para testar mudanças de visibilidade padrão do Bazel. Não destinado ao uso geral, mas documentado para garantir a integridade.

--starlark_cpu_profile=_file_

Essa sinalização, cujo valor é o nome de um arquivo, faz com que o Bazel colete estatísticas sobre o uso da CPU por todas as linhas de execução do Starlark e grave o perfil, no formato pprof, no arquivo nomeado.

Use esta opção para ajudar a identificar funções do Starlark que tornam o carregamento e a análise lentos devido ao excesso de computação. Por exemplo:

$ bazel build --nobuild --starlark_cpu_profile=/tmp/pprof.gz my/project/...
$ pprof /tmp/pprof.gz
(pprof) top
Type: CPU
Time: Feb 6, 2020 at 12:06pm (PST)
Duration: 5.26s, Total samples = 3.34s (63.55%)
Showing nodes accounting for 3.34s, 100% of 3.34s total
      flat  flat%   sum%        cum   cum%
     1.86s 55.69% 55.69%      1.86s 55.69%  sort_source_files
     1.02s 30.54% 86.23%      1.02s 30.54%  expand_all_combinations
     0.44s 13.17% 99.40%      0.44s 13.17%  range
     0.02s   0.6%   100%      3.34s   100%  sorted
         0     0%   100%      1.38s 41.32%  my/project/main/BUILD
         0     0%   100%      1.96s 58.68%  my/project/library.bzl
         0     0%   100%      3.34s   100%  main

Para visualizações diferentes dos mesmos dados, use os comandos pprof svg, web e list.

Como usar o Bazel para versões

O Bazel é usado por engenheiros de software durante o ciclo de desenvolvimento e por engenheiros de lançamento ao preparar binários para implantação em produção. Nesta seção, você verá uma lista de dicas para engenheiros de lançamento que usam o Bazel.

Opções significativas

Ao usar o Bazel para compilações de lançamento, surgem os mesmos problemas que outros scripts que executam uma compilação. Para mais detalhes, consulte Chamar o Bazel de scripts. As seguintes opções são altamente recomendadas:

• --bazelrc=/dev/null
• --nokeep_state_after_build

Estas opções também são importantes:

• --package_path
• --symlink_prefix: para gerenciar versões de várias configurações, pode ser conveniente distinguir cada versão com um identificador distinto, como "64 bits" e "32 bits". Essa opção diferencia os links simbólicos bazel-bin (etc.).

Executar testes

Para criar e executar testes com o Bazel, digite bazel test seguido pelo nome dos destinos de teste.

Por padrão, esse comando executa uma atividade simultânea de criação e teste, criando todos os destinos especificados (incluindo destinos de teste não especificados na linha de comando) e destinos *_test e test_suite assim que os pré-requisitos são criados, o que significa que a execução do teste é intercalada com a criação. Isso costuma gerar ganhos de velocidade significativos.

Opções de bazel test

--cache_test_results=(yes|no|auto) (-t)

Se essa opção estiver definida como "auto" (padrão), o Bazel só executará novamente um teste se uma das seguintes condições se aplicar:

• O Bazel detecta mudanças no teste ou nas dependências
• o teste está marcado como external
• várias execuções de teste foram solicitadas com --runs_per_test
• o teste falhou.

Se for "no", todos os testes serão executados incondicionalmente.

Se for "sim", o comportamento do armazenamento em cache será o mesmo que o automático, exceto pelo fato de que ele pode armazenar em cache falhas de teste e execuções de teste com --runs_per_test.

Os usuários que ativaram essa opção por padrão no arquivo .bazelrc podem achar as abreviações -t (ativadas) ou -t- (desativadas) convenientes para substituir o padrão em uma determinada execução.

--check_tests_up_to_date

Essa opção manda o Bazel não executar os testes, mas apenas verificar e relatar os resultados armazenados. Se houver testes que não tenham sido compilados e executados anteriormente ou com resultados de testes desatualizados (por exemplo, porque o código-fonte ou as opções de compilação foram alteradas), o Bazel informará uma mensagem de erro ("o resultado do teste não está atualizado"), registrará o status do teste como "SEM STATUS" (em vermelho, se a saída de cor estiver ativada) e retornará um código de saída diferente de zero.

Essa opção também implica o comportamento [--check_up_to_date](#check-up-to-date).

Essa opção pode ser útil para verificações de pré-envio.

--test_verbose_timeout_warnings

Essa opção diz ao Bazel para avisar explicitamente o usuário se o tempo limite de um teste for significativamente maior que o tempo de execução real do teste. Embora o tempo limite de um teste deva ser instável, um teste com um tempo limite muito generoso pode ocultar problemas reais que surgem inesperadamente.

Por exemplo, um teste que normalmente é executado em um ou dois minutos não pode ter um tempo limite de ETERNAL ou LONG, pois eles são muito generosos.

Essa opção é útil para ajudar os usuários a decidir um bom valor de tempo limite ou verificar a integridade dos valores de tempo limite atuais.

--[no]test_keep_going

Por padrão, todos os testes são executados até a conclusão. No entanto, se essa sinalização estiver desativada, a versão será cancelada em qualquer teste que não seja aprovado. As etapas de versão subsequentes e as invocações de teste não são executadas, e as invocações em trânsito são canceladas. Não especifique --notest_keep_going e --keep_going.

--flaky_test_attempts=attempts

Essa opção especifica o número máximo de vezes que um teste será realizado se falhar por qualquer motivo. Um teste que inicialmente falha, mas eventualmente é bem-sucedido, é relatado como FLAKY no resumo do teste. No entanto, ela é considerada aprovada para identificar o código de saída do Bazel ou o número total de testes aprovados. Os testes que falham em todas as tentativas permitidas são considerados com falha.

Por padrão, quando essa opção não é especificada ou quando ela é definida como padrão, apenas uma tentativa é permitida para testes regulares e três para regras de teste com o atributo flaky definido. Você pode especificar um valor inteiro para substituir o limite máximo de tentativas de teste. O Bazel permite no máximo 10 tentativas de teste para impedir o abuso do sistema.

--runs_per_test=[regex@]number

Essa opção especifica o número de vezes que cada teste deve ser executado. Todas as execuções de teste são tratadas como testes separados (a funcionalidade de substituto se aplicará a cada uma delas de maneira independente).

O status de um destino com execuções com falha depende do valor da sinalização --runs_per_test_detects_flakes:

• Se ausente, qualquer execução com falha fará com que todo o teste falhe.
• Se estiver presente e duas execuções do mesmo fragmento retornarem PASS e FAIL, o teste receberá um status de instabilidade (a menos que outras execuções com falha causem falha).

Se um único número for especificado, todos os testes serão executados muitas vezes. Como alternativa, uma expressão regular pode ser especificada usando a sintaxe regex@number. Isso restringe o efeito de --runs_per_test a destinos que correspondam ao regex (--runs_per_test=^//pizza:.*@4 executa todos os testes em //pizza/ quatro vezes). Este formulário de --runs_per_test pode ser especificado mais de uma vez.

--[no]runs_per_test_detects_flakes

Se essa opção for especificada (por padrão, não), o Bazel detectará fragmentos de teste instáveis por meio de --runs_per_test. Se uma ou mais execuções de uma única falha de fragmento e uma ou mais execuções para o mesmo passe de fragmento, o destino será considerado instável com a sinalização. Se não for especificado, o destino informará um status de falha.

--test_summary=output_style

Especifica como o resumo de resultados do teste deve ser exibido.

• short imprime os resultados de cada teste com o nome do arquivo que contém a saída do teste, se ele falhar. Esse é o valor padrão.
• terse como short, mas ainda mais curto: imprima apenas informações sobre testes que não foram aprovados.
• detailed imprime cada caso de teste que falhou, não apenas cada teste. Os nomes dos arquivos de saída de teste são omitidos.
• none não imprime o resumo do teste.

--test_output=output_style

Especifica como a saída de teste deve ser exibida:

• summary mostra um resumo se cada teste foi aprovado ou reprovado. Também mostra o nome do arquivo de registro de saída para testes com falha. O resumo será impresso no final da versão. Durante a criação, você verá apenas mensagens de progresso simples quando os testes forem iniciados, aprovados ou reprovados. Esse é o comportamento padrão.
• errors envia a saída stdout/stderr combinada de testes com falha somente para a stdout imediatamente após a conclusão do teste, garantindo que a saída de teste de testes simultâneos não seja intercalada. Imprime um resumo na versão de acordo com a saída de resumo acima.
• all é semelhante a errors, mas exibe a saída de todos os testes, incluindo aqueles que foram aprovados.
• streamed transmite a saída stdout/stderr de cada teste em tempo real.

--java_debug

Essa opção faz com que a máquina virtual Java de um teste Java aguarde a conexão de um depurador compatível com JDWP antes de iniciar o teste. Essa opção implica --test_output=streamed.

--[no]verbose_test_summary

Por padrão, essa opção é ativada, fazendo com que os tempos de teste e outras informações adicionais (como tentativas de teste) sejam impressos no resumo do teste. Se --noverbose_test_summary for especificado, o resumo de teste incluirá apenas o nome, o status e o indicador de teste armazenado em cache e será formatado para permanecer dentro de 80 caracteres, quando possível.

--test_tmpdir=path

Especifica o diretório temporário para testes executados localmente. Cada teste será executado em um subdiretório separado dentro desse diretório. O diretório será limpo no início de cada comando bazel test. Por padrão, o Bazel coloca esse diretório no diretório base de saída do Bazel.

--test_timeout=seconds OU --test_timeout=seconds,seconds,seconds,seconds

Modifica o valor de tempo limite de todos os testes usando o número especificado de segundos como um novo valor de tempo limite. Se apenas um valor for fornecido, ele será usado para todas as categorias de tempo limite do teste.

Como alternativa, quatro valores separados por vírgula podem ser fornecidos, especificando tempos limite individuais para testes curtos, moderados, longos e eternos (nessa ordem). Em qualquer formato, zero ou um valor negativo para qualquer um dos tamanhos de teste serão substituídos pelo tempo limite padrão para as categorias de tempo limite especificadas, conforme definido pela página Como escrever testes. Por padrão, o Bazel usa esses tempos limite para todos os testes inferindo o limite de tempo do tamanho do teste, independentemente de o tamanho ser definido implicitamente ou explicitamente.

Os testes que declaram explicitamente a categoria de tempo limite como diferente do tamanho receberão o mesmo valor como se esse tempo limite tivesse sido definido implicitamente pela tag de tamanho. Portanto, um teste de tamanho "small" que declara um tempo limite "longo" terá o mesmo tempo limite efetivo que um teste "grande" tem sem tempo limite explícito.

--test_arg=arg

Transmite opções/sinalizações/argumentos de linha de comando para cada processo de teste. Essa opção pode ser usada várias vezes para passar vários argumentos. Por exemplo, --test_arg=--logtostderr --test_arg=--v=3.

--test_env=variable=_value_ OU --test_env=variable

Especifica outras variáveis que precisam ser injetadas no ambiente de teste para cada teste. Se value não for especificado, ele será herdado do ambiente shell usado para iniciar o comando bazel test.

O ambiente pode ser acessado a partir de um teste usando System.getenv("var") (Java), getenv("var") (C ou C++),

--run_under=command-prefix

Especifica um prefixo que o executor de teste vai inserir na frente do comando de teste antes de executá-lo. O command-prefix é dividido em palavras usando as regras de tokenização do shell Bourne e, em seguida, a lista de palavras é anexada ao comando que será executado.

Se a primeira palavra for um rótulo totalmente qualificado (começa com //), ela será criada. Em seguida, o rótulo é substituído pelo local executável correspondente anexado ao comando que será executado com as outras palavras.

Algumas advertências se aplicam:

• O PATH usado para executar testes pode ser diferente do PATH no seu ambiente. Por isso, talvez seja necessário usar um caminho absoluto para o comando --run_under (a primeira palavra em command-prefix).
• stdin não está conectado, então --run_under não pode ser usado para comandos interativos.

Exemplos:

        --run_under=/usr/bin/strace
        --run_under='/usr/bin/strace -c'
        --run_under=/usr/bin/valgrind
        --run_under='/usr/bin/valgrind --quiet --num-callers=20'

Seleção de teste

Conforme documentado em Opções de seleção de saída, é possível filtrar testes por tamanho, tempo limite, tag ou linguagem. Um filtro de nome geral prático pode encaminhar argumentos de filtro específicos para o executor de teste.

Outras opções para bazel test

A sintaxe e as opções restantes são exatamente como bazel build.

Como executar executáveis

O comando bazel run é semelhante a bazel build, mas é usado para criar e executar um único destino. Esta é uma sessão típica:

  % bazel run java/myapp:myapp -- --arg1 --arg2
  Welcome to Bazel
  INFO: Loading package: java/myapp
  INFO: Loading package: foo/bar
  INFO: Loading complete.  Analyzing...
  INFO: Found 1 target...
  ...
  Target //java/myapp:myapp up-to-date:
    bazel-bin/java/myapp:myapp
  INFO: Elapsed time: 0.638s, Critical Path: 0.34s

  INFO: Running command line: bazel-bin/java/myapp:myapp --arg1 --arg2
  Hello there
  $EXEC_ROOT/java/myapp/myapp
  --arg1
  --arg2

bazel run é semelhante, mas não idêntico, para invocar diretamente o binário criado pelo Bazel. O comportamento dele é diferente dependendo se o binário a ser invocado é um teste ou não.

Quando o binário não é um teste, o diretório de trabalho atual será a árvore de arquivos de execução do binário.

Quando o binário for um teste, o diretório de trabalho atual será a raiz exec. Uma tentativa de boa-fé será feita para replicar os testes de ambiente que geralmente são executados. No entanto, a emulação não é perfeita. Os testes que têm vários fragmentos não podem ser executados dessa forma. A opção da linha de comando --test_sharding_strategy=disabled pode ser usada para contornar esse problema.

As seguintes variáveis de ambiente extras também estão disponíveis para o binário:

• BUILD_WORKSPACE_DIRECTORY: a raiz do espaço de trabalho em que a versão foi executada.
• BUILD_WORKING_DIRECTORY: o diretório de trabalho atual de onde o Bazel foi executado.

Eles podem ser usados, por exemplo, para interpretar nomes de arquivos na linha de comando de maneira fácil.

Opções de bazel run

--run_under=command-prefix

Isso tem o mesmo efeito que a opção --run_under para bazel test (veja acima), exceto que se aplica ao comando que está sendo executado por bazel run, e não aos testes executados por bazel test, e não pode ser executado sob o rótulo.

Como filtrar saídas de registro do Bazel

Ao invocar um binário com bazel run, o Bazel exibe a saída da geração de registros do próprio Bazel e do binário em invocação. Para tornar os registros menos ruidosos, suprima as saídas do próprio Bazel com as sinalizações --ui_event_filters e --noshow_progress.

Exemplo: bazel run --ui_event_filters=-info,-stdout,-stderr --noshow_progress //java/myapp:myapp

Como executar testes

O bazel run também pode executar binários de teste, o que resulta na execução do teste em uma aproximação do ambiente descrito em Como programar testes. Nenhum dos argumentos --test_* tem efeito ao executar um teste dessa maneira, exceto --test_arg .

Como limpar saídas de compilação

O comando clean

O Bazel tem um comando clean, semelhante ao do Make. Ele exclui os diretórios de saída para todas as configurações de compilação executadas por esta instância do Bazel ou toda a árvore de trabalho criada por essa instância do Bazel e redefine caches internos. Se executado sem nenhuma opção de linha de comando, o diretório de saída de todas as configurações será limpo.

Lembre-se de que cada instância do Bazel está associada a um único espaço de trabalho. Portanto, o comando clean excluirá todas as saídas de todas as versões que você fez com essa instância do Bazel nesse espaço de trabalho.

Para remover completamente toda a árvore de trabalho criada por uma instância do Bazel, especifique a opção --expunge. Quando executado com --expunge, o comando clean simplesmente remove toda a árvore base da saída que, além da saída build, contém todos os arquivos temporários criados pelo Bazel. Ele também interrompe o servidor do Bazel após a limpeza, equivalente ao comando shutdown. Por exemplo, para limpar todos os traces de disco e memória de uma instância do Bazel, especifique:

  % bazel clean --expunge

Como alternativa, é possível eliminar em segundo plano usando --expunge_async. É seguro invocar um comando do Bazel no mesmo cliente enquanto a eliminação assíncrona continua em execução.

O comando clean é fornecido principalmente como um meio de recuperar espaço em disco para espaços de trabalho que não são mais necessários. As recriações incrementais do Bazel podem não ser perfeitas. Portanto, a clean pode ser usada para recuperar um estado consistente quando surgem problemas.

O design do Bazel faz com que esses problemas sejam corrigidos e que esses bugs tenham alta prioridade para serem corrigidos. Se você encontrar um build incremental incorreto, envie um relatório do bug e reporte bugs nas ferramentas em vez de usar clean.

Como consultar o gráfico de dependência

O Bazel inclui uma linguagem de consulta para fazer perguntas sobre o gráfico de dependência usado durante a criação. A linguagem de consulta é usada por dois comandos: consulta e cquery. A principal diferença entre os dois comandos é que a consulta é executada após a fase de carregamento e a consulta é executada após a fase de análise. Essas ferramentas são uma ajuda inestimável para muitas tarefas de engenharia de software.

A linguagem de consulta baseia-se na ideia de operações algébricas sobre gráficos. Ela está documentada em detalhes

Referência de consulta do Bazel. Consulte esse documento para ver referências, exemplos e opções de linha de comando específicas da consulta.

A ferramenta de consulta aceita várias opções de linha de comando. --output seleciona o formato de saída. --[no]keep_going (desativado por padrão) faz com que a ferramenta de consulta continue a progredir em caso de erros. Esse comportamento pode ser desativado se um resultado incompleto não for aceitável em caso de erros.

A opção --[no]tool_deps, ativada por padrão, faz com que as dependências em configurações não relacionadas à segmentação sejam incluídas no gráfico de dependência em que a consulta opera.

A opção --[no]implicit_deps, ativada por padrão, faz com que dependências implícitas sejam incluídas no gráfico de dependências em que a consulta opera. Uma dependência implícita é aquela que não está explicitamente especificada no arquivo BUILD, mas adicionada pelo Bazel.

Exemplo: "Mostrar os locais das definições (em arquivos BUILD) de todas as regras necessárias para criar todos os testes na árvore PEBL."

  bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))'

Como consultar o gráfico de ação

O comando aquery permite consultar ações no gráfico da versão. Ele opera no gráfico de destino configurado pós-análise e expõe informações sobre ações, artefatos e os relacionamentos deles.

A ferramenta aceita várias opções de linha de comando. --output seleciona o formato de saída. O formato de saída padrão (text) é legível, use proto ou textproto para o formato legível por máquina. Em especial, o comando aquery é executado sobre uma compilação normal do Bazel e herda o conjunto de opções disponíveis durante uma compilação.

Ele é compatível com o mesmo conjunto de funções que também está disponível para query tradicional, mas siblings, buildfiles e tests.

Para mais detalhes, consulte a Consulta do gráfico de ações.

Diversos comandos e opções

help

O comando help fornece ajuda on-line. Por padrão, ele mostra um resumo dos comandos e tópicos de ajuda disponíveis, conforme mostrado em Como criar com o Bazel. A especificação de um argumento exibe ajuda detalhada para um tópico específico. A maioria dos tópicos são comandos do Bazel, como build ou query, mas há outros tópicos de ajuda que não correspondem a comandos.

--[no]long (-l)

Por padrão, bazel help [topic] imprime apenas um resumo das opções relevantes para um tópico. Se a opção --long for especificada, o tipo, o valor padrão e a descrição completa de cada opção também serão impressos.

shutdown

Os processos do servidor do Bazel podem ser interrompidos usando o comando shutdown. Esse comando faz com que o servidor do Bazel seja encerrado assim que se torna inativo (por exemplo, após a conclusão de todas as versões ou outros comandos que estão em andamento no momento). Para mais detalhes, consulte Implementação do cliente/servidor.

Os servidores do Bazel são interrompidos após um tempo limite de inatividade, de modo que esse comando raramente é necessário. No entanto, ele pode ser útil em scripts quando se sabe que nenhum outro build ocorrerá em um determinado espaço de trabalho.

shutdown aceita uma opção, --iff_heap_size_greater_than _n_, que requer um argumento de número inteiro (em MB). Se especificado, isso torna o encerramento condicional à quantidade de memória já consumida. Isso é útil para scripts que iniciam muitas versões, já que qualquer vazamento de memória no servidor do Bazel pode fazer com que ele falhe repetidamente em ocasiões. A reinicialização condicional encerra essa condição.

info

O comando info imprime vários valores associados à instância do servidor do Bazel ou a uma configuração de versão específica. Elas podem ser usadas por scripts que geram uma versão.

O comando info também permite um único argumento (opcional), que é o nome de uma das chaves na lista abaixo. Nesse caso, bazel info key imprimirá apenas o valor dessa chave. Isso é especialmente conveniente ao escrever o Bazel, porque evita a necessidade de canalizar o resultado por meio de sed -ne /key:/s/key://p:

Dados independentes da configuração

• release: o rótulo de versão dessa instância do Bazel ou a "versão de desenvolvimento" se esse não for um binário lançado.
• workspace é o caminho absoluto para o diretório base do espaço de trabalho.

• install_base: o caminho absoluto para o diretório de instalação usado por essa instância do Bazel para o usuário atual. O Bazel instala os executáveis necessários internamente abaixo desse diretório.

• output_base: o caminho absoluto para o diretório de saída base usado por essa instância do Bazel para a combinação atual de usuário e espaço de trabalho. O Bazel coloca todo o trabalho de rascunho e criação abaixo desse diretório.

• execution_root: o caminho absoluto para o diretório raiz de execução em output_base. Esse diretório é a raiz de todos os arquivos acessíveis aos comandos executados durante a versão e é o diretório de trabalho desses comandos. Se o diretório do espaço de trabalho for gravável, um link simbólico chamado bazel-<workspace> será colocado nesse local e apontará para esse diretório.

• output_path: o caminho absoluto para o diretório de saída abaixo da raiz de execução usada para todos os arquivos realmente gerados como resultado de comandos de criação. Se o diretório do espaço de trabalho for gravável, um link simbólico chamado bazel-out será colocado nesse local e apontará para esse diretório.

• server_pid: o ID do processo do servidor do Bazel.

• server_log: o caminho absoluto para o arquivo de registro de depuração do servidor do Bazel. Esse arquivo contém informações de depuração de todos os comandos durante o ciclo de vida do servidor do Bazel e é destinado ao consumo humano por desenvolvedores e usuários avançados do Bazel.

• command_log: o caminho absoluto para o arquivo de registros de comandos. Ele contém os streams intercalados de stdout e stderr do comando mais recente do Bazel. Observe que a execução de bazel info substituirá o conteúdo desse arquivo, já que ele se torna o comando mais recente do Bazel. No entanto, o local do arquivo de registros de comandos não será alterado, a menos que você altere a configuração das opções --output_base ou --output_user_root.

• used-heap-size, committed-heap-size, max-heap-size: informa vários parâmetros de tamanho de heap do JVM. Respectivamente: memória atualmente usada, memória atualmente garantida para ficar disponível para a JVM no sistema, alocação máxima possível.

• gc-count, gc-time: a contagem cumulativa de coletas de lixo desde o início do servidor do Bazel e o tempo gasto para executá-las. Esses valores não são redefinidos no início de cada build.

• package_path: uma lista separada por dois-pontos dos caminhos que seriam procurados por pacotes pelo Bazel. Tem o mesmo formato que o argumento da linha de comando da versão --package_path.

Exemplo: o ID do processo do servidor do Bazel.

% bazel info server_pid
1285

Dados específicos da configuração

Esses dados podem ser afetados pelas opções de configuração transmitidas para bazel info, por exemplo, --cpu, --compilation_mode etc. O comando info aceita todas as opções que controlam a análise de dependência, já que algumas delas determinam o local do diretório de saída de uma compilação, a escolha do compilador etc.

• bazel-bin, bazel-testlogs, bazel-genfiles: informa o caminho absoluto para os diretórios bazel-* em que os programas gerados pelo build estão localizados. Geralmente, embora não seja sempre o mesmo que os links simbólicos bazel-* criados no diretório do espaço de trabalho base após a criação. No entanto, se o diretório do espaço de trabalho for somente leitura, nenhum link simbólico bazel-* poderá ser criado. Os scripts que usam o valor relatado por bazel info, em vez de presumir a existência do link simbólico, serão mais robustos.
• O ambiente"Make" completo (em inglês). Se a sinalização --show_make_env for especificada, todas as variáveis no ambiente "Fazer" da configuração atual também serão exibidas (como CC, GLIBC_VERSION etc.). Essas são as variáveis acessadas usando a sintaxe $(CC) ou varref("CC") nos arquivos BUILD.

Exemplo: o compilador C++ da configuração atual. Essa é a variável $(CC) no ambiente "Make", então a sinalização --show_make_env é necessária.

  % bazel info --show_make_env -c opt COMPILATION_MODE
  opt

Exemplo: o diretório de saída bazel-bin para a configuração atual. Isso é garantido mesmo em casos em que o link simbólico bazel-bin não pode ser criado por algum motivo, como se você estivesse criando a partir de um diretório somente leitura.

% bazel info --cpu=piii bazel-bin
/var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/piii-opt/bin
% bazel info --cpu=k8 bazel-bin
/var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/k8-opt/bin

version e --version

O comando de versão imprime detalhes da versão sobre o binário do Bazel criado, incluindo a lista de alterações em que foi criado e a data. Isso é útil principalmente para determinar se você tem o Bazel mais recente ou se está relatando bugs. Veja alguns valores interessantes:

• changelist: a lista de alterações em que esta versão do Bazel foi lançada.
• label: o rótulo de versão dessa instância do Bazel ou a "versão de desenvolvimento" se esse não for um binário lançado. Muito útil para informar bugs.

bazel --version, sem outros argumentos, emitirá a mesma saída que bazel version --gnu_format, exceto sem o efeito colateral de iniciar um servidor do Bazel ou descompactar o arquivo do servidor. bazel --version pode ser executado de qualquer lugar. Não é necessário ter um diretório de espaço de trabalho.

mobile-install

O comando mobile-install instala apps em dispositivos móveis. No momento, somente dispositivos Android com ART são compatíveis.

Consulte bazel mobile-install para mais informações.

As seguintes opções são compatíveis:

--incremental

Se definido, o Bazel tentará instalar o aplicativo de forma incremental, ou seja, apenas as partes que mudaram desde a última versão. Isso não pode atualizar recursos referenciados a partir de AndroidManifest.xml, código nativo ou recursos Java (como aqueles referenciados por Class.getResource()). Se isso mudar, essa opção precisará ser omitida. Ao contrário do espírito do Bazel e devido às limitações da plataforma Android, é responsabilidade do usuário saber quando esse comando é bom o suficiente e quando uma instalação completa é necessária.

Se você estiver usando um dispositivo com o Marshmallow ou posterior, considere a sinalização --split_apks.

--split_apks

Indica se é necessário usar apks divididos para instalar e atualizar o aplicativo no dispositivo. Funciona apenas com dispositivos com o Marshmallow ou posterior. Observe que a sinalização --incremental não é necessária ao usar --split_apks.

--start_app

Inicia o app em um estado limpo após a instalação. É equivalente a --start=COLD.

--debug_app

Aguarda a conexão do depurador antes de iniciar o aplicativo em estado limpo após a instalação. É equivalente a --start=DEBUG.

--start=_start_type_

Como o app deve ser iniciado após a instalação. Os _start_type_s compatíveis são:

• NO não inicia o app. Este é o padrão.
• COLD inicia o app em um estado limpo após a instalação.
• WARM Preserva e restaura o estado do aplicativo em instalações incrementais.
• DEBUG Aguarda o depurador antes de iniciar o app em um estado limpo após a instalação.

--adb=path

Indica o binário adb a ser usado.

O padrão é usar o adb no SDK do Android especificado por --android_sdk.

--adb_arg=serial

Argumentos extras para adb. Eles vêm antes do subcomando na linha de comando e normalmente são usados para especificar em qual dispositivo instalar. Por exemplo, para selecionar o dispositivo ou emulador Android a ser usado:

% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef

invoca adb como

adb -s deadbeef install ...

--incremental_install_verbosity=number

O nível de detalhes da instalação incremental. Defina como 1 para que a geração de registros de depuração seja impressa no console.

dump

O comando dump imprime em stdout um despejo do estado interno do servidor do Bazel. Esse comando é usado principalmente para desenvolvedores do Bazel. Portanto, a saída desse comando não é especificada e está sujeita a alterações.

Por padrão, o comando apenas imprimirá a mensagem de ajuda descrevendo as opções possíveis para despejar áreas específicas do estado do Bazel. Para despejar o estado interno, pelo menos uma das opções precisa ser especificada.

As seguintes opções são compatíveis:

• --action_cache despeja o conteúdo do cache de ação.
• --packages despeja o conteúdo do cache do pacote.
• --skyframe despeja o estado do gráfico de dependência interno do Bazel.
• --rules despeja o resumo da regra para cada regra e classe de aspecto, incluindo contagens e contagens de ações. Isso inclui as regras nativas e do Starlark. Se o rastreamento de memória estiver ativado, o consumo de memória das regras também será impresso.
• --skylark_memory despeja um arquivo .gz compatível com pprof no caminho especificado. É necessário ativar o acompanhamento de memória para que isso funcione.

Rastreamento de memória

Alguns comandos dump exigem o rastreamento de memória. Para ativar esse recurso, passe as sinalizações de inicialização para o Bazel:

• --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar
• --host_jvm_args=-DRULE_MEMORY_TRACKER=1

O java-agent é verificado no Bazel em third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar. Portanto, ajuste o $BAZEL para onde você mantém seu repositório do Bazel.

Não se esqueça de passar essas opções para o Bazel em todos os comandos, senão o servidor será reiniciado.

Exemplos

    % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \
    --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
    build --nobuild <targets>

    # Dump rules
    % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \
    --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
    dump --rules

    # Dump Starlark heap and analyze it with pprof
    % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \
    --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
    dump --skylark_memory=$HOME/prof.gz
    % pprof -flame $HOME/prof.gz

analyze-profile

O comando analyze-profile analisa um perfil de trace JSON coletado anteriormente durante uma invocação do Bazel.

canonicalize-flags

O comando canonicalize-flags, que usa uma lista de opções para um comando do Bazel e retorna uma lista de opções com o mesmo efeito. A nova lista de opções é a canônica. Por exemplo, duas listas de opções com o mesmo efeito são canonizadas na mesma lista nova.

A opção --for_command pode ser usada para selecionar entre diferentes comandos. No momento, apenas build e test são compatíveis. As opções não compatíveis com o comando fornecido causam um erro.

Como exemplo:

  % bazel canonicalize-flags -- --config=any_name --test_tag_filters="-lint"
  --config=any_name
  --test_tag_filters=-lint

Opções de inicialização

As opções descritas nesta seção afetam a inicialização da máquina virtual Java usada pelo processo do servidor do Bazel e se aplicam a todos os comandos subsequentes manipulados por esse servidor. Se já houver um servidor do Bazel em execução e as opções de inicialização não forem correspondentes, ele será reiniciado.

É necessário especificar todas as opções descritas nesta seção usando a sintaxe --key=value ou --key value. Além disso, essas opções precisam aparecer antes do nome do comando do Bazel. Use startup --key=value para listá-los em um arquivo .bazelrc.

--output_base=dir

Essa opção requer um argumento de caminho, que precisa especificar um diretório gravável. O Bazel usará esse local para gravar toda a saída. A base de saída também é a chave pela qual o cliente localiza o servidor do Bazel. Ao alterar a base de saída, você altera o servidor que manipulará o comando.

Por padrão, a base de saída é derivada do nome de login do usuário e do nome do diretório do espaço de trabalho (na verdade, o resumo MD5). Portanto, um valor típico é semelhante a: /var/tmp/google/_bazel_johndoe/d41d8cd98f00b204e9800998ecf8427e.

Por exemplo:

 OUTPUT_BASE=/var/tmp/google/_bazel_johndoe/custom_output_base
% bazel --output_base ${OUTPUT_BASE}1 build //foo  &  bazel --output_base ${OUTPUT_BASE}2 build //bar

Nesse comando, os dois comandos do Bazel são executados simultaneamente (por causa do operador shell &), cada um usando uma instância diferente do servidor do Bazel (por causa das diferentes bases de saída). Por outro lado, se a base de saída padrão tiver sido usada nos dois comandos, as duas solicitações serão enviadas para o mesmo servidor, o que as processaria sequencialmente: criando //foo primeiro, seguido de um build incremental de //bar.

--output_user_root=dir

Aponta para o diretório raiz em que as bases de saída e instalação são criadas. O diretório não pode existir ou ser de propriedade do usuário que faz a chamada. Antes, isso era permitido para um diretório compartilhado entre vários usuários, mas não é mais permitido. Isso será permitido assim que o problema 11100 for resolvido.

Se a opção --output_base for especificada, ela substituirá o uso de --output_user_root para calcular a base de saída.

O local de base instalado é calculado com base em --output_user_root, além da identidade MD5 dos binários incorporados do Bazel.

É possível usar a opção --output_user_root para escolher um local de base alternativo para toda a saída do Bazel (instalar e base de saída) se houver um local melhor no layout do sistema de arquivos.

--server_javabase=dir

Especifica a máquina virtual Java em que o Bazel é executado. O valor precisa ser um caminho para o diretório que contém um JDK ou JRE. Não deve ser um marcador. Essa opção deve aparecer antes de qualquer comando do Bazel, por exemplo:

  % bazel --server_javabase=/usr/local/buildtools/java/jdk11 build //foo

Essa sinalização não afeta as JVMs usadas pelos subprocessos do Bazel, como aplicativos, testes, ferramentas e assim por diante. Use as opções de versão --javabase ou --host_javabase.

Essa sinalização era chamada anteriormente de --host_javabase (às vezes chamada de --host_javabase do lado esquerdo), mas foi renomeada para evitar confusão com a sinalização da versão --host_javabase (às vezes chamada de --host_javabase do lado direito).

--host_jvm_args=string

Especifica uma opção de inicialização a ser passada para a máquina virtual Java em que o Bazel em si é executado. Isso pode ser usado para definir o tamanho da pilha, por exemplo:

  % bazel --host_jvm_args="-Xss256K" build //foo

Essa opção pode ser usada várias vezes com argumentos individuais. Observe que a definição dessa sinalização raramente é necessária. Também é possível transmitir uma lista de strings separadas por espaços, cada uma sendo interpretada como um argumento JVM separado, mas esse recurso será descontinuado em breve.

Isso não afeta as JVMs usadas pelos subprocessos do Bazel: aplicativos, testes, ferramentas e assim por diante. Para transmitir as opções de JVM para programas Java executáveis, sejam executados por bazel run ou na linha de comando, use o argumento --jvm_flags compatível com todos os programas java_binary e java_test. Como alternativa para testes, use bazel test --test_arg=--jvm_flags=foo ....

--host_jvm_debug

Essa opção faz com que a máquina virtual Java aguarde a conexão de um depurador compatível com JDWP antes de chamar o método principal do Bazel propriamente dito. Isso se destina principalmente aos desenvolvedores do Bazel.

--autodetect_server_javabase

Essa opção faz com que o Bazel pesquise automaticamente um JDK instalado na inicialização e use o JRE instalado se o JRE incorporado não estiver disponível. --explicit_server_javabase pode ser usado para escolher um JRE explícito para executar o Bazel.

--batch

O modo de lote faz com que o Bazel não use o modo de cliente/servidor padrão, mas executa um processo Java do Bazel para um único comando, que é usado para semânticas mais previsíveis em relação ao tratamento de sinais, ao controle de jobs e à herança de variável de ambiente, e é necessário para executar o Bazel em uma prisão chroot.

O modo de lote retém a semântica de enfileiramento adequada dentro da mesma saída_base. Ou seja, invocações simultâneas serão processadas em ordem, sem sobreposição. Se um Bazel em modo de lote for executado em um cliente com um servidor em execução, ele primeiro eliminará o servidor antes de processar o comando.

O Bazel ficará mais lento no modo de lote ou com as alternativas descritas acima. Isso ocorre porque, entre outras coisas, o cache do arquivo de compilação é residente na memória e, portanto, não é preservado entre as invocações em lote sequenciais. Portanto, o uso do modo em lote geralmente faz mais sentido nos casos em que o desempenho é menos crítico, como versões contínuas.

--max_idle_secs=n

Essa opção especifica quanto tempo, em segundos, o processo do servidor do Bazel deve aguardar depois da última solicitação do cliente, antes de sair. O valor padrão é 10800 (3 horas). --max_idle_secs=0 fará com que o processo do servidor do Bazel permaneça indefinidamente.

Essa opção pode ser usada por scripts que invocam o Bazel para garantir que eles não deixem processos do servidor do Bazel na máquina de um usuário quando não seriam executados. Por exemplo, um script de pré-envio pode invocar o bazel query para garantir que a alteração pendente de um usuário não introduz dependências indesejadas. No entanto, se o usuário não tiver feito uma versão recente nesse espaço de trabalho, o aplicativo de pré-envio não poderá iniciar um servidor do Bazel apenas para permanecer inativo pelo resto do dia. Ao especificar um pequeno valor de --max_idle_secs na solicitação de consulta, o script pode garantir que, se ele causar a inicialização de um novo servidor, esse servidor será encerrado imediatamente. Se, em vez disso, já houver um servidor em execução, ele continuará em execução até ficar inativo durante o tempo normal. É claro que o temporizador ocioso do servidor existente será redefinido.

--[no]shutdown_on_low_sys_mem

Se ativado e --max_idle_secs estiver definido com uma duração positiva, após o servidor de build ficar inativo por um tempo, desligue o servidor quando o sistema estiver com pouca memória. Somente no Linux.

Além de executar uma verificação de inatividade correspondente a max_idle_secs, o servidor de criação começará a monitorar a memória do sistema disponível depois que ele ficar inativo por algum tempo. Se a memória disponível do sistema ficar criticamente baixa, o servidor será encerrado.

--[no]block_for_lock

Se ativado, o Bazel esperará que outros comandos do Bazel com o bloqueio de servidor sejam concluídos antes de progredir. Se desativado, o Bazel sairá por engano se não conseguir adquirir imediatamente o bloqueio e prosseguir.

Os desenvolvedores podem usar isso em verificações de pré-envio para evitar esperas longas causadas por outro comando do Bazel no mesmo cliente.

--io_nice_level=n

Define um nível de 0 a 7 para a programação de E/S de melhor esforço. 0 é a prioridade mais alta, 7 é a mais baixa. O programador antecipatório só pode cumprir a prioridade 4. Valores negativos são ignorados.

--batch_cpu_scheduling

Use a programação de CPU batch do Bazel. Essa política é útil para cargas de trabalho não interativas, mas que não querem diminuir esse valor. Consulte 'homem 2 sched_setscheduler'. Essa política pode fornecer melhor interatividade do sistema, prejudicando a capacidade do Bazel.

Opções diversas

--[no]announce_rc

Controla se o Bazel anuncia opções de comando lidas do arquivo bazelrc ao iniciar. As opções de inicialização são anunciadas incondicionalmente.

--color (yes|no|auto)

Essa opção determina se o Bazel usará cores para destacar a saída na tela.

Se essa opção for definida como yes, a saída de cores será ativada. Se essa opção for definida como auto, o Bazel usará a saída de cor somente se a saída estiver sendo enviada a um terminal e a variável de ambiente TERM estiver definida como um valor diferente de dumb, emacs ou xterm-mono. Se essa opção for definida como no, a saída de cor será desativada, independentemente da saída para um terminal e da configuração da variável de ambiente TERM.

--config=name

Seleciona outra seção de configuração dos arquivos rc. Para a command atual, ela também extrai as opções de command:name, se essa seção existir. Pode ser especificado várias vezes para adicionar sinalizações a partir de várias seções de configuração. As expansões podem se referir a outras definições. Por exemplo, expansões podem ser encadeadas.

--curses (yes|no|auto)

Essa opção determina se o Bazel usará controles de cursor na saída de tela. Isso resulta em menos dados de rolagem e um fluxo de saída mais compacto e fácil de ler do Bazel. Isso funciona bem com --color.

Se esta opção for definida como yes, o uso de controles de cursor será ativado. Se esta opção for definida como no, o uso dos controles do cursor será desativado. Se esta opção for definida como auto, o uso de controles de cursor será ativado nas mesmas condições que em --color=auto.

--[no]show_timestamps

Se especificado, um carimbo de data/hora é adicionado a cada mensagem gerada pelo Bazel, especificando o horário em que a mensagem foi exibida.