Nesta página, abordamos as opções disponíveis para vários comandos do Bazel, como bazel build
, bazel run
e bazel test
. Esta página acompanha
a lista de comandos do Bazel em Criar com o 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ão documentadas em
Como especificar destinos para a criação.
Opções
As seções abaixo descrevem as opções disponíveis durante um
build. Quando --long
é usado em um comando de ajuda, as mensagens
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 que são pesquisados para encontrar o arquivo BUILD de um determinado pacote.
O Bazel encontra os pacotes pesquisando o caminho do pacote. Ela é 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 do caminho do pacote podem ser especificados em três formatos:
- Se o primeiro caractere for
/
, o caminho será absoluto. - Se o caminho começar com
%workspace%
, ele será levado em relação 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
. - Todo o restante é usado em relação ao diretório de trabalho.
Em geral, isso não é o que você quer fazer
e poderá se comportar de maneira inesperada se usar o Bazel nos diretórios abaixo do espaço de trabalho do Bazel.
Por exemplo, se você usar o elemento package-path
.
e depois 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 conveniência.
O Bazel não exige que nenhum pacote esteja no diretório atual, então você pode fazer um build em um espaço de trabalho do bazel vazio se todos os pacotes necessários puderem ser encontrados em outro lugar no caminho do pacote.
Exemplo: criar a partir de um cliente vazio
% mkdir -p foo/bazel % cd foo/bazel % touch WORKSPACE % bazel build --package_path /some/other/path //foo
--deleted_packages
Essa opção especifica uma lista separada por vírgulas de pacotes que o Bazel considera excluídos e não tenta carregar de nenhum diretório no caminho do pacote. Isso pode ser usado para simular a exclusão de pacotes sem realmente excluí-los. Essa opção pode ser passada 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 os avisos do Bazel.
--[no]check_visibility
Se essa opção for definida como falsa, as verificações de visibilidade serão rebaixadas para avisos. O valor padrão dessa opção é verdadeiro, para que a verificação de visibilidade seja feita por padrão.
--output_filter=regex
A opção --output_filter
só vai mostrar avisos de build e
compilação para destinos que corresponderem à expressão regular. Se um destino não
corresponder à expressão regular em questão e a execução dela for bem-sucedida, a saída
e o erro padrão serão descartados.
Veja alguns valores comuns para essa opção:
`--output_filter='^//(first/project|second/project):'` | Mostra a saída dos pacotes especificados. |
`--output_filter='^//((?!(first/bad_project|second/bad_project):).)*$'` | Não mostra a saída dos pacotes especificados. |
`--output_filter=` | Mostrar tudo. |
`--output_filter=DONT_MATCH_ANYTHING` | Não mostrar. |
Sinalizações 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 para o compilador. O argumento será passado para o compilador sempre que for invocado para pré-processamento, compilação e/ou montagem de código C, C++ ou assembler. Ele não será transmitido na 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
um 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 exec. Isso é análogo à opção --copt
, mas se aplica apenas à configuração exec.
--host_conlyopt=cc-option
Essa opção usa um argumento que precisa ser transmitido ao compilador para arquivos de origem C
que são compilados na configuração exec. Isso é análogo à
opção --conlyopt
, mas se aplica apenas
à configuração exec.
--host_cxxopt=cc-option
Essa opção usa um argumento que será transmitido ao compilador dos arquivos de origem C++
que são compilados na configuração exec. Isso é análogo à opção --cxxopt
, mas se aplica apenas à configuração exec.
--host_linkopt=linker-option
Essa opção usa um argumento que será transmitido para o vinculador dos arquivos de origem compilados na configuração de execução. Isso é análogo à opção --linkopt
, mas se aplica apenas à configuração exec.
--conlyopt=cc-option
Essa opção usa um argumento que será passado ao compilador ao compilar arquivos de origem em C.
Isso é semelhante a --copt
, mas se aplica somente à compilação C,
não à compilação ou vinculação C++. Você pode transmitir opções específicas de C
(como -Wno-pointer-sign
) usando --conlyopt
.
--cxxopt=cc-option
Essa opção usa um argumento que será transmitido para o compilador ao compilar arquivos de origem em C++.
Isso é semelhante a --copt
, mas se aplica apenas à compilação em C++,
não à compilação ou vinculação C++. Você pode transmitir opções específicas de 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 será transmitido ao compilador durante a vinculação.
Isso é semelhante a --copt
, mas só se aplica à vinculação,
não à compilação. Assim, você pode transmitir opções do compilador que só fazem sentido
no momento do link (como -lssp
ou -Wl,--wrap,abort
)
usando --linkopt
. Exemplo:
% bazel build --copt="-fmudflap" --linkopt="-lmudflap" //foo/buggy_code
As regras de criação também podem especificar opções de vinculação nos atributos delas. 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 as informações de depuração de
todos os binários e bibliotecas compartilhadas invocando o vinculador com a opção -Wl,--strip-debug
.
--strip=always
significa sempre remover informações de depuração.
--strip=never
significa que 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
vai compilar o destino, removendo 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 apenas remove informações de depuração. Se, por algum motivo, você quiser remover todos os símbolos,
não apenas os símbolos de debug, use a opção --strip-all
do ld,
transmitindo --linkopt=-Wl,--strip-all
para o Bazel. Esteja
ciente de que a definição da flag --strip
do Bazel vai substituir
--linkopt=-Wl,--strip-all
. Portanto, defina apenas uma das opções.
Se você estiver criando apenas um binário e quiser que todos os símbolos sejam removidos, também é possível
transmitir --stripopt=--strip-all
e criar explicitamente a
versão //foo:bar.stripped
do destino. Conforme descrito na seção 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 link do build.
--stripopt=strip-option
Essa é uma opção adicional para transmitir ao comando strip
ao gerar
um binário *.stripped
. O padrão
é -S -p
. Essa opção pode ser usada várias vezes.
--fdo_instrument=profile-output-dir
A opção --fdo_instrument
permite a geração de
saída do perfil de otimização direcionada por feedback (FDO, na sigla em inglês) 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 precisará 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 brutos de dados do
perfil do LLVM são despejados. Por exemplo: --fdo_instrument=/path/to/rawprof/dir/
.
As opções --fdo_instrument
e --fdo_optimize
não podem ser usadas ao mesmo tempo.
--fdo_optimize=profile-zip
A opção --fdo_optimize
permite o uso das
informações do perfil de arquivo por objeto para realizar otimizações de FDO (otimização
direta por feedback) na compilação. Para o GCC, o argumento
fornecido é o arquivo ZIP que contém a árvore de arquivos .gcda gerada anteriormente
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 do LLVM indexado preparado pela ferramenta llvm-profdata e ter uma extensão .profdata.
As opções --fdo_instrument
e --fdo_optimize
não podem ser usadas ao mesmo tempo.
--java_language_version=version
Esta opção especifica a versão das origens 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 é 8. -->
Os valores possíveis são: 8, 9, 10, 11, 14, 15 e 21 e podem ser estendidos com o registro de conjuntos de ferramentas Java personalizados usando default_java_toolchain
.
--tool_java_language_version=version
A versão da linguagem Java usada para criar ferramentas que são executadas durante um build. O valor padrão é 8.
--java_runtime_version=version
Essa opção especifica a versão da JVM a ser usada para executar o código e os testes. Exemplo:
% bazel run --java_runtime_version=remotejdk_11 java/com/example/common/foo:java_application
faz o download do JDK 11 de um repositório remoto e executa o aplicativo Java usando esse repositório.
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
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. Pode ser usado com um grande argumento ou várias vezes com argumentos individuais. Exemplo:
% bazel build --jvmopt="-server -Xms256m" java/com/example/common/foo:all
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 passados para javac. Pode ser usado com um grande argumento ou várias vezes com argumentos individuais. Exemplo:
% bazel build --javacopt="-g:source,lines" //myprojects:prog
recriará um java_binary com as informações de depuração padrão do javac (em vez do padrão bazel).
A opção é passada para javac após as 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 javac verifica se há dependências diretas ausentes. Destinos Java precisam declarar explicitamente todos os destinos usados diretamente como dependências. Essa sinalização instrui o javac a determinar os jars realmente usados para a verificação de tipos de cada arquivo Java e a avisar/error se não forem a saída de uma dependência direta do destino atual.
off
significa que a verificação está desativada.warn
significa que javac vai gerar avisos Java padrão do tipo[strict]
para cada dependência direta ausente.default
,strict
eerror
, todos o javac médio vão gerar erros em vez de avisos, fazendo com que o destino atual não seja criado se alguma dependência direta ausente for encontrada. Esse também é o comportamento padrão quando a sinalização não for 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 reduzida para -c
,
especialmente -c opt
) usa um argumento de fastbuild
, dbg
ou opt
e afeta várias opções de geração de código
C/C++, como o nível de otimização e a integridade das
tabelas de depuração. O Bazel usa um diretório de saída diferente para cada
modo de compilação diferente. Assim, você pode alternar entre os modos sem
precisar fazer uma recompilação completa sempre.
fastbuild
significa criar o mais rápido possível: gerar informações mínimas de depuração (-gmlt -Wl,-S
) e não otimizar. Esse é o padrão. Observação:-DNDEBUG
não será definido.dbg
significa criar com a depuração ativada (-g
) para que você possa usar gdb (ou outro depurador).opt
significa criar com a otimização ativada e com chamadasassert()
desativadas (-O2 -DNDEBUG
). As informações de depuração não serão geradas no modoopt
, 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 pelo nome. Nesse caso, o valor será recebido do
ambiente de invocação ou pelo par name=value
, que define o valor independente do
ambiente de invocação.
Essa sinalização --action_env
pode ser especificada várias vezes. Se um valor for atribuído à mesma
variável em várias sinalizações --action_env
, a atribuição mais recente vencerá.
--experimental_action_listener=label
A opção experimental_action_listener
instrui o Bazel a usar
detalhes da regra action_listener
especificada por label para
inserir extra_actions
no gráfico de build.
--[no]experimental_extra_action_top_level_only
Se esta opção for definida como verdadeira, as ações extras especificadas pela opção de linha de comando --experimental_action_listener
só serão programadas para destinos de nível superior.
--experimental_extra_action_filter=regex
A opção experimental_extra_action_filter
instrui o Bazel a
filtrar o conjunto de destinos para programar extra_actions
.
Essa sinalização é aplicável somente em combinação com a
sinalização --experimental_action_listener
.
Por padrão, todos os extra_actions
no fechamento transitivo dos
destinos para criação solicitados são programados para execução.
--experimental_extra_action_filter
restringe a programação a extra_actions
, das quais o rótulo do proprietário corresponde à expressão regular especificada.
O exemplo a seguir limita a programação de extra_actions
para que se aplique apenas a ações em que o rótulo do proprietário contenha '/bar/':
% bazel build --experimental_action_listener=//test:al //foo/... \ --experimental_extra_action_filter=.*/bar/.*
--host_cpu=cpu
Essa opção especifica o nome da arquitetura de CPU que precisa ser usada para criar ferramentas de host.
--android_platforms=platform[,platform]*
As plataformas para criar o deps
transitivo das
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á valor padrão para essa flag: é necessário definir e usar uma plataforma Android personalizada.
Um arquivo .so
é criado e empacotado no APK para cada plataforma especificada
com --android_platforms
. O nome do arquivo .so
tem "lib" como prefixo do nome da
regra android_binary
. Por exemplo, se o nome de android_binary
for "foo", o arquivo será libfoo.so
.
--per_file_copt=[+-]regex[,[+-]regex]...@option[,option]...
Quando presente, qualquer arquivo C++ com um rótulo ou um caminho de execução correspondente a uma das expressões regex
de inclusão e que não corresponda a nenhuma das expressões de exclusão será criado
com as opções fornecidas. A correspondência de rótulo 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 (incluindo a extensão) do arquivo C++. Ela também inclui os prefixos dependentes da plataforma.
Para corresponder aos arquivos gerados (como saídas genrule),
o Bazel só pode usar o caminho de execução. Nesse caso, a regexp não deve começar com "//",
porque não corresponde a nenhum caminho de execução. Os nomes dos pacotes podem ser usados desta forma:
--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 independentemente do modo de compilação usado. Por exemplo, é possível
compilar com --compilation_mode=opt
e compilar seletivamente alguns
arquivos com a otimização mais forte ativada ou com a otimização desativada.
Advertência: se alguns arquivos forem compilados seletivamente com símbolos de depuração, os símbolos
podem 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 ser prefixada com
um +
para identificar padrões de inclusão e com -
para identificar
padrões de exclusão. option
significa uma opção arbitrária transmitida ao compilador C++. Se uma opção contiver um ,
, ela precisará ser citada como \,
. As opções também podem conter @
, já que apenas o primeiro
@
é usado para separar expressões regulares das opções.
Exemplo:
--per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-O0,-fprofile-arcs
adiciona as opções -O0
e -fprofile-arcs
à linha
de comando do compilador C++ para todos os arquivos .cc
em //foo/
, exceto file.cc
.
--dynamic_mode=mode
Determina se os binários C++ serão vinculados dinamicamente, interagindo com o atributo linkstatic nas regras de build.
Modos:
auto
: traduz para um modo dependente da plataforma;default
para Linux eoff
para cygwin.default
: permite que o Bazel escolha se quer vincular dinamicamente. Consulte linkstatic para mais informações.fully
: vincula todos os destinos dinamicamente. Isso acelera o tempo de vinculação e reduz o tamanho dos binários resultantes.off
: vincula todos os destinos no modo principalmente estático. Se-static
for definido em linkopts, os destinos serão alterados para totalmente estáticos.
--fission (yes|no|[dbg][,opt][,fastbuild])
Ativa a Fission, que grava informações de depuração de C++ em arquivos .dwo dedicados, em vez de arquivos .o, para onde iriam. Isso reduz substancialmente o tamanho da entrada dos links e pode reduzir os tempos dos links.
Quando definida como [dbg][,opt][,fastbuild]
(exemplo:
--fission=dbg,fastbuild
), a fissão é ativada
apenas para o conjunto especificado de modos de compilação. Isso é útil para as configurações de bazelrc. Quando definido como yes
, a fissão é ativada
universalmente. Quando definido como no
, a fissão é desativada
universamente. O padrão é no
.
--force_ignore_dash_static
Se essa sinalização estiver definida, todas as opções -static
em vinculações de
arquivos BUILD de regras cc_*
serão ignoradas. Isso é apenas uma
solução alternativa para builds de aumento da proteção do C++.
--[no]force_pic
Se essa opção estiver ativada, todas as compilações em C++ produzirão um código independente de posição ("-fPIC"), os links terão preferência por bibliotecas pré-criadas PIC em vez de bibliotecas não PIC, e os links produzem executáveis independentes de posição ("-pie"). O padrão é desativado.
--android_resource_shrinking
Seleciona se a redução de recursos para regras android_binary será realizada. Define o padrão para o atributo reduzir_recursos nas regras android_binary. Consulte a documentação dessa regra para ver mais detalhes. O padrão é desativado.
--custom_malloc=malloc-library-target
Quando especificada, usa sempre a implementação maloca determinada, substituindo todos os
atributos malloc="target"
, incluindo os destinos que usam o
padrão (sem especificar nenhum malloc
).
--crosstool_top=label
Essa opção especifica o local do pacote de compilador crosstool
a ser usado para toda a compilação em C++ durante um build. O Bazel procurará um arquivo CROSSTOOL nesse local e o usará para determinar automaticamente as configurações de --compiler
.
--host_crosstool_top=label
Se não for especificado, ele usará o valor de --crosstool_top
para compilar
código na configuração "exec", como ferramentas executadas durante a compilação. O principal objetivo dessa flag
é permitir a compilação cruzada.
--apple_crosstool_top=label
A crosstool a ser usada para compilar regras C/C++ no deps
transitivo das
regras objc*, ios* e apple*. Para esses destinos, essa sinalização substitui
--crosstool_top
.
--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 o conjunto de ferramentas do SDK/plataforma e a biblioteca do Android Runtime que serão usados para criar qualquer regra relacionada ao Android.
O SDK do Android será selecionado automaticamente se uma regra android_sdk_repository
for definida no arquivo do ESPAÇO DE TRABALHO.
--java_toolchain=label
Essa opção especifica o rótulo do java_dataset usado para compilar arquivos de origem Java.
--host_java_toolchain=label
Se não for especificado, o Bazel usará o valor de --java_toolchain
para compilar
código na configuração exec, como para ferramentas executadas durante a compilação. O principal objetivo dessa flag
é permitir a compilação cruzada.
--javabase=(label)
Essa opção define o rótulo da instalação Java básica a ser usada no bazel run (em inglês), no teste do bazel (em inglês) e nos binários Java criados pelas regras java_binary
e java_test
. As variáveis"Make"
JAVABASE
e JAVA
são derivadas dessa opção.
--host_javabase=label
Essa opção define o rótulo da instalação básica do Java a ser usado na configuração exec. Por exemplo, para ferramentas de build do host, incluindo JavaBuilder e Singlejar.
Essa ação não seleciona o compilador Java usado para compilar arquivos de origem Java. O compilador pode ser selecionado pelas configurações na opção
--java_toolchain
.
Estratégia de execução
Essas opções afetam como o Bazel executará a compilação. Eles não precisam ter nenhum efeito significativo nos arquivos de saída gerados pelo build. Normalmente, o principal efeito deles é na velocidade do build.
--spawn_strategy=strategy
Essa opção controla onde e como os comandos são executados.
standalone
faz com que os comandos sejam executados como subprocessos locais. Esse valor foi descontinuado. Em vez disso, uselocal
sandboxed
faz com que os comandos sejam executados dentro de um sandbox na máquina local. Isso exige que todos os arquivos de entrada, dependências de dados e ferramentas sejam listados como dependências diretas nos atributossrcs
,data
etools
. O Bazel ativa o sandbox local por padrão em sistemas compatíveis com a execução em sandbox.local
faz com que os comandos sejam executados como subprocessos locais.worker
faz com que os comandos sejam executados usando um worker permanente, se disponível.docker
faz com que os comandos sejam executados dentro de um sandbox do Docker na máquina local. Para isso, é necessário que o Docker esteja instalado.remote
faz com que os comandos sejam executados remotamente. Isso só estará 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 mnemonic Genrule) com base em cada mnemônico. Consulte --spawn_strategy para conhecer as estratégias compatíveis e os efeitos delas.
--strategy_regexp=<filter,filter,...>=<strategy>
Essa opção especifica qual estratégia precisa ser usada para executar comandos com descrições
correspondentes a uma determinada regex_filter
. Consulte --per_file_copt para ver detalhes sobre a correspondência de regex_filter. Consulte --spawn_strategy para conhecer as estratégias compatíveis e os efeitos delas.
O último regex_filter
que corresponde à descrição é usado. Essa opção substitui
outras sinalizações para especificar a estratégia.
- Exemplo:
--strategy_regexp=//foo.*\\.cc,-//foo/bar=local
significa executar ações usando a estratégialocal
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égiasandboxed
, mas inverter a ordem a executa comlocal
. - Exemplo:
--strategy_regexp='Compiling.*/bar=local,sandboxed'
executa "Compiling //foo/bar/baz" com a estratégialocal
e volta parasandboxed
se falhar.
--genrule_strategy=strategy
Essa é uma abreviação 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 precisam ser executados simultaneamente durante a fase de execução do build.
--progress_report_interval=n
O Bazel periodicamente imprime um relatório de progresso em jobs que ainda não foram concluídos (como testes de longa duração). Essa opção define a frequência do relatório. O progresso será mostrado a cada n
segundos.
O padrão é 0, que significa um algoritmo incremental: o primeiro relatório é mostrado após 10 segundos, depois 30 segundos e, depois desse progresso, uma vez por minuto.
Quando o Bazel está usando o controle de 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 serem executadas localmente. Elas usam um número inteiro ou uma palavra-chave (HOST_RAM ou HOST_CPUS) opcionalmente seguida por [-|*
float]
(por exemplo, --local_cpu_resources=2
, --local_ram_resources=HOST_RAM*.5
, --local_cpu_resources=HOST_CPUS-1
). As sinalizações são independentes. Uma ou ambas podem ser definidas. Por padrão, o Bazel estima
a quantidade de RAM e o número de núcleos de CPU diretamente da configuração do sistema local.
--[no]build_runfile_links
Essa opção, ativada por padrão, especifica se os links simbólicos
de arquivos de execução para testes e binários precisam ser criados no diretório de saída.
O uso de --nobuild_runfile_links
pode ser útil
para validar se todos os destinos são compilados sem gerar a sobrecarga
da criação das árvores de arquivos de execução.
Quando testes (ou aplicativos) são executados, as dependências de dados do ambiente de execução
são reunidas em um só lugar. Dentro da árvore de saída
do Bazel, essa árvore "runfiles" normalmente tem acesso root como um irmão
do binário ou teste correspondente.
Durante a execução do teste, os arquivos de execução podem ser acessados usando caminhos no formato
$TEST_SRCDIR/workspace/packagename/filename
.
A árvore de arquivos de execução garante que os testes tenham acesso a todos os arquivos
em que eles têm uma dependência declarada e nada mais. Por
padrão, a árvore de arquivos de execução é implementada construindo um conjunto de
links simbólicos para os arquivos necessários. À medida que o conjunto de links cresce, o
custo dessa operação também cresce. Para alguns builds grandes, ela pode
contribuir significativamente para o tempo geral de build, principalmente porque
cada teste (ou aplicativo) individual exige uma árvore de arquivos de execução própria.
--[no]build_runfile_manifests
Essa opção, ativada por padrão, especifica se os manifestos dos runfiles
precisam ser gravados na árvore de saída.
A desativação implica --nobuild_runfile_links
.
Ela pode ser desativada ao executar testes remotamente, já que as árvores de arquivos de execução serão criadas remotamente a partir de 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. Isso libera memória adicional (cerca de 10%) para a fase de execução. A desvantagem é que builds incrementais adicionais serão mais lentos. Consulte também modo de economia de memória.
--[no]keep_going
(-mil)
Como no GNU Make, a fase de execução de uma compilação é interrompida quando o primeiro erro é encontrado. Às vezes, é útil tentar criar o máximo possível, mesmo que ocorram erros. Essa opção ativa esse comportamento e, quando ela é especificada, o build tenta criar todos os destinos que tenham pré-requisitos criados, mas ignora erros.
Embora essa opção esteja geralmente 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, mas somente alguns deles puderem ser analisados, o build será interrompido com um erro, a menos que --keep_going
seja especificado. Nesse caso, o build prosseguirá para a fase de execução, mas apenas para os destinos que foram analisados.
--[no]use_ijars
Essa opção muda a maneira como os destinos java_library
são
compilados pelo Bazel. Em vez de usar a saída de um
java_library
para compilar destinos
java_library
dependentes, o Bazel criará jars de interface
que contêm apenas as assinaturas de membros não particulares (métodos e campos de acesso
públicos, protegidos e padrão (pacote)) e usará
os jars da interface para compilar os destinos dependentes. Isso
possibilita evitar a recompilação quando as mudanças são feitas apenas nos
corpos de métodos ou em membros particulares de uma classe.
--[no]interface_shared_objects
Essa opção ativa objetos compartilhados de interface, o que faz com que binários e outras bibliotecas compartilhadas dependam da interface de um objeto compartilhado, e não da implementação dele. Quando apenas a implementação muda, o Bazel pode evitar a recriação desnecessariamente de destinos que dependem da biblioteca compartilhada modificada.
Seleção de saída
Essas opções determinam o que compilar ou testar.
--[no]build
Essa opção faz com que a fase de execução do build ocorra. Ela fica ativada por padrão. Quando ele é desligado, 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 necessário para executar as regras *_test
e test_suite
que não foram filtradas devido ao
tamanho,
tempo limite,
tag ou
idioma.
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
o solicitado, incluindo as 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 falhas de
build na árvore foo
.
--[no]check_up_to_date
Essa opção faz com que o Bazel não execute uma versão, mas apenas verifique se todos os destinos especificados estão atualizados. Nesse caso, o build é concluído com êxito, como de costume. No entanto, se algum arquivo estiver desatualizado, em vez de ser criado, um erro será informado e o build falhará. Essa opção pode ser útil para determinar se uma versão foi realizada mais recentemente do que uma edição de origem (por exemplo, para verificações pré-envio) sem incorrer no custo de uma versão.
Consulte também --check_tests_up_to_date
.
--[no]compile_one_dependency
Compile uma única dependência dos arquivos de argumento. Isso é útil para verificar a sintaxe de arquivos de origem em ambientes de desenvolvimento integrado, por exemplo, ao recriar um único destino que depende do arquivo de origem para detectar erros o mais cedo possível no ciclo de edição/criação/teste. Esse argumento afeta a maneira como todos os argumentos que não são de sinalização 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 C++ e Java, as regras no mesmo espaço de linguagem são escolhidas de preferência. Para várias regras com a mesma preferência, aquela 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 erro.
--save_temps
A opção --save_temps
faz com que as saídas temporárias do compilador sejam
salvas. Isso inclui arquivos .s (código assembler), .i (C pré-processado) e .ii
(C++ pré-processado). Essas saídas geralmente são úteis para depuração. As temporárias serão geradas somente para o conjunto de destinos especificados na linha de comando.
No momento, a sinalização --save_temps
funciona apenas para regras cc_*.
Para garantir que o Bazel mostre o local dos outros arquivos de saída, verifique se
a configuração --show_result n
é alta o suficiente.
--build_tag_filters=tag[,tag]*
Se especificado, o Bazel vai criar apenas destinos que tenham pelo menos uma tag necessária (se alguma delas for especificada) e não tiver nenhuma tag excluída. O filtro de tag de build é especificado como uma lista de palavras-chave de tag delimitada por vírgulas, opcionalmente precedida por um sinal "-" usado para indicar as tags excluídas. As tags obrigatórias também podem ter um sinal "+" no início.
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 testará (ou criará, se --build_tests_only
também for especificado) somente destinos de teste com o tamanho determinado. O filtro de tamanho de teste é especificado como uma lista delimitada por vírgulas de valores de tamanho de teste permitidos (pequeno, médio, grande ou enorme), opcionalmente precedido pelo sinal "-", usado para indicar os tamanhos de teste excluídos. Por exemplo:
% bazel test --test_size_filters=small,medium //foo:all
e
% bazel test --test_size_filters=-large,-enormous //foo:all
testará apenas testes pequenos e médios em //foo.
Por padrão, a filtragem de tamanho de teste não é aplicada.
--test_timeout_filters=timeout[,timeout]*
Se especificado, o Bazel testará (ou criará se --build_tests_only
também for especificado) somente destinos de teste com o tempo limite determinado. O filtro de tempo limite do teste é especificado como uma lista delimitada por vírgulas de valores de tempo limite de teste permitidos (curtos, moderados, longos ou eternos), opcionalmente precedidos pelo sinal "-", usado para indicar os tempos limite de teste excluídos. Consulte --test_size_filters para ver a sintaxe de exemplo.
Por padrão, a filtragem de tempo limite de teste não é aplicada.
--test_tag_filters=tag[,tag]*
Se especificado, o Bazel testará (ou criará se --build_tests_only
também for especificado) somente destinos que tenham pelo menos uma tag obrigatória
(se alguma delas for especificada) e não tiver nenhuma tag excluída. O filtro de tag de teste é especificado como uma lista de palavras-chave de tag delimitada por vírgulas, opcionalmente precedida pelo sinal "-" usado para indicar as tags excluídas. As tags obrigatórias também podem ter um sinal "+" no início.
Por exemplo:
% bazel test --test_tag_filters=performance,stress,-flaky //myproject:all
testará destinos marcados com a tag performance
ou stress
, mas não com a tag flaky
.
Por padrão, a filtragem de tags de teste não é aplicada. Também é possível filtrar
as tags size
e local
do teste
dessa maneira.
--test_lang_filters=string[,string]*
Especifica uma lista de strings separada por vírgulas que se refere aos nomes das 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/...
vai 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 pode usar para escolher um subconjunto de testes para execução. Todos os destinos especificados na invocação são criados, mas, dependendo da expressão, apenas alguns deles podem ser executados. Em alguns casos, apenas determinados métodos de teste são executados.
A interpretação específica de filter-expression depende do framework de teste responsável por executar o teste. Pode ser um glob,
substring ou regexp. --test_filter
é mais conveniente
além de transmitir diferentes --test_arg
argumentos de filtro,
mas nem todos os frameworks oferecem suporte a isso.
Verbosidade
Essas opções controlam o nível de detalhes da saída do Bazel, seja para o terminal ou para outros arquivos de registro.
--explain=logfile
Essa opção, que requer um argumento de nome de arquivo, faz com que o
verificador de dependência na fase de execução de bazel build
explique,
para cada etapa de build, por que ele está sendo executado ou
que está atualizado. A explicação é gravada em logfile.
Se você encontrar recriações inesperadas, essa opção pode ajudar a
entender o motivo. Adicione-o ao .bazelrc
para que
a geração de registros ocorra para todos os builds subsequentes e, em seguida, inspecione o registro
quando vir uma etapa de execução executada inesperadamente. Essa opção
pode ter uma pequena penalidade de desempenho, então recomendamos que você a remova
quando ela não for mais necessária.
--verbose_explanations
Essa opção aumenta o nível de detalhes das explicações geradas quando a opção --explain está ativada.
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).
O uso dessa opção pode aumentar significativamente o tamanho do
arquivo de explicação gerado e a penalidade de desempenho do uso de
--explain
.
Se --explain
não estiver ativado, --verbose_explanations
não terá efeito.
--profile=file
Essa opção, que usa um argumento de nome de arquivo, faz com que o Bazel grave
os dados de criação de perfil em um arquivo. 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 gere mensagens de progresso de carregamento de pacotes. Se 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 é ativada por padrão. Quando está 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 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 mostrar uma mensagem informando se
o destino foi atualizado ou não e, em caso afirmativo,
a lista de arquivos de saída criados pelo destino. Se vários destinos tiverem sido especificados, as informações dos resultados não serão exibidas.
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 sobrecarregadas e distraídas.
Com essa opção, ela pode ser controlada. --show_result
usa um argumento de número inteiro, que é o número máximo de destinos
em que as informações completas do resultado precisam ser impressas. Por padrão,
o valor é 1. Acima desse limite, nenhuma informação de resultado é exibida para metas individuais. Assim, o zero faz com que as informações
do resultado sejam sempre suprimidas, e um valor muito grande faz
com que o resultado seja sempre mostrado.
Os usuários podem querer escolher um valor intermediário se alternar 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 do resultado são muito úteis, enquanto no último caso são menos. Assim 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 a colagem do nome do arquivo no shell e a execução de executáveis compilados. As mensagens "atualizadas" ou "com falha" para 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 de depuração extras ao usar o sandbox para execução da ação. Essa opção também preserva os diretórios de sandbox para que os arquivos visíveis para as ações durante a execução possam ser examinados.
--subcommands
(-s
)
Essa opção faz com que a fase de execução do Bazel mostre a linha de comando completa para 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
. Copie-os.
No entanto, alguns comandos são implementados internamente no Bazel, como a
criação de árvores de links simbólicos. Para esses casos, não é necessário exibir uma linha de comando.
--subcommands=pretty_print
pode ser passado para mostrar
os argumentos do comando como uma lista, e não como 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 que falharam. Isso pode ser inestimável para depurar um build com falha.
Os comandos com falha são impressos em uma sintaxe compatível com o shell Bourne, adequada para copiar e colar em um prompt do shell.
Status do espaço de trabalho
Use estas opções para "marcar" binários criados pelo Bazel para incorporar outras informações aos
binários, como a revisão do controle de origem ou outras informações relacionadas ao espaço de trabalho. Você pode usar
esse mecanismo com regras que oferecem suporte ao atributo stamp
, como
genrule
, cc_binary
e outras.
--workspace_status_command=program
Essa sinalização permite especificar um binário que o Bazel executa antes de cada compilação. O programa pode relatar informações sobre o status do espaço de trabalho, como a revisão atual do controle de origem.
O valor da flag precisa ser um caminho para um programa nativo. No Linux/macOS, qualquer executável pode ser gerado. No Windows, precisa ser um binário nativo, geralmente um arquivo ".exe", ".bat" ou ".cmd".
O programa precisa mostrar 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 falha). Os nomes das chaves podem ser qualquer coisa, mas só podem conter letras maiúsculas e sublinhados. O primeiro espaço após o 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 particiona as chaves em dois buckets: "estável" e "volatile". Os nomes "estável" e "volátil" são um pouco contraintuitivos, então não pense muito neles.
Em seguida, o Bazel escreve 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 comSTABLE_
.bazel-out/volatile-status.txt
contém o restante das chaves e os valores delas
O contrato é:
os valores das chaves "estáveis" raramente mudam, se possível. Se o conteúdo de
bazel-out/stable-status.txt
mudar, o Bazel invalidará as ações que dependem dele. Em outras palavras, se o valor de uma chave estável mudar, o Bazel executará novamente as ações marcadas. Portanto, o status estável não pode conter itens como carimbos de data/hora, porque eles mudam o tempo todo e fariam o Bazel executar novamente as ações marcadas com cada compilação.O Bazel sempre gera as seguintes chaves estáveis:
BUILD_EMBED_LABEL
: valor de--embed_label
BUILD_HOST
: o nome da máquina host em que o Bazel está sendo executado.BUILD_USER
: o nome do usuário em que o Bazel está sendo executado.
os valores das chaves "voláteis" podem mudar com frequência. Assim como os carimbos de data/hora, o Bazel espera que elas mudem o tempo todo e atualiza corretamente o arquivo
bazel-out/volatile-status.txt
. No entanto, para evitar sempre que ações sejam executadas novamente, o Bazel finge que o arquivo volátil nunca muda. Em outras palavras, se o arquivo de status volátil for o único com conteúdo alterado, o Bazel não invalidará as ações que dependem dele. Se outras entradas das ações tiverem sido alteradas, o Bazel executará essa ação novamente e a ação verá o status volátil atualizado, mas apenas a alteração do status volátil não invalidará a ação.O Bazel sempre gera as seguintes chaves voláteis:
BUILD_TIMESTAMP
: tempo do build em segundos desde a era Unix (o valor deSystem.currentTimeMillis()
dividido por mil)FORMATTED_DATE
: hora do build formatada comoyyyy MMM d HH mm ss EEE
(por exemplo, 2023 jun 2 01 44 29 sex) em UTC.
No Linux/macOS, é possível transmitir --workspace_status_command=/bin/true
para
desativar a recuperação do status do espaço de trabalho, porque true
não faz nada, sai
com sucesso e não imprime nenhuma saída. No Windows, você pode transmitir o caminho do true.exe
do MSYS
para o mesmo efeito.
Se o comando de status do espaço de trabalho falhar (sair de zero) por qualquer motivo, o build falhará.
Exemplo de programa no Linux com 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, junto com o atributo de regra stamp
, controla a
incorporação de informações de build em binários.
A estampagem pode ser ativada ou desativada explicitamente em cada 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 estampa está ativada.
Ele nunca marca binários criados para a configuração "exec",
independente dessa opção ou do atributo stamp
. Para regras que definem stamp =
0
(o padrão para regras *_test
), o carimbo é desativado, independente de
--[no]stamp
. Especificar --stamp
não força os destinos a serem recriados se
as dependências não tiverem mudado.
Geralmente, convém definir --nostamp
para melhorar o desempenho do build, porque
reduz a volatilidade da entrada e maximiza o armazenamento em cache do build.
Plataforma
Use essas opções para controlar as plataformas de host e destino que configuram o funcionamento das compilações e para controlar quais plataformas de execução e conjuntos de ferramentas estão disponíveis para as regras do Bazel.
Consulte as informações básicas sobre plataformas e conjuntos de ferramentas.
--platforms=labels
Os rótulos das regras da plataforma que descrevem as plataformas de destino do comando atual.
--host_platform=label
O rótulo de uma regra de plataforma que descreve o sistema host.
--extra_execution_platforms=labels
As plataformas que estão disponíveis como plataformas de execução para executar ações. As plataformas podem ser especificadas por destino exato ou como um padrão de destino. Essas plataformas serão consideradas antes das declaradas no arquivo do ESPAÇO DE TRABALHO por register_execution_platforms(). Essa opção aceita uma lista de plataformas separadas por vírgulas em ordem de prioridade. Se a sinalização for transmitida várias vezes, as substituições mais recentes.
--extra_toolchains=labels
As regras do conjunto de ferramentas a serem consideradas durante a resolução do conjunto de ferramentas. Os conjuntos de ferramentas podem ser especificados por destino exato ou como 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 conjuntos de ferramentas se o tipo de conjunto de ferramentas corresponder ao regex. Várias regex podem ser separadas por vírgulas. A regex pode ser negada usando um -
no início. Isso pode ajudar os desenvolvedores
de regras do Bazel ou Starlark com falhas de depuração devido à ausência de conjuntos de ferramentas.
Diversos
--flag_alias=alias_name=target_path
Uma flag de conveniência usada para vincular configurações de build mais longas do Starlark a um nome mais curto. Para ver 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 do prefixo de link simbólico é bazel-
, que
criará os links simbólicos bazel-bin
, bazel-testlogs
e
bazel-genfiles
.
Se não for possível criar os links simbólicos por qualquer motivo, um aviso será emitido, mas o build ainda será considerado um sucesso. Especificamente, isso permite que você crie em um diretório somente leitura ou em um que você não tenha permissão para gravar. Os caminhos impressos em mensagens informativas na conclusão de um build só vão usar a forma curta de links simbólicos se eles apontarem para o local esperado. Em outras palavras, é possível confiar na precisão desses caminhos, mesmo que não dependa dos links simbólicos que estão sendo criados.
Alguns valores comuns dessa opção:
Suprimir a criação de links simbólicos:
--symlink_prefix=/
fará com que o Bazel não crie nem atualize links simbólicos, incluindobazel-out
ebazel-<workspace>
. Use essa opção para suprimir totalmente a criação de links simbólicos.Reduzir a sobrecarga:
--symlink_prefix=.bazel/
fará com que o Bazel crie links simbólicos chamadosbin
(etc) dentro de um diretório oculto.bazel
.
--platform_suffix=string
Adiciona um sufixo ao nome curto da configuração, que é usado para determinar o diretório de saída. A definição dessa opção com valores diferentes coloca os arquivos em diretórios diferentes. Por exemplo, para melhorar as taxas de ocorrência em cache para builds que podem sobrecarregar uns aos outros os arquivos de saída ou para manter os arquivos de saída para comparações.
--default_visibility=(private|public)
Sinalização temporária para testar as mudanças de visibilidade padrão do Bazel. Não destinado ao uso geral, mas documentado para fins de integridade.
--starlark_cpu_profile=_file_
Essa flag, que tem o valor como o nome de um arquivo, faz com que o Bazel reúna 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 ajudar a identificar funções Starlark que tornam o carregamento e a análise lentos devido à computação excessiva. 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, teste os comandos pprof
svg
,
web
e list
.
Como usar o Bazel para versões
Ele é usado por engenheiros de software durante o ciclo de desenvolvimento e por engenheiros de lançamento ao preparar binários para implantação na produção. Esta seção fornece uma lista de dicas para engenheiros de versão que usam o Bazel.
Opções significativas
Ao usar o Bazel para builds de lançamento, surgem os mesmos problemas de outros scripts que executam uma compilação. Para saber mais, consulte Chamar o Bazel usando scripts. Especificamente, as seguintes opções são altamente recomendadas:
Estas opções também são importantes:
--package_path
--symlink_prefix
: para gerenciar builds para várias configurações, pode ser conveniente distinguir cada build com um identificador distinto, como "64 bits" e "32 bits". Essa opção diferencia os links simb.bazel-bin
(etc.).
Executar testes
Para criar e executar testes com o Bazel, digite bazel test
seguido pelo
nome dos destinos de teste.
Por padrão, esse comando executa atividades de build e teste
simultâneas, criando todos os destinos especificados (incluindo os destinos não
de teste especificados na linha de comando) e testando
destinos *_test
e test_suite
assim que
os pré-requisitos são criados, o que significa que a execução do teste é
intercalada com a criação. Isso geralmente resulta em ganhos significativos de velocidade.
Opções de bazel test
--cache_test_results=(yes|no|auto)
(-t
)
Se essa opção for definida como "auto" (padrão), o Bazel só executará um teste novamente se alguma das seguintes condições se aplicar:
- O Bazel detecta mudanças no teste ou nas dependências
- o teste fica marcado como
external
- várias execuções de teste foram solicitadas com
--runs_per_test
- falha no teste.
Se for "não", todos os testes serão executados incondicionalmente.
Se "sim", o comportamento de armazenamento em cache será o mesmo que o automático,
exceto que pode armazenar em cache falhas de teste e execuções de teste com
--runs_per_test
.
Os usuários que ativaram essa opção por padrão no
arquivo .bazelrc
podem achar as
abreviações -t
(ativadas) ou -t-
(desativadas)
convenientes para substituir o padrão em uma execução específica.
--check_tests_up_to_date
Essa opção diz ao Bazel para não executar os testes, mas apenas verificar e relatar os resultados armazenados em cache. Se houver algum teste que não tenha sido criado e executado anteriormente ou com resultados desatualizados (por exemplo, porque o código-fonte ou as opções de build mudaram), o Bazel vai relatar uma mensagem de erro ("resultado do teste não está atualizado"), registrar o status do teste como "SEM STATUS" (em vermelho, se a saída de cor estiver ativada) e retornar um código de saída diferente de zero.
Essa opção também implica o comportamento
[--check_up_to_date](#check-up-to-date)
.
Essa opção pode ser útil para verificações pré-envio.
--test_verbose_timeout_warnings
Essa opção diz ao Bazel para avisar explicitamente o usuário se o tempo limite de um teste for significativamente maior do que o tempo real de execução. Embora o tempo limite de um teste deva ser definido de modo que não seja instável, um teste com um tempo limite altamente generoso pode ocultar problemas reais que surgem inesperadamente.
Por exemplo, um teste que normalmente é executado em um ou dois minutos não precisa ter um tempo limite de ETERNAL ou LONG, já que eles são muito generosos.
Essa opção é útil para ajudar os usuários a decidir qual é um bom valor de tempo limite ou de verificação de integridade.
--[no]test_keep_going
Por padrão, todos os testes são executados até a conclusão. No entanto, se essa sinalização for desativada, o build será cancelado em qualquer teste não aprovado. As etapas de build
e as invocações de teste subsequentes não serão executadas, e as invocações em trânsito serã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 precisa ser tentado
se ele falhar por qualquer motivo. Um teste que inicialmente falha, mas eventualmente é bem-sucedido, é 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. Os testes que falharem em todas as tentativas permitidas serão
considerados como reprovados.
Por padrão, quando essa opção não é especificada ou é
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. Ele permite
no máximo 10 tentativas de teste para evitar abuso do sistema.
--runs_per_test=[regex@]number
Esta 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 fallback se aplica a cada uma delas de maneira independente).
O status de um destino 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 presente e duas execuções do mesmo fragmento retornarem PASS e FAIL, o teste vai receber um status instável, a menos que outras execuções com falha causem falha.
Se um único número for especificado, todos os testes serão executados essa quantidade de vezes.
Como alternativa, uma expressão regular pode ser especificada com a sintaxe regex@number. Isso restringe o efeito de --runs_per_test
a destinos
que correspondem ao regex (--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, não é), o Bazel detectará fragmentos
de teste instáveis usando --runs_per_test
. Se uma ou mais execuções para um único fragmento
falharem e uma ou mais execuções para a mesma passagem de fragmento, o destino será
considerado instável com a flag. Se não for especificado, o destino informará um
status de falha.
--test_summary=output_style
Especifica como o resumo do resultado do teste será exibido.
short
imprime os resultados de cada teste com o nome do arquivo que contém a saída do teste se ele falhar. Esse é o valor padrão.terse
, comoshort
, mas ainda mais curto: mostra apenas informações sobre testes que não foram aprovados.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.- O
none
não mostra o resumo do teste.
--test_output=output_style
Especifica como a saída do teste deve ser exibida:
summary
mostra um resumo se cada teste foi aprovado ou reprovado. Também mostra o nome do arquivo de registro de saída para testes com falha. O resumo será impresso no final da criação (durante a criação, serão exibidas apenas mensagens de progresso simples quando os testes forem iniciados, aprovados ou reprovados). Esse é o comportamento padrão.- O
errors
envia a saída combinada stdout/stderr de testes com falha apenas para a stdout imediatamente após a conclusão do teste, garantindo que a saída do teste de testes simultâneos não seja intercalada uma com a outra. Exibe um resumo no build conforme o resumo mostrado acima. all
é semelhante aerrors
, mas mostra a saída para todos os testes, incluindo os que foram aprovados.streamed
transmite a saída stdout/stderr de cada teste em tempo real.
--java_debug
Essa opção faz com que a máquina virtual Java de um teste Java aguarde 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 é ativada, fazendo com que os tempos de teste e outras
informações adicionais (como tentativas de teste) sejam impressas no resumo do teste. Se --noverbose_test_summary
for especificado, o resumo do teste incluirá apenas o nome do teste, o status do teste e o indicador de teste em cache e será formatado para permanecer dentro de 80 caracteres, quando possível.
--test_tmpdir=path
Especifica o diretório temporário para testes executados localmente. Cada teste será
executado em um subdiretório separado dentro desse diretório. O diretório será
limpado no início de cada comando bazel test
.
Por padrão, o bazel colocará esse diretório no diretório base de saída do Bazel.
--test_timeout=seconds
OU --test_timeout=seconds,seconds,seconds,seconds
Modifica o valor de tempo limite de todos os testes usando o número especificado de segundos como um novo valor de tempo limite. Se apenas um valor for fornecido, ele será usado para todas as categorias de tempo limite do teste.
Como alternativa, quatro valores separados por vírgula podem ser fornecidos, especificando tempos limite individuais para testes curtos, moderados, longos e eternos (nessa ordem). De qualquer forma, o valor zero ou um valor negativo para qualquer um dos tamanhos de teste será substituído pelo tempo limite padrão das categorias de tempo limite determinadas, conforme definido na página Como gravar testes. Por padrão, o Bazel usa esses tempos limite para todos os testes, inferindo o limite de tempo limite do tamanho do teste, independentemente do tamanho estar implícito ou explicitamente definido.
Os testes que declaram explicitamente a categoria de tempo limite como diferentes do tamanho receberão o mesmo valor como se esse tempo limite tivesse sido definido implicitamente pela tag de tamanho. Portanto, um teste de tamanho "pequeno" que declara um tempo limite "longo" terá o mesmo tempo limite efetivo que um teste "grande" 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
.
Ao contrário do comando bazel run
, não é possível transmitir argumentos de teste
diretamente como em bazel test -- target --logtostderr --v=3
. Isso ocorre porque
argumentos externos transmitidos para bazel test
são interpretados como outros destinos de
teste. Ou seja, --logtostderr
e --v=3
seriam interpretados como um
destino de teste. Essa ambiguidade não existe para um comando bazel run
, que aceita
apenas um destino.
--test_arg
pode ser transmitido para um comando bazel run
, mas será ignorado, a menos que o destino em execução seja um destino de teste. Como acontece com qualquer outra sinalização, se ela for transmitida em um
comando bazel run
após um token --
, ela não será processada pelo Bazel, mas
encaminhada literalmente para o destino executado.
--test_env=variable=_value_
OU --test_env=variable
Especifica outras variáveis que precisam ser injetadas no ambiente
para cada teste. Se value não for especificado, ele será herdado do ambiente shell usado para iniciar o comando bazel test
.
O ambiente pode ser acessado de dentro de 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 na frente do comando de teste antes de executá-lo. O command-prefix é dividido em palavras usando regras de tokenização de shell Bourne e, em seguida, a lista de palavras é anexada ao comando que será executado.
Se a primeira palavra for um rótulo totalmente qualificado (começa com //
), ela será criada. Em seguida, o rótulo é substituído pelo local executável correspondente que é anexado ao comando que será executado junto com as outras palavras.
Algumas ressalvas são aplicáveis:
- O PATH usado para executar testes pode ser diferente do PATH no seu ambiente. Portanto, pode ser necessário usar um caminho absoluto para o comando
--run_under
(a primeira palavra em command-prefix). - O
stdin
não está conectado, portanto, o--run_under
não pode ser usado para comandos interativos.
Por exemplo:
--run_under=/usr/bin/strace --run_under='/usr/bin/strace -c' --run_under=/usr/bin/valgrind --run_under='/usr/bin/valgrind --quiet --num-callers=20'
Seleção de teste
Conforme documentado em Opções de seleção de saída, é possível filtrar testes por tamanho, tempo limite, tag ou idioma. Um filtro de nome geral de conveniência 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 iguais a
bazel build
.
Como executar executáveis
O comando bazel run
é semelhante ao bazel build
, mas é usado para criar e executar um único destino. Esta é uma sessão típica:
% bazel run java/myapp:myapp -- --arg1 --arg2 Welcome to Bazel INFO: Loading package: java/myapp INFO: Loading package: foo/bar INFO: Loading complete. Analyzing... INFO: Found 1 target... ... Target //java/myapp:myapp up-to-date: bazel-bin/java/myapp:myapp INFO: Elapsed time: 0.638s, Critical Path: 0.34s INFO: Running command line: bazel-bin/java/myapp:myapp --arg1 --arg2 Hello there $EXEC_ROOT/java/myapp/myapp --arg1 --arg2
O bazel run
é semelhante, mas não idêntico, a invocar diretamente
o binário criado pelo Bazel. O comportamento dele é diferente dependendo se o
binário a ser invocado é um teste ou não.
Quando o binário não for um teste, o diretório de trabalho atual será a árvore de runfiles do binário.
Quando o binário é um teste, o diretório de trabalho atual é a raiz executiva,
e uma tentativa de boa-fé é feita para replicar o ambiente em que os testes de ambiente
costumam ser executados. No entanto, a emulação não é perfeita, e os testes com vários
fragmentos não podem ser executados dessa maneira. 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 em que o Bazel foi executado.
Eles podem ser usados, por exemplo, para interpretar nomes de arquivo na linha de comando de maneira fácil de usar.
Opções de bazel run
--run_under=command-prefix
Isso tem o mesmo efeito que a opção --run_under
para
bazel test
(veja acima),
exceto que se aplica ao comando executado por bazel
run
, e não aos testes em execução por bazel test
e não podem ser executados sob o rótulo.
Como 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 tornar os registros menos barulhentos, é possível
suprimir as saídas do próprio Bazel com as sinalizações --ui_event_filters
e
--noshow_progress
.
Exemplo:
bazel run --ui_event_filters=-info,-stdout,-stderr --noshow_progress //java/myapp:myapp
Como executar testes
bazel run
também pode executar binários de teste, que servem para
executar o teste em uma aproximação do ambiente descrito em
Como criar testes. Nenhum dos argumentos
--test_*
tem efeito durante a execução de um teste dessa maneira, exceto
--test_arg
.
Como limpar saídas de build
O comando clean
O Bazel tem um comando clean
, parecido com o do Make.
Ele exclui os diretórios de saída de todas as configurações de compilação 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 nenhuma
opção de linha de comando, o diretório de saída para todas as configurações
será limpo.
Lembre-se de que cada instância do Bazel está associada a um único espaço de trabalho. Portanto, o
comando clean
vai excluir todas as saídas de todas as compilações que você fez
com essa instância do Bazel nesse espaço de trabalho.
Para remover completamente toda a árvore de trabalho criada por uma instância
do Bazel, especifique a opção --expunge
. Quando
executado com --expunge
, o comando "clean" simplesmente
remove toda a árvore base de saída que, além da saída
de 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 rastreamentos de disco e memória de uma instância do Bazel, especifique:
% bazel clean --expunge
Como alternativa, é possível eliminar o em segundo plano usando
--expunge_async
. É seguro invocar um comando do Bazel
no mesmo cliente enquanto a eliminação assíncrona continua sendo executada.
O comando clean
é fornecido principalmente como um meio de
recuperar espaço em disco para espaços de trabalho que não são mais necessários.
As recompilações incrementais do Bazel podem não ser perfeitas. Portanto, clean
pode ser usado para recuperar um estado consistente quando surgem problemas.
No projeto do Bazel, esses problemas podem ser corrigidos, e
esses bugs têm alta prioridade de serem corrigidos. Se você
encontrar um build incremental incorreto, envie um relatório do bug e informe nas ferramentas
em vez de usar clean
.
Como consultar o gráfico de dependências
O Bazel inclui uma linguagem de consulta para fazer perguntas sobre o gráfico de dependência usado durante a compilação. 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 o cquery é executado 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 é baseada na ideia de operações algébricas sobre gráficos. Ela é documentada em detalhes
Referência de consulta do Bazel. Consulte esse documento para referência, exemplos e opções de linha de comando específicas para consultas.
A ferramenta de consulta aceita várias opções de linha de comando. --output
seleciona o formato de saída.
--[no]keep_going
(desativado por padrão) faz com que a ferramenta de consulta continue a progredir após erros. Esse comportamento poderá 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 que não sejam de destino sejam incluídas no
gráfico de dependência em que a consulta opera.
A opção --[no]implicit_deps
, ativada por padrão, faz com que
dependências implícitas sejam incluídas no gráfico de dependências em que a consulta opera. Uma
dependência implícita é aquela que não é especificada explicitamente no arquivo BUILD,
mas é adicionada pelo Bazel.
Exemplo: "Mostre os locais das definições (em arquivos BUILD) de todas as regras gerais 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 do build.
Ele opera no gráfico de destino configurado após a análise e expõe
informações sobre ações, artefatos e relações.
A ferramenta aceita várias opções de linha de comando.
--output
seleciona o formato de saída. O formato de saída padrão (text
) é legível. Use proto
ou textproto
para um formato legível por máquina.
O comando aquery é executado em um build normal do Bazel e herda
o conjunto de opções disponíveis durante uma compilação.
Ele oferece suporte ao mesmo conjunto de funções que também está disponível para o
query
tradicional, mas siblings
, buildfiles
e
tests
.
Para mais detalhes, consulte Consulta do gráfico de ações.
Comandos e opções diversos
help
O comando help
fornece ajuda on-line. Por padrão, ela
mostra um resumo dos comandos disponíveis e tópicos de ajuda, conforme mostrado em
Como criar com o Bazel.
A especificação de um argumento mostra ajuda detalhada para um tópico
específico. A maioria dos tópicos são comandos do Bazel, como build
ou query
, mas há alguns outros tópicos de ajuda
que não correspondem aos comandos.
--[no]long
(-l
)
Por padrão, bazel help [topic]
mostra 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 mostrados.
shutdown
Os processos do servidor do Bazel podem ser interrompidos usando o comando
shutdown
. Esse comando faz com que o servidor do Bazel seja encerrado assim que
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 Bazel são interrompidos automaticamente 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 nenhuma outra compilação ocorrerá em um determinado espaço de trabalho.
shutdown
aceita uma opção, --iff_heap_size_greater_than _n_
, que requer um argumento de número inteiro (em MB). Se especificado, isso torna o encerramento
condicional à quantidade de memória já consumida. Isso é útil para scripts que iniciam muitas versões, já que qualquer vazamento de memória no servidor do Bazel pode fazer com que ele falhe espúrio de vez em quando. A execução de uma reinicialização condicional antecipa essa condição.
info
O comando info
imprime vários valores associados à
instância do servidor do Bazel ou a uma configuração do 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 mostrar apenas
o valor dessa chave. Isso é especialmente conveniente ao criar scripts do Bazel, porque evita a necessidade de canalizar o resultado por sed -ne /key:/s/key://p
:
Dados independentes de configuração
release
: o rótulo de lançamento desta instância do Bazel ou "versão de desenvolvimento" se o binário não foi 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. Ele 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 e os resultados de 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 a compilação, além de ser o diretório de trabalho desses comandos. Se o diretório do espaço de trabalho for gravável, um link simbólico chamadobazel-<workspace>
será colocado nele, apontando para esse diretório.output_path
: o caminho absoluto para o diretório de saída abaixo da raiz de execução usado para todos os arquivos realmente gerados como resultado de comandos de build. Se o diretório do espaço de trabalho for gravável, um link simbólico chamadobazel-out
será colocado nele, apontando para esse diretório.server_pid
: o ID do processo do servidor do Bazel.server_log
: o caminho absoluto para o arquivo de registros 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 registro de comando. Contém os fluxos intercalados stdout e stderr do comando mais recente do Bazel. Observe que executarbazel info
substituirá o conteúdo desse arquivo, porque ele se torna o comando mais recente do Bazel. No entanto, o local do arquivo de registro do comando não será alterado, a menos que você mude a configuração das opções--output_base
ou--output_user_root
.used-heap-size
,committed-heap-size
,max-heap-size
: informa vários parâmetros de tamanho de heap do JVM. Respectivamente: memória usada atualmente, memória atualmente com garantia de estar disponível para a JVM no sistema, alocação máxima possível.gc-count
,gc-time
: a contagem cumulativa de coletas de lixo desde o início deste servidor do Bazel e o tempo gasto para executá-las. Esses valores não são redefinidos no início de cada build.package_path
: uma lista separada por dois-pontos de caminhos que seriam procurados por pacotes pelo bazel. Tem o mesmo formato do argumento de linha de comando do build--package_path
.
Exemplo: o ID de processo do servidor do Bazel.
% bazel info server_pid 1285
Dados específicos de configuração
Esses dados podem ser afetados pelas opções de configuração passadas
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 determinam o local do
diretório de saída de um build, a escolha do compilador etc.
bazel-bin
,bazel-testlogs
,bazel-genfiles
: informa o caminho absoluto para os diretóriosbazel-*
em que os programas gerados pelo build estão localizados. Em geral, ele é igual, mas não sempre, aos links simbólicosbazel-*
criados no diretório do espaço de trabalho base após um build bem-sucedido. No entanto, se o diretório do espaço de trabalho for somente leitura, nenhum link simbólicobazel-*
não poderá ser criado. Os scripts que usam o valor informado porbazel info
, em vez de presumir a existência do link simbólico, serão mais robustos.- O
ambiente"Make" completo. Se a sinalização
--show_make_env
for especificada, todas as variáveis no ambiente "Make" da configuração atual também serão exibidas (comoCC
,GLIBC_VERSION
etc.). Essas são as variáveis acessadas usando a sintaxe$(CC)
ouvarref("CC")
nos arquivos BUILD.
Exemplo: o compilador C++ da configuração atual.
Essa é a variável $(CC)
no ambiente "Make",
então a sinalização --show_make_env
é necessária.
% bazel info --show_make_env -c opt COMPILATION_MODE opt
Exemplo: o diretório de saída bazel-bin
da configuração
atual. Isso tem a garantia de estar correto mesmo nos casos em que
o link simbólico bazel-bin
não puder ser criado por algum motivo
(como se você estiver criando de um diretório somente leitura).
% bazel info --cpu=piii bazel-bin /var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/piii-opt/bin % bazel info --cpu=k8 bazel-bin /var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/k8-opt/bin
version
e --version
O comando "version" imprime detalhes sobre o binário criado do Bazel, incluindo a lista de mudanças em que ele foi criado e a data. Eles são particularmente úteis para determinar se você tem o Bazel mais recente 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 o binário não foi lançado. Muito útil ao informar bugs.
bazel --version
, sem outros argumentos, emite 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 de
qualquer lugar: não requer um diretório de espaço de trabalho.
mobile-install
O comando mobile-install
instala apps em dispositivos móveis.
Atualmente, apenas dispositivos Android que executam ART são compatíveis.
Consulte bazel mobile-install para mais informações.
As seguintes opções são compatíveis:
--incremental
Se definido, o Bazel tentará instalar o app de forma incremental, ou seja, apenas as
partes que mudaram desde a última compilação. Isso não pode atualizar recursos
referenciados em 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 a limitações da plataforma Android, é
responsabilidade do usuário saber quando esse comando é bom o suficiente e
quando uma instalação completa é necessária.
Se você estiver usando um dispositivo com o Marshmallow ou uma versão mais recente, considere a
sinalização --split_apks
.
--split_apks
Define se os APKs divididos para instalar e atualizar o app no dispositivo serão usados.
Funciona apenas com dispositivos que usam o Marshmallow ou superior. A sinalização
--incremental
não é necessária ao usar --split_apks
.
--start_app
Inicia o app em um estado limpo após a instalação. É equivalente a --start=COLD
.
--debug_app
Espera o depurador ser anexado 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 compatíveis são:
NO
Não inicia o app. Esse é o padrão.COLD
Inicia o app em um estado limpo após a instalação.WARM
Preserva e restaura o estado do aplicativo em instalações incrementais.DEBUG
aguarda o depurador antes de iniciar o app em um estado limpo após a instalação.
--adb=path
Indica o binário adb
a ser usado.
O padrão é usar o adb no SDK do Android especificado por
--android_sdk
.
--adb_arg=serial
Argumentos extras para adb
. Eles vêm antes do subcomando na
linha de comando e normalmente são usados para especificar em qual dispositivo instalar.
Por exemplo, para selecionar o dispositivo ou emulador Android a ser usado:
% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef
invoca adb
como
adb -s deadbeef install ...
--incremental_install_verbosity=number
O nível de detalhes da instalação incremental. Defina como 1 para que a geração de registros de depuração seja impressa no console.
dump
O comando dump
imprime um despejo do estado interno do servidor do Bazel em stdout. Esse comando é destinado principalmente ao uso por desenvolvedores do Bazel. Portanto, a saída dele não é especificada e está sujeita a alterações.
Por padrão, o comando apenas imprime uma mensagem de ajuda descrevendo as possíveis opções para fazer o despejo de áreas específicas do estado do Bazel. Para despejar o estado interno, pelo menos uma das opções precisa ser especificada.
As seguintes opções são aceitas:
--action_cache
despeja o conteúdo do cache de ação.--packages
despeja o conteúdo do cache do pacote.--skyframe
despeja o estado do gráfico de dependências interno do Bazel.--rules
descarta o resumo da regra para cada regra e classe de aspecto, incluindo contagens e contagens de ações. Isso inclui tanto as regras nativas quanto as Starlark. Se o rastreamento de memória estiver ativado, o consumo de memória das regras também será exibido.--skylark_memory
despeja um arquivo .gz compatível com pprof para o caminho especificado. Ative o rastreamento de memória para que isso funcione.
Monitoramento de memória
Alguns comandos dump
exigem rastreamento de memória. Para ativar esse recurso, é preciso passar
as flags de inicialização para o Bazel:
--host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar
--host_jvm_args=-DRULE_MEMORY_TRACKER=1
O java-agent é verificado no Bazel em
third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar
. Portanto, ajuste $BAZEL
para onde você mantém o repositório do Bazel.
Não se esqueça de continuar passando essas opções para o Bazel em cada comando, ou o servidor será reiniciado.
Exemplo:
% bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \ --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \ build --nobuild <targets> # Dump rules % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \ --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \ dump --rules # Dump Starlark heap and analyze it with pprof % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \ --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \ dump --skylark_memory=$HOME/prof.gz % pprof -flame $HOME/prof.gz
analyze-profile
O comando analyze-profile
analisa um
perfil de rastro JSON coletado anteriormente
durante uma invocação do Bazel.
canonicalize-flags
O comando canonicalize-flags
, que recebe 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 canônicas à mesma nova lista.
A opção --for_command
pode ser usada para selecionar comandos
diferentes. No momento, apenas build
e test
são
compatíveis. As opções não compatíveis com o comando fornecido causam um erro.
Como exemplo:
% bazel canonicalize-flags -- --config=any_name --test_tag_filters="-lint" --config=any_name --test_tag_filters=-lint
Opções de inicialização
As opções descritas nesta seção afetam a inicialização da máquina virtual Java usada pelo processo do servidor do Bazel e se aplicam a todos os comandos subsequentes processados por esse servidor. Se já houver um servidor do Bazel em execução e as opções de inicialização não corresponderem, 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 listá-los em um arquivo .bazelrc
.
--output_base=dir
Essa opção requer um argumento de caminho, que precisa especificar um diretório gravável. O Bazel usará esse local para gravar toda a saída. A base de saída também é a chave pela qual o cliente localiza o servidor do Bazel. Ao alterar a base de saída, você altera o servidor que manipulará o comando.
Por padrão, a base de saída é derivada do nome de login do usuário
e do nome do diretório do espaço de trabalho (na verdade, o resumo MD5 dele).
Um valor típico tem a seguinte aparência:
/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
Neste comando, os dois comandos do Bazel são executados simultaneamente (por causa do
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 em ambos os comandos,
as duas solicitações seriam enviadas para o mesmo servidor, que as processaria
sequencialmente: criando //foo
primeiro, seguido
de um build incremental de //bar
.
--output_user_root=dir
Aponta para o diretório raiz em que as bases de saída e instalação são criadas. O diretório não pode existir ou ser de propriedade do usuário que faz a chamada. Antes, isso podia apontar para um diretório compartilhado entre vários usuários, mas não é mais permitido. Isso poderá ser permitido assim que o problema 11100 for resolvido.
Se a opção --output_base
for especificada, ela modificará
o uso de --output_user_root
para calcular a base de saída.
O local de base da instalação é calculado com base em
--output_user_root
, mais a identidade MD5 dos binários incorporados
do Bazel.
Você pode usar a opção --output_user_root
para escolher um
local de base alternativo para todas as saídas do Bazel (base de instalação e
de saída) se houver um local melhor no layout do seu 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 deve 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 sinalização não afeta as JVMs usadas por subprocessos do Bazel, como aplicativos, testes, ferramentas e assim por diante. Use as opções de build --javabase ou --host_javabase.
Essa flag era chamada de --host_javabase
(às vezes chamada de
--host_javabase
do "lado esquerdo"), mas foi renomeada para evitar confusão com a
flag de build --host_javabase (às vezes chamada de
--host_javabase
do "lado direito").
--host_jvm_args=string
Especifica uma opção de inicialização a ser transmitida para a máquina virtual Java na qual 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, que serão interpretadas como um argumento da JVM separado, mas esse recurso será descontinuado em breve.
Que isso não afeta JVMs usadas por subprocessos do Bazel: aplicativos, testes, ferramentas e assim por diante. Para transmitir
opções de JVM para programas Java executáveis, sejam executados por bazel
run
ou na linha de comando, use
o argumento --jvm_flags
, que
todos os programas java_binary
e java_test
oferecem suporte. 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 (link em inglês). Isso é destinado principalmente aos desenvolvedores do Bazel.
--autodetect_server_javabase
Essa opção faz com que o Bazel procure automaticamente um JDK instalado na inicialização
e volte 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 de lote faz com que o Bazel não use o modo cliente/servidor padrão. Em vez disso, ele executa um processo bazel java para um único comando, que é usado para semânticas mais previsíveis com relação ao processamento de sinais, controle de jobs e herança de variável de ambiente. Além disso, é necessário para executar o bazel em uma cadeia chroot.
O modo de lote mantém a semântica de enfileiramento adequada dentro da mesma output_base. Ou seja, as invocações simultâneas sã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 elimina o servidor antes de processar o comando.
O Bazel será executado mais lentamente no modo de lote ou com as alternativas descritas acima. Isso ocorre porque, entre outras coisas, o cache do arquivo de build é residente na memória, de modo que não é preservado entre invocações em lote sequenciais. Portanto, o uso do modo de lote geralmente faz mais sentido nos casos em que o desempenho é menos crítico, como builds contínuos.
--max_idle_secs=n
Essa opção especifica quanto tempo, em segundos, o processo do servidor do Bazel
precisa aguardar após a última solicitação do cliente antes de sair. O
valor padrão é 10800 (3 horas). --max_idle_secs=0
fará com que o processo do servidor Bazel persista indefinidamente.
Essa opção pode ser usada por scripts que invocam o Bazel para garantir que
eles não saiam dos processos do servidor do Bazel na máquina de um usuário quando
não estariam sendo executados de outra forma.
Por exemplo, um script de pré-envio pode
invocar bazel query
para garantir que a mudança pendente
de um usuário não introduza dependências indesejadas. No entanto, se o
usuário não tiver feito uma versão recente nesse espaço de trabalho, não é
desejável que o script de pré-envio inicie um servidor do Bazel apenas
para que ele permaneça inativo pelo resto do dia.
Ao especificar um pequeno valor de --max_idle_secs
na solicitação de consulta, o script pode garantir que if ele fez com que um novo servidor fosse iniciado, esse servidor sairá imediatamente. No entanto, se já houver um servidor em execução, ele continuará sendo executado até ficar inativo pelo tempo normal. Obviamente, o timer de inatividade do servidor
existente será redefinido.
--[no]shutdown_on_low_sys_mem
Se ativado e --max_idle_secs
for definido como uma duração positiva,
após o servidor de build ficar inativo por um tempo, desligue o servidor quando o sistema estiver
com pouca memória. Somente no Linux.
Além de executar uma verificação de inatividade correspondente a max_idle_secs, o servidor de build começa a monitorar a memória disponível do sistema depois que o servidor fica inativo por algum tempo. Se a memória disponível do sistema ficar criticamente baixa, o servidor será fechado.
--[no]block_for_lock
Se ativado, o Bazel vai aguardar a conclusão de outros comandos que contêm o bloqueio do servidor antes de progredir. Se desativado, o Bazel sairá por engano se não puder adquirir o bloqueio imediatamente e prosseguir.
Os desenvolvedores podem usar isso em verificações de pré-envio para evitar esperas longas causadas por outro comando do Bazel no mesmo cliente.
--io_nice_level=n
Define um nível de 0 a 7 para a programação de E/S de melhor esforço. 0 é a prioridade mais alta, 7 é a menor. O programador antecipado só pode respeitar a prioridade 4. Valores negativos são ignorados.
--batch_cpu_scheduling
Use a programação de CPU batch
para o Bazel. Essa política é útil para
cargas de trabalho que não são interativas, mas não querem diminuir o valor delas.
Consulte "man 2 sched_setscheduler". Essa política pode melhorar a interatividade do sistema
em detrimento da capacidade do Bazel.
Opções diversas
--[no]announce_rc
Controla se o Bazel anuncia as opções de inicialização e as opções de comando lidas dos arquivos bazelrc na inicialização.
--color (yes|no|auto)
Essa opção determina se o Bazel usará cores para destacar a saída na tela.
Se essa opção for definida como yes
, a saída de cores será ativada.
Se essa opção for definida como auto
, o Bazel usará a saída de cor somente se a saída estiver sendo enviada a um terminal e a variável de ambiente TERM estiver definida como um valor diferente de dumb
, emacs
ou xterm-mono
.
Se essa opção for definida como no
, a saída de cor será desativada, independentemente de a saída ir para um terminal e da configuração da variável de ambiente TERM.
--config=name
Seleciona a seção de configuração extra dos
arquivos rc. Para o command
atual,
ele também extrai as opções de command:name
, se essa seção existir. Podem ser
especificadas 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, as expansões podem ser encadeadas).
--curses (yes|no|auto)
Essa opção determina se o Bazel usará controles de cursor
na saída da tela. Isso resulta em menos dados de rolagem e um stream
de saída do Bazel mais compacto e fácil de ler. Isso funciona bem com
--color
.
Se essa opção for definida como yes
, o uso de controles de cursor será ativado.
Se essa opção for definida como no
, o uso de controles de cursor será desativado.
Se essa opção for definida como auto
, o uso de controles de cursor será
ativado nas mesmas condições que para --color=auto
.
--[no]show_timestamps
Se especificado, um carimbo de data/hora é adicionado a cada mensagem gerada pelo Bazel especificando a hora em que a mensagem foi exibida.