Comandos e opções

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 Build with Bazel.

Sintaxe de destino

Alguns comandos, como build ou test, podem operar em uma lista de destinos. Eles usam uma sintaxe mais flexível do que os rótulos, que está documentada em Especificar destinos para criar.

Opções

As seções a seguir descrevem as opções disponíveis durante um build. 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 especificado 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 deles. É 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 bazel mais próximo. 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 é relativa ao diretório de trabalho. Normalmente, não é isso que você quer fazer, e o Bazel pode se comportar de maneira inesperada se você o usar em diretórios abaixo do espaço de trabalho. Por exemplo, se você usar o elemento package-path . e depois usar o comando cd no diretório /home/bob/clients/bob_client/bazel/foo, os pacotes serão resolvidos no 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. Portanto, é possível fazer uma build em um espaço de trabalho vazio do Bazel se todos os pacotes necessários puderem ser encontrados em outro lugar no caminho do pacote.

Exemplo: criar 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 nenhum diretório no caminho do pacote. Isso pode ser usado para simular a exclusão de pacotes sem excluí-los de verdade. Essa opção pode ser transmitida várias vezes. Nesse caso, as listas individuais são concatenadas.

Verificação de erros

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

--[no]check_visibility

Se essa opção for definida como "false", as verificações de visibilidade serão rebaixadas para avisos. O valor padrão dessa opção é "true", para que a verificação de visibilidade seja feita por padrão.

--output_filter=regex

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

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

Flags de ferramentas

Essas opções controlam quais opções o Bazel vai transmitir para outras ferramentas.

--copt=cc-option

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

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

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

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

--host_copt=cc-option

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

--host_conlyopt=cc-option

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

--host_cxxopt=cc-option

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

--host_linkopt=linker-option

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

--conlyopt=cc-option

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

É semelhante a --copt, mas só se aplica à compilação em C, não em C++ ou vinculação. Assim, é possível transmitir opções específicas de C (como -Wno-pointer-sign) usando --conlyopt.

--cxxopt=cc-option

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

É semelhante a --copt, mas se aplica apenas à compilação do C++, não à compilação ou vinculação do C. Assim, é possível transmitir opções específicas do C++ (como -fpermissive ou -fno-implicit-templates) usando --cxxopt.

Exemplo:

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

--linkopt=linker-option

Essa opção usa um argumento que é transmitido ao compilador durante a vinculação.

Isso é semelhante a --copt, mas só se aplica à vinculação, não à compilação. Assim, é possível transmitir opções de compilador que só fazem sentido no momento da vinculação (como -lssp ou -Wl,--wrap,abort) usando --linkopt. Exemplo:

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

As regras de build 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 vai remover 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 remover se --compilation_mode for fastbuild.

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

compila o destino e remove 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: ela remove apenas as informações de depuração. Se, por algum motivo, você quiser remover todos os símbolos, e não apenas os de depuração, use a opção --strip-all do ld, o que pode ser feito transmitindo --linkopt=-Wl,--strip-all ao Bazel. Além disso, definir a flag --strip do Bazel vai substituir --linkopt=-Wl,--strip-all. Portanto, defina apenas uma delas.

Se você estiver criando apenas um binário e quiser remover todos os símbolos, também poderá transmitir --stripopt=--strip-all e criar explicitamente a versão //foo:bar.stripped do destino. Conforme descrito na seção sobre --stripopt, isso aplica uma ação de remoção após a vinculação do binário final, em vez de incluir a remoção em todas as ações de vinculação 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 de FDO (otimização direcionada por feedback) quando o binário C/C++ criado é executado. Para o GCC, o argumento fornecido é usado como um prefixo de diretório para uma árvore de diretórios de arquivos por objeto de arquivos .gcda que contêm informações de perfil para cada arquivo .o.

Depois que a árvore de dados do perfil for 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 de perfil LLVM brutos 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 usar as informações de perfil de cada arquivo de objeto para realizar otimizações de FDO (otimização direcionada por feedback) durante a compilação. Para o GCC, o argumento fornecido é o arquivo ZIP que contém a árvore de arquivos gerada anteriormente de arquivos .gcda com 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 precisa 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

Essa opção especifica a versão das fontes Java. 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, que podem ser estendidos com o registro de toolchains Java personalizadas usando default_java_toolchain.

--tool_java_language_version=version

A versão da linguagem Java usada para criar ferramentas executadas durante um build. O valor padrão é 11.

--java_runtime_version=version

Essa opção especifica a versão da JVM a ser usada para executar o código e os testes. Por 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 as ferramentas necessárias durante um build. O valor padrão é remotejdk_11.

--jvmopt=jvm-option

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

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

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

--javacopt=javac-option

Essa opção permite que argumentos de opção sejam transmitidos para o javac. Ele pode ser usado com um argumento grande ou várias vezes com argumentos individuais. Exemplo:

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

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

A opção é transmitida para o 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 vence. As opções padrão para javac são:

  -source 8 -target 8 -encoding UTF-8

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

Essa opção controla se o javac verifica dependências diretas ausentes. Os destinos Java precisam declarar explicitamente todos os destinos usados diretamente como dependências. Essa flag instrui o javac a determinar os jars realmente usados para verificação de tipo de cada arquivo Java e a emitir um aviso/erro se eles não forem a saída de uma dependência direta da meta atual.

• off significa que a verificação está desativada.
• warn significa que o javac vai gerar avisos padrão do Java do tipo [strict] para cada dependência direta ausente.
• default, strict e error significam que o javac vai gerar erros em vez de avisos, fazendo com que a build do destino atual falhe se dependências diretas ausentes forem encontradas. Esse também é o comportamento padrão quando a flag não é especificada.

Semântica de build

Essas opções afetam os comandos de build 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, então você pode alternar entre os modos sem precisar fazer uma reconstruçã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 o gdb (ou outro depurador).
• opt significa criar com a otimização ativada e com as 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 o build.

--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. Nesse caso, o valor será extraído do ambiente de invocação. Também é possível usar o par name=value, que define o valor independente do ambiente de invocação.

Essa flag --action_env pode ser especificada várias vezes. Se um valor for atribuído à mesma variável em várias flags --action_env, a atribuição mais recente vai prevalecer.

--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 "true", as ações extras especificadas pela opção de linha de comando --experimental_action_listener serão programadas apenas 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 flag só é aplicável em combinação com a flag --experimental_action_listener.

Por padrão, todos os extra_actions no fechamento transitivo dos destinos a serem criados solicitados são programados para execução. --experimental_extra_action_filter vai restringir o agendamento a extra_actions cujo rótulo do proprietário corresponda à expressão regular especificada.

O exemplo a seguir limita o agendamento de extra_actions para aplicar apenas às 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 da CPU que deve ser usada para criar ferramentas de host.

--android_platforms=platform[,platform]*

As plataformas para criar o deps transitivo de regras android_binary (especificamente para dependências nativas, como C++). Por exemplo, se um cc_library aparecer no deps transitivo de uma regra android_binary, ele será criado uma vez para cada plataforma especificada com --android_platforms para a regra android_binary e incluído na saída final.

Não há um valor padrão para essa flag: uma plataforma Android personalizada precisa ser definida e usada.

Um arquivo .so é criado e empacotado no APK para cada plataforma especificada com --android_platforms. O nome do arquivo .so precede o nome da regra android_binary com "lib". Por exemplo, se o nome do 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 que corresponda a uma das expressões regulares de inclusão e não corresponda a nenhuma das expressões de exclusão será criado com as opções fornecidas. A correspondência de rótulos usa a forma canônica do rótulo (ou seja, //package:label_name).

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

Para corresponder aos arquivos gerados (como saídas de genrule), o Bazel só pode usar o caminho de execução. Nesse caso, a expressão regular não pode começar com "//", já que isso não corresponde a nenhum caminho de execução. Os nomes de pacotes podem ser usados assim: --per_file_copt=base/.*\.pb\.cc@-g0. Isso vai 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 independente do modo de compilação usado. Por exemplo, é possível compilar com --compilation_mode=opt e compilar seletivamente alguns arquivos com uma otimização mais forte ativada ou desativada.

Observação: se alguns arquivos forem compilados seletivamente com símbolos de depuração, eles poderão ser removidos durante a vinculação. Isso pode ser evitado definindo --strip=never.

Sintaxe: [+-]regex[,[+-]regex]...@option[,option]... em que regex representa uma expressão regular que pode ter como prefixo um + para identificar padrões de inclusão e um - para identificar padrões de exclusão. option representa uma opção arbitrária transmitida ao 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 de 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:

• default: permite que o Bazel escolha se vai vincular dinamicamente. Consulte linkstatic para mais informações.
• fully: vincula todos os destinos de forma dinâmica. 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 estiver definido em linkopts, os destinos vão mudar para totalmente estáticos.

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

Ativa o Fission, que grava informações de depuração em C++ em arquivos .dwo dedicados em vez de arquivos .o, que seria o destino normal. Isso reduz substancialmente o tamanho da entrada para links e pode diminuir os tempos de vinculação.

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

--force_ignore_dash_static

Se essa flag estiver definida, todas as opções -static em linkopts dos arquivos BUILD das regras cc_* serão ignoradas. Isso é apenas uma solução alternativa para builds de reforço do C++.

--[no]force_pic

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

--android_resource_shrinking

Seleciona se a redução de recursos será realizada para regras android_binary. 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 especificado, sempre use a implementação de malloc fornecida, substituindo todos os atributos malloc="target", incluindo aqueles destinos que usam o padrão (não especificando nenhum malloc).

--crosstool_top=label

Essa opção especifica o local do conjunto de compiladores crosstool a ser usado em toda a compilação em C++ durante um build. O Bazel vai procurar um arquivo CROSSTOOL nesse local e usá-lo 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 código na configuração de execução, como ferramentas executadas durante o build. O objetivo principal dessa flag é ativar a compilação cruzada.

--apple_crosstool_top=label

A crosstool a ser usada para compilar regras C/C++ no deps transitivo de objc*, ios* e apple*. Para esses destinos, a flag substitui --crosstool_top.

--android_crosstool_top=label

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

--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 o build. Se você quiser criar com uma crosstool personalizada, use um arquivo CROSSTOOL em vez de especificar essa flag.

--android_sdk=label

Obsoleto. Isso não deve ser especificado diretamente.

Essa opção especifica a cadeia de ferramentas do SDK/plataforma do Android e a biblioteca de tempo de execução do Android que serão usadas 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 da java_toolchain usada 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 código na configuração de execução, como para ferramentas executadas durante o build. O objetivo principal dessa flag é ativar a compilação cruzada.

--javabase=(label)

Essa opção define o rótulo da instalação base do Java a ser usada para bazel run, bazel test e para 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 base do Java a ser usada na configuração de execução, por exemplo, para ferramentas de build do host, incluindo JavaBuilder e Singlejar.

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

Estratégia de execução

Essas opções afetam a forma como o Bazel vai executar a build. Eles não devem ter um efeito significativo nos arquivos de saída gerados pelo build. Normalmente, o principal efeito é na velocidade do build.

--spawn_strategy=strategy

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

• O standalone faz com que os comandos sejam executados como subprocessos locais. Esse valor está obsoleto. Em vez disso, use local
• O sandboxed faz com que os comandos sejam executados em 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 que oferecem suporte à execução em sandbox.
• O local faz com que os comandos sejam executados como subprocessos locais.
• O worker faz com que os comandos sejam executados usando um worker persistente, se disponível.
• O docker faz com que os comandos sejam executados em um sandbox do Docker na máquina local. Isso exige que o Docker esteja instalado.
• O 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

Essa opção controla onde e como os comandos são executados, substituindo --spawn_strategy (e --genrule_strategy com o mnemônico Genrule) por mnemônico. 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 deve ser usada para executar comandos com descrições que correspondem a um determinado regex_filter. Consulte --per_file_copt para mais 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 flags 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 "Compiling //foo/bar/baz" com a estratégia sandboxed, mas invertendo a ordem, ele é executado com local.
• Exemplo: --strategy_regexp='Compiling.*/bar=local,sandboxed' executa "Compiling //foo/bar/baz" com a estratégia local e volta para sandboxed se falhar.

--genrule_strategy=strategy

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

--jobs=n (-j)

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

--progress_report_interval=n

O Bazel imprime periodicamente um relatório de progresso sobre jobs que ainda não foram concluídos (como testes de longa duração). Essa 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 isso, o progresso será informado uma vez por minuto.

Quando o bazel usa o controle do cursor, conforme especificado por --curses, o progresso é informado 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 build e teste para execução local. Eles usam um número inteiro ou uma palavra-chave (HOST_RAM ou HOST_CPUS) seguida opcionalmente por [-|*float] (por exemplo, --local_cpu_resources=2, --local_ram_resources=HOST_RAM*.5, --local_cpu_resources=HOST_CPUS-1). As flags 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 symlinks de runfiles para testes e binários devem 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 de 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 reunidas em um só lugar. Na árvore de saída do Bazel, essa árvore de "runfiles" geralmente é enraizada como um elemento irmão do binário ou teste correspondente. Durante a execução do teste, os runfiles podem ser acessados usando caminhos do formato $TEST_SRCDIR/workspace/packagename/filename. A árvore de runfiles garante que os testes tenham acesso a todos os arquivos de que dependem e nada mais. Por padrão, a árvore de runfiles é implementada construindo um conjunto de links simbólicos para os arquivos necessários. À medida que o conjunto de links aumenta, o custo dessa operação também aumenta. Em algumas builds grandes, isso pode contribuir significativamente para o tempo total de build, principalmente porque cada teste (ou aplicativo) individual exige sua própria árvore de arquivos de execução.

--[no]build_runfile_manifests

Essa opção, que é ativada por padrão, especifica se os manifestos de runfiles devem ser gravados na árvore de saída. Desativar essa opção implica --nobuild_runfile_links.

Ele pode ser desativado ao executar testes remotamente, já que as árvores de runfiles serão criadas remotamente com base em manifestos na memória.

--[no]discard_analysis_cache

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

--[no]keep_going (-k)

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

Embora essa opção geralmente esteja associada à fase de execução de um build, ela também afeta a fase de análise: se vários destinos forem especificados em um comando de build, mas apenas alguns deles puderem ser analisados com êxito, o build será interrompido com um erro, a menos que --keep_going seja especificado. Nesse caso, o build vai para a fase de execução, mas apenas para os destinos que foram analisados com êxito.

--[no]use_ijars

Essa opção muda a forma 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 vai criar jars de interface que contêm apenas as assinaturas de membros não particulares (públicos, protegidos e métodos e campos de acesso padrão (pacote)) e usar os jars de interface para compilar os destinos dependentes. Isso permite evitar a recompilação quando as mudanças são feitas apenas em corpos de métodos ou membros particulares de uma classe.

--[no]interface_shared_objects

Essa opção ativa os objetos compartilhados de interface, o que faz com que binários e outras bibliotecas compartilhadas dependam da interface de um objeto compartilhado, em vez da implementação dele. Quando apenas a implementação muda, o Bazel pode evitar a recriação desnecessária de destinos que dependem da biblioteca compartilhada alterada.

Seleção de saída

Essas opções determinam o que será criado ou testado.

--[no]build

Essa opção faz com que a fase de execução do build ocorra. Ela fica ativada por padrão. Quando ela está desativada, a fase de execução é ignorada, e apenas 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 realmente criar nada.

--[no]build_tests_only

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

--[no]check_up_to_date

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

Consulte também --check_tests_up_to_date.

--[no]compile_one_dependency

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

--save_temps

A opção --save_temps faz com que saídas temporárias do compilador sejam salvas. Eles incluem arquivos .s (código de 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 especificados na linha de comando.

No momento, a flag --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 está alta o suficiente.

--build_tag_filters=tag[,tag]*

Se especificado, o Bazel vai criar apenas destinos que tenham pelo menos uma tag obrigatória (se alguma delas for especificada) e nenhuma tag excluída. O filtro de tag de build é especificado como uma lista separada por vírgulas de palavras-chave de tag, opcionalmente precedida pelo sinal "-", usado para indicar 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 deles, filtre os destinos de teste usando --test_tag_filters ou excluindo-os explicitamente.

--test_size_filters=size[,size]*

Se especificado, o Bazel vai testar (ou criar, se --build_tests_only também for especificado) apenas destinos de teste com o tamanho determinado. O filtro de tamanho do teste é especificado como uma lista delimitada por vírgulas de valores de tamanho de teste permitidos (pequeno, médio, grande ou enorme), precedida opcionalmente com o sinal "-", usado para indicar 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 em //foo.

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

--test_timeout_filters=timeout[,timeout]*

Se especificado, o Bazel vai testar (ou criar, se --build_tests_only também for especificado) apenas destinos de teste com o tempo limite determinado. O filtro de tempo limite do teste é especificado como uma lista separada por vírgulas de valores de tempo limite permitidos (curto, moderado, longo ou eterno), opcionalmente precedida pelo sinal "-" usado para indicar 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 vai testar (ou criar, se --build_tests_only também for especificado) apenas os destinos de teste que têm pelo menos uma tag obrigatória (se alguma delas for especificada) e não têm tags excluídas. O filtro de tags de teste é especificado como uma lista de palavras-chave de tags delimitadas por vírgulas, opcionalmente precedida pelo sinal "-", usado para indicar 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á destinos marcados com a tag performance ou stress, mas que não estão marcados 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 separada por vírgulas de strings que se referem a nomes de classes de regras de teste. Para se referir à classe de regra foo_test, use a string "foo". O Bazel vai testar (ou criar, se --build_tests_only também for especificado) apenas destinos das classes de regras referenciadas. Para excluir esses destinos, 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 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 fica a cargo do framework de teste responsável por executar o teste. Pode ser um glob, uma substring ou uma expressão regular. --test_filter é uma conveniência em relação à transmissão de diferentes argumentos de filtro --test_arg, mas nem todos os frameworks oferecem suporte a ele.

Nível de detalhes

Essas opções controlam a verbosidade da saída do Bazel, no terminal ou em arquivos de registro adicionais.

--explain=logfile

Essa opção, que exige 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 de build, por que ela está sendo executada ou que ela está atualizada. A explicação é gravada em logfile.

Se você estiver enfrentando recriações inesperadas, essa opção pode ajudar a entender o motivo. Adicione-o ao seu .bazelrc para que o registro em log ocorra em todas as builds subsequentes e inspecione o log quando uma etapa de execução for executada inesperadamente. Essa opção pode ter uma pequena penalidade de performance. Por isso, remova-a quando não for mais necessária.

--verbose_explanations

Essa opção aumenta a verbosidade das explicações geradas quando a opção --explain está ativada.

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

Usar essa opção pode aumentar significativamente o tamanho do arquivo de explicação gerado e a penalidade de desempenho de usar --explain.

Se --explain não estiver ativada, --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 build pode ser útil para entender onde o comando build do Bazel está gastando tempo.

--[no]show_loading_progress

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

--[no]show_progress

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

--show_progress_rate_limit=n

Essa opção faz com que o bazel mostre 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 vai limitar as mensagens de progresso a uma a cada 0,02 segundos.

--show_result=n

Essa opção controla a impressão de informações de resultado no final de um comando bazel build. Por padrão, se um único destino de build for especificado, o Bazel vai imprimir uma mensagem informando se o destino foi atualizado ou não e, em caso afirmativo, a lista de arquivos de saída que o destino criou. Se vários destinos foram especificados, as informações de resultado não serão mostradas.

Embora as informações de resultado possam ser úteis para builds de um único destino ou de alguns destinos, para builds grandes (como uma árvore de projeto de nível superior inteira), essas informações podem ser excessivas e distrair. Essa opção permite que elas sejam controladas. --show_result usa um argumento inteiro, que é o número máximo de destinos para os quais as informações completas de resultado devem ser impressas. Por padrão, o valor é 1. Acima desse limite, nenhuma informação de resultado é mostrada para metas individuais. Assim, zero sempre suprime as informações de resultado, e um valor muito grande sempre imprime o resultado.

Os usuários podem escolher um valor intermediário se alternarem regularmente entre a criação de um pequeno grupo de destinos (por exemplo, durante o ciclo de compilação-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 de resultado são muito úteis, enquanto no segundo, são menos úteis. Como em todas as opções, isso pode ser especificado implicitamente pelo arquivo .bazelrc.

Os arquivos são impressos para facilitar a cópia e colagem do nome do arquivo no shell, para executar executáveis criados. As mensagens "atualizado" ou "falha" de cada destino podem ser facilmente analisadas por scripts que impulsionam um build.

--sandbox_debug

Essa opção faz com que o Bazel imprima informações extras de depuração ao usar o sandboxing para execução de ações. 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 da execução.

  >>>>> # //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 que possam ser 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. Não se esqueça de copiá-los. No entanto, alguns comandos são implementados internamente no Bazel, como a criação de árvores de links simbólicos. Para eles, não há uma linha de comando para mostrar.

--subcommands=pretty_print pode ser transmitido para imprimir os argumentos do comando como uma lista em vez de uma única linha. Isso pode ajudar a tornar linhas de comando longas mais legíveis.

Consulte 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 comandos com falha. Isso pode ser muito útil para depurar um build com falha.

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

Status do espaço de trabalho

Use essas opções para "marcar" binários criados com o Bazel: para incorporar informações adicionais aos binários, como a revisão do controle de origem ou outras informações relacionadas ao espaço de trabalho. É possível usar esse mecanismo com regras que aceitam o atributo stamp, como genrule, cc_binary e muito mais.

--workspace_status_command=program

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

O valor da flag precisa ser um caminho para um programa nativo. No Linux/macOS, pode ser qualquer executável. No Windows, precisa ser um binário nativo, geralmente um arquivo ".exe", ".bat" ou ".cmd".

O programa precisa 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, o build vai falhar. Os nomes das chaves podem ser qualquer coisa, mas só podem usar letras maiúsculas e sublinhados. O primeiro espaço depois do nome da chave a 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 divide as chaves em dois intervalos: "estável" e "volátil". Os nomes "estável" e "volátil" são um pouco contraditórios, 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 seus 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 mudar, o Bazel vai invalidar as ações que dependem dele. Em outras palavras, se o valor de uma chave estável mudar, o Bazel vai executar novamente as ações de carimbo. Portanto, o status estável não deve conter elementos como carimbos de data/hora, porque eles mudam o tempo todo e fariam o Bazel executar novamente as ações marcadas com cada build.

  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.

• Os valores das 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 o bazel-out/volatile-status.txt arquivo. Para evitar a execução repetida de ações marcadas o tempo todo, o Bazel finge que o arquivo volátil nunca muda. Em outras palavras, se o arquivo de status volátil for o único cujo conteúdo mudou, o Bazel não vai invalidar as ações que dependem dele. Se outras entradas das ações mudarem, o Bazel vai executar novamente essa ação, e ela vai ver o status volátil atualizado. No entanto, apenas a mudança do status volátil não invalida a ação.

  O Bazel sempre gera as seguintes chaves voláteis:

  • BUILD_TIMESTAMP: tempo do build em segundos desde a época do Unix (o valor de System.currentTimeMillis() dividido por mil).
  • FORMATTED_DATE: hora do build formatada como yyyy MMM d HH mm ss EEE(por exemplo, 2023 Jun 2 01 44 29 Fri) 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, com sucesso (sai com zero) e não imprime nenhuma saída. No Windows, você pode transmitir o caminho do true.exe do MSYS para ter o mesmo efeito.

Se o comando de status do espaço de trabalho falhar (sair com um valor diferente de zero) por qualquer motivo, o build vai falhar.

Exemplo de programa no Linux usando 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, e o arquivo de status estável vai incluir as linhas STABLE, e o arquivo de status volátil vai incluir o restante das linhas.

--[no]stamp

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

A inclusão de carimbos pode ser ativada ou desativada explicitamente por regra usando o atributo stamp. Consulte a Build Encyclopedia para mais detalhes. Quando uma regra define stamp = -1 (o padrão para regras *_binary), essa opção determina se a inclusão de carimbos está ativada.

O Bazel nunca adiciona carimbos a binários criados para a configuração de execução, independente dessa opção ou do atributo stamp. Para regras que definem stamp = 0 (o padrão para regras de *_test), a inclusão de carimbos é desativada, independente de --[no]stamp. Especificar --stamp não força a reconstrução dos destinos se as dependências deles não tiverem mudado.

Definir --nostamp geralmente é desejável para o desempenho da build, já que reduz a volatilidade da entrada e maximiza o armazenamento em cache da build.

Plataforma

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

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

--platforms=labels

Os rótulos das regras da 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 realizar ações. As plataformas podem ser especificadas por segmentação exata ou como um padrão de segmentação. Essas plataformas serão consideradas antes daquelas declaradas no arquivo WORKSPACE por register_execution_platforms(). Essa opção aceita uma lista de plataformas separadas por vírgulas em ordem de prioridade. Se a flag for transmitida várias vezes, a mais recente vai substituir as outras.

--extra_toolchains=labels

As regras da cadeia de ferramentas a serem consideradas durante a resolução da cadeia de ferramentas. As toolchains podem ser especificadas por destino exato ou como um padrão de destino. Esses conjuntos de ferramentas serão considerados antes daqueles declarados no arquivo WORKSPACE por register_toolchains().

--toolchain_resolution_debug=regex

Imprime informações de depuração ao encontrar toolchains se o tipo de toolchain corresponder à regex. É possível separar várias expressões regulares com vírgulas. A expressão regular 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 a toolchains ausentes.

Diversos

--flag_alias=alias_name=target_path

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

--symlink_prefix=string

Muda o prefixo dos links simbólicos de conveniência gerados. O valor padrão para o prefixo de link simbólico é bazel-, que cria 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 criar em um diretório somente leitura ou em um diretório em que você não tem permissão para gravar. Os caminhos impressos em mensagens informativas ao final de um build só usarão a forma abreviada relativa ao symlink se os symlinks apontarem para o local esperado. Em outras palavras, você pode confiar na correção desses caminhos, mesmo que não possa confiar na criação dos symlinks.

Alguns valores comuns dessa opção:

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

• Reduza a confusão:--symlink_prefix=.bazel/ faz com que o Bazel crie links simbólicos chamados bin (etc.) em 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 acerto de cache para builds que substituem os arquivos de saída uns dos outros ou para manter os arquivos de saída para comparações.

--default_visibility=(private|public)

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

--starlark_cpu_profile=_file_

Essa flag, 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 essa opção para identificar funções do Starlark que tornam o carregamento e a análise lentos devido ao excesso de computação. 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 diferentes visualizações dos mesmos dados, tente os comandos pprof svg, web e list.

Como usar o Bazel para lançamentos

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ê encontra uma lista de dicas para engenheiros de lançamento que usam o Bazel.

Opções significativas

Ao usar o Bazel para builds de lançamento, surgem os mesmos problemas que em outros scripts que realizam um build. Para mais detalhes, consulte Chamar o Bazel de scripts. Em especial, 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 builds de várias configurações, pode ser conveniente distinguir cada build com um identificador distinto, como "64bit" x "32bit". Essa opção diferencia os links simbólicos bazel-bin (etc.).

Como 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 realiza atividades simultâneas de build e teste, criando todos os destinos especificados (incluindo destinos não relacionados a testes especificados na linha de comando) e testando os destinos *_test e test_suite assim que os pré-requisitos são criados. Isso significa que a execução do teste é intercalada com a criação. Isso geralmente resulta em ganhos significativos de velocidade.

Opções de bazel test

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

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

• O Bazel detecta mudanças no teste ou nas dependências dele.
• o teste está marcado como external
• vários testes foram solicitados com --runs_per_test
• o teste falhou.

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

Se a resposta for "sim", o comportamento de cache será o mesmo que "auto", exceto que ele poderá 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 (ativado) ou -t- (desativado) convenientes para substituir o padrão em uma execução específica.

--check_tests_up_to_date

Essa opção informa ao Bazel para não executar os testes, mas apenas verificar e informar os resultados armazenados em cache. Se houver testes que não foram criados e executados anteriormente ou cujos resultados estão desatualizados (por exemplo, porque o código-fonte ou as opções de build mudaram), o Bazel vai informar uma mensagem de erro ("o resultado do teste não está atualizado"), vai registrar o status do teste como "SEM STATUS" (em vermelho, se a saída de cor estiver ativada) e vai 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 antes do envio.

--test_verbose_timeout_warnings

Essa opção instrui o Bazel a avisar explicitamente o usuário se o tempo limite de um teste for significativamente maior do que o tempo de execução real do teste. Embora o tempo limite de um teste deva ser definido para que ele não seja 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 deve ter um tempo limite ETERNAL ou LONG, já que eles são muito, muito generosos.

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

--[no]test_keep_going

Por padrão, todos os testes são executados até a conclusão. Se essa flag estiver desativada, o build será cancelado em qualquer teste que não for aprovado. As etapas de build e as invocações de teste subsequentes não são executadas, e as invocações em andamento 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 deve ser tentado se ele falhar por qualquer motivo. Um teste que falha inicialmente, mas é bem-sucedido depois, é informado como FLAKY no resumo do teste. No entanto, ele é considerado aprovado quando se trata de identificar o código de saída do Bazel ou o número total de testes aprovados. Testes que falham em todas as tentativas permitidas são considerados reprovados.

Por padrão (quando essa opção não é especificada ou quando é definida como "padrão"), apenas uma tentativa é permitida para testes regulares e três para regras de teste com o atributo flaky definido. É possível especificar um valor inteiro para substituir o limite máximo de tentativas de teste. O Bazel permite um máximo de 10 tentativas de teste para evitar abusos 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 substituição será aplicada a cada uma delas de forma independente.

O status de uma meta com execuções com falha depende do valor da flag --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á o status instável, a menos que outras execuções com falha causem a falha.

Se um único número for especificado, todos os testes serão executados esse número de 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 correspondem à expressão regular (--runs_per_test=^//pizza:.*@4 executa todos os testes em //pizza/ quatro vezes). Essa forma de --runs_per_test pode ser especificada mais de uma vez.

--[no]runs_per_test_detects_flakes

Se essa opção for especificada (por padrão, ela não é), o Bazel vai detectar fragmentos de teste instáveis usando --runs_per_test. Se uma ou mais execuções de um único fragmento falharem e uma ou mais execuções do mesmo fragmento forem aprovadas, o destino será considerado instável com a flag. Se não for especificado, o destino vai informar um status de falha.

--test_summary=output_style

Especifica como o resumo dos resultados do teste deve ser mostrado.

• short imprime os resultados de cada teste junto com o nome do arquivo que contém a saída do teste, caso ele tenha falhado. Esse é o valor padrão.
• terse como short, mas ainda mais curto: só imprime informações sobre testes que não foram aprovados.
• O detailed imprime cada caso de teste individual 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 do teste deve ser exibida:

• summary mostra um resumo de 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 do build. Durante o build, apenas mensagens simples de progresso serão exibidas quando os testes começarem, forem aprovados ou falharem. Esse é o comportamento padrão.
• O errors envia a saída combinada stdout/stderr de testes com falha apenas para o stdout imediatamente após a conclusão do teste, garantindo que a saída de testes simultâneos não seja intercalada. Imprime um resumo no build, conforme a saída acima.
• all é semelhante a errors, mas imprime a saída de todos os testes, incluindo os aprovados.
• O 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 uma 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 fica 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 do teste vai incluir apenas o nome, o status e o indicador de teste em cache, além de ser formatado para ficar 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

Substitui 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 de teste.

Como alternativa, é possível fornecer quatro valores separados por vírgulas, especificando tempos limite individuais para testes curtos, moderados, longos e eternos (nessa ordem). Em qualquer uma das formas, zero ou um valor negativo para qualquer um dos tamanhos de teste será substituído pelo tempo limite padrão para as categorias de tempo limite definidas na página Writing Tests. Por padrão, o Bazel usa esses tempos limite para todos os testes, inferindo o limite do tamanho do teste, seja ele definido de forma implícita ou explícita.

Os testes que declaram explicitamente a categoria de tempo limite como diferente do tamanho recebem 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 "long" terá o mesmo tempo limite efetivo que um teste "large" sem um tempo limite explícito.

--test_arg=arg

Transmite opções/flags/argumentos de linha de comando para cada processo de teste. Essa opção pode ser usada várias vezes para transmitir 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 de shell usado para iniciar o comando bazel test.

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

--run_under=command-prefix

Isso especifica um prefixo que o executor de testes vai inserir antes do comando de teste antes de executá-lo. O command-prefix é dividido em palavras usando regras de tokenização do Bourne shell, e a lista de palavras é adicionada ao comando que será executado.

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

Algumas advertências:

• O PATH usado para executar testes pode ser diferente do PATH no seu ambiente. Portanto, 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 não é possível usar --run_under 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 os testes por tamanho, tempo limite, tag ou idioma. Um filtro de nome geral conveniente pode encaminhar argumentos de filtro específicos para o executor de testes.

Outras opções para bazel test

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

Execução de executáveis

O comando bazel run é semelhante ao bazel build, mas é usado para criar e executar um único destino. Confira um exemplo de sessão:

  % 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, à invocação direta do binário criado pelo Bazel, e o comportamento é 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 é a árvore de runfiles do binário.

Quando o binário é um teste, o diretório de trabalho atual é a raiz de execução, e uma tentativa de boa-fé é feita para replicar o ambiente em que os testes geralmente são executados. No entanto, a emulação não é perfeita, e testes com vários fragmentos não podem ser executados dessa forma. A opção de linha de comando --test_sharding_strategy=disabled pode ser usada para contornar isso.

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 o build foi executado.
• 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 uma maneira fácil de usar.

Opções de bazel run

--run_under=command-prefix

Isso tem o mesmo efeito da opção --run_under para bazel test (veja acima), exceto que se aplica ao comando executado por bazel run em vez dos testes executados por bazel test e não pode ser executado com um rótulo.

Filtrar saídas de geração de registros do Bazel

Ao invocar um binário com bazel run, o Bazel imprime a saída de geração de registros do próprio Bazel e do binário em invocação. Para reduzir o ruído dos registros, é possível suprimir as saídas do próprio Bazel com as flags --ui_event_filters e --noshow_progress.

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

Executar testes

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

Como limpar saídas de build

O comando clean

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

Cada instância do Bazel está associada a um único espaço de trabalho. Portanto, o comando clean exclui todas as saídas de todas as builds 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 de base de saída que, além da saída 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 rastros de disco e memória de uma instância do Bazel, especifique:

  % bazel clean --expunge

Como alternativa, é possível expurgar em segundo plano usando --expunge_async. É seguro invocar um comando do Bazel no mesmo cliente enquanto a exclusão assíncrona continua sendo executada.

O comando clean é fornecido principalmente como uma forma de recuperar espaço em disco para workspaces que não são mais necessários. As recriações incrementais do Bazel podem não ser perfeitas, então clean pode ser usado para recuperar um estado consistente quando surgem problemas.

O design do Bazel é feito para que esses problemas possam ser corrigidos, e esses bugs têm alta prioridade. Se você encontrar um build incremental incorreto, envie um relatório de bug e informe os 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ências usado durante o build. A linguagem de consulta é usada por dois comandos: query e cquery. A principal diferença entre os dois comandos é que a consulta é executada após a fase de carregamento, e a cquery é 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 se baseia na ideia de operações algébricas em gráficos e está documentada em detalhes em

Referência de consulta do Bazel. Consulte esse documento para ver 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 da saída. --[no]keep_going (desativado por padrão) faz com que a ferramenta de consulta continue progredindo 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 de destino sejam incluídas no gráfico de dependências 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 não é especificada explicitamente no arquivo BUILD, mas é adicionada pelo Bazel.

Exemplo: "Mostre os locais das definições (em arquivos BUILD) de todas as genrules 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ções

O comando aquery permite consultar ações no gráfico de build. Ele opera no gráfico de destino configurado após a análise e expõe informações sobre ações, artefatos e os relacionamentos entre eles.

A ferramenta aceita várias opções de linha de comando. --output seleciona o formato da saída. O formato de saída padrão (text) é legível por humanos. Use proto ou textproto para um formato legível por máquina. O comando aquery é executado em cima de um build regular do Bazel e herda o conjunto de opções disponíveis durante um build.

Ele oferece suporte ao mesmo conjunto de funções disponíveis para query tradicional, mas não para siblings, buildfiles e tests.

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

Comandos e opções diversos

help

O comando help oferece 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. Especificar um argumento mostra ajuda detalhada sobre um tópico específico. A maioria dos tópicos são comandos do Bazel, como build ou query, mas há alguns tópicos de ajuda adicionais 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 Bazel podem ser interrompidos usando o comando shutdown. Esse comando faz com que o servidor do Bazel seja encerrado assim que ficar inativo (por exemplo, após a conclusão de builds ou outros comandos em andamento). Para mais detalhes, consulte Implementação de cliente/servidor.

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

shutdown aceita uma opção, --iff_heap_size_greater_than _n_, que exige um argumento inteiro (em MB). Se especificado, isso torna o desligamento condicional à quantidade de memória já consumida. Isso é útil para scripts que iniciam muitos builds, já que vazamentos de memória no servidor do Bazel podem causar falhas ocasionais. A reinicialização condicional evita essa situação.

info

O comando info imprime vários valores associados à instância do servidor Bazel ou a uma configuração de build específica. (Eles podem ser usados por scripts que impulsionam um build.)

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 vai imprimir apenas o valor dessa chave. Isso é especialmente conveniente ao criar scripts do Bazel, porque evita a necessidade de transmitir o resultado por sed -ne /key:/s/key://p:

Dados independentes da configuração

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

• install_base: o caminho absoluto para o diretório de instalação usado por esta 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 esta instância do Bazel para a combinação atual de usuário e espaço de trabalho. O Bazel coloca todos os resultados de rascunho e build 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 o build 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 lá, apontando para esse diretório.

• output_path: o caminho absoluto para o diretório de saída na raiz de execução usado para todos os arquivos realmente gerados como resultado dos comandos de build. Se o diretório do espaço de trabalho for gravável, um link simbólico chamado bazel-out será colocado lá, apontando 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 para 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 comando. Ele contém os fluxos stdout e stderr intercalados do comando Bazel mais recente. A execução de bazel info vai substituir o conteúdo desse arquivo, já que ele se torna o comando mais recente do Bazel. No entanto, o local do arquivo de registro de comandos não vai mudar, 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 do heap da JVM. Respectivamente: memória usada no momento, memória garantida no momento para estar disponível para a JVM do sistema, alocação máxima possível.

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

• package_path: uma lista separada por dois-pontos de caminhos que seriam pesquisados por pacotes pelo bazel. Tem o mesmo formato do argumento de linha de comando do comando de build --package_path.

Exemplo: o ID do processo do servidor Bazel.

% bazel info server_pid
1285

Dados específicos de 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 a localização do diretório de saída de um build, a escolha do compilador etc.

• bazel-bin, bazel-testlogs e bazel-genfiles: informam o caminho absoluto para os diretórios bazel-* em que os programas gerados pelo build estão localizados. Normalmente, mas nem sempre, é o mesmo que os links simbólicos bazel-* criados no diretório do espaço de trabalho base após uma build bem-sucedida. No entanto, se o diretório do espaço de trabalho for somente leitura, nenhum link simbólico bazel-* poderá ser criado. Scripts que usam o valor informado por bazel info, em vez de presumir a existência do symlink, serão mais robustos.
• O ambiente completo de "Make". Se a flag --show_make_env for especificada, todas as variáveis no ambiente "Make" da configuração atual também serão mostradas (como CC, GLIBC_VERSION etc.). Essas são as variáveis acessadas usando a sintaxe $(CC) ou varref("CC") dentro dos arquivos BUILD.

Exemplo: o compilador C++ para a configuração atual. Essa é a variável $(CC) no ambiente "Make". Portanto, a flag --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 nos casos em que o link simbólico bazel-bin não pode ser criado por algum motivo (por exemplo, se você estiver criando em 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 sobre o binário do Bazel criado, incluindo a lista de mudanças em que ele foi criado e a data. Eles são particularmente úteis para determinar se você tem a versão mais recente do Bazel ou se está relatando bugs. Alguns dos valores interessantes são:

• changelist: a lista de mudanças em que esta versão do Bazel foi lançada.
• label: o rótulo de lançamento desta instância do Bazel ou "versão de desenvolvimento" se não for um binário lançado. Muito útil ao informar bugs.

bazel --version, sem outros argumentos, vai emitir a mesma saída que bazel version --gnu_format, mas sem o efeito colateral de iniciar um servidor do Bazel ou descompactar o arquivo do servidor. O bazel --version pode ser executado em qualquer lugar e não exige um diretório de espaço de trabalho.

mobile-install

O comando mobile-install instala apps em dispositivos móveis. No momento, apenas dispositivos Android que executam o 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 tenta instalar o app de forma incremental, ou seja, apenas as partes que mudaram desde o último build. Não é possível atualizar recursos referenciados de AndroidManifest.xml, código nativo ou recursos Java (como os referenciados por Class.getResource()). Se esses itens mudarem, 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 Marshmallow ou mais recente, considere a flag --split_apks.

--split_apks

Se é necessário usar APKs divididos para instalar e atualizar o aplicativo no dispositivo. Funciona apenas com dispositivos Marshmallow ou mais recentes. A flag --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

Aguarde a conexão com o depurador antes de iniciar o app em um 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 aceitos são:

• NO Não inicia o app. Essa é a opçã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 geralmente 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 detalhamento para instalação incremental. Definido como 1 para que o registro de depuração seja impresso no console.

dump

O comando dump imprime no stdout um despejo do estado interno do servidor do Bazel. Esse comando é destinado principalmente ao uso por desenvolvedores do Bazel. Portanto, a saída dele não é especificada e está sujeita a mudanças.

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

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

• --action_cache despeja o conteúdo do cache de ações.
• O --packages despeja o conteúdo do cache do pacote.
• O --skyframe despeja o estado do gráfico de dependência interno do Bazel.
• --rules gera um resumo de regras para cada regra e classe de aspecto, incluindo contagens e contagens de ações. Isso inclui 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. Para isso, é necessário ativar o rastreamento de memória.

Monitoramento de memória

Alguns comandos dump exigem rastreamento de memória. Para ativar isso, transmita flags de inicialização para o Bazel:

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

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

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

Exemplo:

    % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.4.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.4.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.4.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 rastreamento JSON coletado anteriormente durante uma invocação do Bazel.

canonicalize-flags

O comando canonicalize-flags 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 é canônica. Por exemplo, duas listas de opções com o mesmo efeito são canonicalizadas para a mesma nova lista.

A opção --for_command pode ser usada para selecionar entre diferentes comandos. No momento, apenas build e test são compatíveis. Opções que o comando especificado não aceita 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 processados por esse servidor. Se houver um servidor do Bazel já em execução e as opções de inicialização não forem iguais, ele será reiniciado.

Todas as opções descritas nesta seção precisam ser especificadas 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 listar essas informações em um arquivo .bazelrc.

--output_base=dir

Essa opção exige um argumento de caminho, que precisa especificar um diretório gravável. O Bazel vai 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 mudar a base de saída, você muda o servidor que vai processar 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 dele). Portanto, um valor típico é parecido com este: /var/tmp/google/_bazel_johndoe/d41d8cd98f00b204e9800998ecf8427e.

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 (devido ao operador & do shell), cada um usando uma instância diferente do servidor do Bazel (devido às diferentes bases de saída). Por outro lado, se a base de saída padrão fosse usada nos dois comandos, as duas solicitações seriam enviadas ao mesmo servidor, que as processaria sequencialmente: criando //foo primeiro, seguido por uma 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 precisa ser de propriedade do usuário que faz a chamada. No passado, isso era permitido para apontar para um diretório compartilhado entre vários usuários, mas não é mais permitido. Isso pode ser permitido quando o problema nº 11100 for resolvido.

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

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

Você pode usar a opção --output_user_root para escolher um local base alternativo para toda a saída do Bazel (base de instalação 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 próprio Bazel é executado. O valor precisa ser um caminho para o diretório que contém um JDK ou JRE. Não pode ser um rótulo. Essa opção precisa aparecer antes de qualquer comando do Bazel. Por exemplo:

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

Essa flag não afeta as JVMs usadas por subprocessos do Bazel, como aplicativos, testes, ferramentas etc. Use as opções de build --javabase ou --host_javabase.

Essa flag era chamada de --host_javabase (às vezes chamada de --host_javabase "lado esquerdo"), mas foi renomeada para evitar confusão com a flag de build --host_javabase (às vezes chamada de --host_javabase "lado direito").

--host_jvm_args=string

Especifica uma opção de inicialização a ser transmitida para a máquina virtual Java em que o próprio Bazel é 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. A definição dessa flag raramente é necessária. Também é possível transmitir uma lista de strings separadas por espaços. Cada uma delas será interpretada como um argumento JVM separado, mas esse recurso será descontinuado em breve.

Isso não afeta nenhuma JVM usada por subprocessos do Bazel: aplicativos, testes, ferramentas etc. Para transmitir opções da JVM a programas executáveis em Java, seja executado por bazel run ou na linha de comando, use o argumento --jvm_flags, que todos os programas java_binary e java_test aceitam. 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 uma conexão de um depurador compatível com JDWP antes de chamar o método principal do próprio Bazel. Ele é destinado principalmente a desenvolvedores do Bazel.

--autodetect_server_javabase

Com essa opção, o Bazel pesquisa automaticamente um JDK instalado na inicialização e volta para 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 em lote faz com que o Bazel não use o modo cliente/servidor padrão, mas execute um processo bazel java para um único comando, que tem sido usado para semântica mais previsível em relação ao processamento de sinais, controle de jobs e herança de variáveis de ambiente, e é necessário para executar o bazel em uma chroot jail.

O modo de lote retém a semântica de enfileiramento adequada no mesmo output_base. Ou seja, as invocações simultâneas serão processadas em ordem, sem sobreposição. Se um Bazel no modo de lote for executado em um cliente com um servidor em execução, ele primeiro interromperá o servidor antes de processar o comando.

O Bazel será executado mais lentamente no modo em lote ou com as alternativas descritas acima. Isso ocorre porque, entre outras coisas, o cache de arquivos de build reside na memória e, portanto, não é preservado entre invocações de lote sequenciais. Portanto, usar o modo de lote geralmente faz mais sentido em casos em que o desempenho é menos crítico, como builds contínuos.

--max_idle_secs=n

Essa opção especifica por quanto tempo, em segundos, o processo do servidor Bazel deve esperar após a última solicitação do cliente antes de ser encerrado. O valor padrão é 10.800 (3 horas). --max_idle_secs=0 fará com que o processo do servidor Bazel persista indefinidamente.

Essa opção pode ser usada por scripts que invocam o Bazel para garantir que não deixem processos do servidor Bazel na máquina de um usuário quando não estiverem em execução. Por exemplo, um script de pré-envio pode querer invocar bazel query para garantir que uma mudança pendente de um usuário não introduza dependências indesejadas. No entanto, se o usuário não tiver feito um build recente nesse espaço de trabalho, não será desejável que o script de pré-envio inicie um servidor Bazel apenas para que ele fique ocioso pelo resto do dia. Ao especificar um valor pequeno de --max_idle_secs na solicitação de consulta, o script pode garantir que, se ele tiver causado a inicialização de um novo servidor, esse servidor será encerrado imediatamente. No entanto, se já houver um servidor em execução, ele continuará funcionando até ficar inativo pelo tempo normal. É claro que o timer de inatividade do servidor atual será redefinido.

--[no]shutdown_on_low_sys_mem

Se ativado e --max_idle_secs estiver definido como uma duração positiva, depois que o servidor de build ficar inativo por um tempo, ele será desligado 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 build começa a monitorar a memória do sistema disponível depois que o servidor fica inativo por algum tempo. Se a memória do sistema disponível ficar criticamente baixa, o servidor será encerrado.

--[no]block_for_lock

Se ativado, o Bazel vai aguardar a conclusão de outros comandos do Bazel que mantêm o bloqueio do servidor antes de prosseguir. Se desativado, o Bazel vai sair com um erro se não conseguir adquirir o bloqueio imediatamente e continuar.

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

--io_nice_level=n

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

--batch_cpu_scheduling

Use o agendamento de CPU batch para o Bazel. Essa política é útil para cargas de trabalho não interativas que não querem diminuir o valor nice. Consulte "man 2 sched_setscheduler". Essa política pode melhorar a interatividade do sistema, mas prejudica a capacidade de transferência do Bazel.

Opções diversas

--[no]announce_rc

Controla se o Bazel anuncia as 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 vai usar cores para destacar a saída na tela.

Se essa opção estiver definida como yes, a saída de cor será ativada. Se essa opção for definida como auto, o Bazel usará a saída de cor somente se ela for 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 estiver definida como no, a saída de cor será desativada, independente de a saída ir 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 o command atual, também extrai as opções de command:name, se houver uma seção desse tipo. Pode ser especificado várias vezes para adicionar flags de várias seções de configuração. As expansões podem se referir a outras definições (por exemplo, podem ser encadeadas).

--curses (yes|no|auto)

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

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

--[no]show_timestamps

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