O Bazel aceita várias opções. Algumas opções variam com frequência (por exemplo,
--subcommands
), enquanto outras permanecem as mesmas em vários builds (como
--package_path
). Para evitar especificar essas opções inalteradas para todos os builds
(e outros comandos), você pode especificar as opções em um arquivo de configuração, chamado
.bazelrc
.
Onde estão os arquivos .bazelrc
?
O Bazel procura arquivos de configuração opcionais nos locais a seguir,
na ordem mostrada abaixo. As opções são interpretadas nessa ordem. Portanto, as opções em arquivos posteriores podem substituir um valor de um arquivo anterior em caso de conflito. Todas as opções que controlam quais desses arquivos são carregados são
opções de inicialização, o que significa que precisam ocorrer após bazel
e
antes do comando (build
, test
etc.).
O arquivo RC do sistema, a menos que
--nosystem_rc
esteja presente.Caminho:
- No Linux/macOS/Unixes:
/etc/bazel.bazelrc
- No Windows:
%ProgramData%\bazel.bazelrc
Não haverá erro se o arquivo não existir.
Se outro local especificado pelo sistema for necessário, crie um binário do Bazel personalizado, substituindo o valor
BAZEL_SYSTEM_BAZELRC_PATH
em//src/main/cpp:option_processor
. O local especificado pelo sistema pode conter referências de variáveis de ambiente, como${VAR_NAME}
no Unix ou%VAR_NAME%
no Windows.- No Linux/macOS/Unixes:
O arquivo RC do espaço de trabalho, a menos que
--noworkspace_rc
esteja presente.Caminho:
.bazelrc
no diretório do espaço de trabalho (ao lado do arquivoWORKSPACE
principal).Não haverá erro se o arquivo não existir.
O arquivo RC inicial, a menos que
--nohome_rc
esteja presente.Caminho:
- No Linux/macOS/Unixes:
$HOME/.bazelrc
- No Windows:
%USERPROFILE%\.bazelrc
, se existir, ou%HOME%/.bazelrc
Não haverá erro se o arquivo não existir.
- No Linux/macOS/Unixes:
O arquivo RC especificado pelo usuário, se definido com
--bazelrc=file
Essa sinalização é opcional, mas também pode ser especificada várias vezes.
/dev/null
indica que todos os outros--bazelrc
s serão ignorados, o que é útil para desativar a pesquisa de um arquivo rc do usuário, como em builds de lançamento.Exemplo:
--bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc
x.rc
ey.rc
são lidos.z.rc
é ignorado devido ao/dev/null
anterior.
Além desse arquivo de configuração opcional, o Bazel procura um arquivo rc global. Para mais detalhes, consulte a seção do bazelrc global.
Sintaxe e semântica de .bazelrc
Como todos os arquivos "rc" do UNIX, o .bazelrc
é um arquivo de texto com uma gramática
baseada em linha. Linhas vazias e linhas que começam com #
(comentários) são ignoradas. Cada linha contém uma sequência de palavras, que são tokenizadas de acordo com as mesmas regras do shell Bourne.
Importações
As linhas que começam com import
ou try-import
são especiais. Use-as para carregar
outros arquivos "rc". Para especificar um caminho relativo à raiz do espaço de trabalho, escreva import %workspace%/path/to/bazelrc
.
A diferença entre import
e try-import
é que o Bazel falha se o
arquivo com import
está ausente (ou não pode ser lido), mas não para um
arquivo com try-import
.
Precedência de importação:
- As opções no arquivo importado têm precedência sobre as opções especificadas antes da instrução de importação.
- As opções especificadas após a instrução de importação têm precedência sobre as opções no arquivo importado.
- As opções nos arquivos importados posteriormente têm precedência em relação aos arquivos importados anteriormente.
Padrões de opção
A maioria das linhas de um Bazel define valores de opção padrão. A primeira palavra em cada linha especifica quando esses padrões são aplicados:
startup
: opções de inicialização, que vão antes do comando e são descritas embazel help startup_options
.common
: opções que precisam ser aplicadas a todos os comandos do Bazel com suporte a elas. Se um comando não for compatível com uma opção especificada dessa maneira, a opção será ignorada, desde que seja válida para algum outro comando do Bazel. Observe que isso se aplica apenas a nomes de opções: se o comando atual aceitar uma opção com o nome especificado, mas não for compatível com o valor especificado, ele falhará.always
: opções que se aplicam a todos os comandos do Bazel. Se um comando não for compatível com uma opção especificada dessa maneira, ele falhará.command
: comando do Bazel, comobuild
ouquery
, a que as opções se aplicam. Essas opções também se aplicam a todos os comandos herdados do comando especificado. Por exemplo,test
herda debuild
.
Cada uma dessas linhas pode ser usada mais de uma vez, e os argumentos que seguem a primeira palavra são combinados como se tivessem aparecido em uma única linha. Os usuários do CVS, outra ferramenta com uma interface de linha de comando "canivete suíço", encontrarão uma sintaxe semelhante à de .cvsrc
. Por exemplo, as linhas:
build --test_tmpdir=/tmp/foo --verbose_failures
build --test_tmpdir=/tmp/bar
são combinados como:
build --test_tmpdir=/tmp/foo --verbose_failures --test_tmpdir=/tmp/bar
de modo que as flags efetivas sejam --verbose_failures
e --test_tmpdir=/tmp/bar
.
Precedência da opção:
- As opções na linha de comando sempre têm precedência sobre as opções nos arquivos rc.
Por exemplo, se um arquivo rc informar
build -c opt
, mas a sinalização de linha de comando for-c dbg
, a sinalização de linha de comando terá precedência. No arquivo rc, a precedência é regida pela especificidade: as linhas para um comando mais específico têm precedência sobre as linhas para um comando menos específico.
A especificidade é definida pela herança. Alguns comandos herdam opções de outros comandos, tornando o comando herdado mais específico que o comando base. Por exemplo,
test
é herdado do comandobuild
. Portanto, todas as sinalizaçõesbazel build
são válidas parabazel test
e todas as linhasbuild
também se aplicam abazel test
, a menos que haja uma linhatest
para a mesma opção. Se o arquivo rc disser:test -c dbg --test_env=PATH
build -c opt --verbose_failures
então
bazel build //foo
vai usar-c opt --verbose_failures
ebazel test //foo
vai usar--verbose_failures -c dbg --test_env=PATH
.O gráfico de herança (especificidade) é:
- Cada comando é herdado de
common
- Os comandos a seguir herdam de (e são mais específicos que)
build
:test
,run
,clean
,mobile-install
,info
,print_action
,config
,cquery
eaquery
coverage
herda detest
- Cada comando é herdado de
Duas linhas que especificam opções para o mesmo comando com a mesma especificidade são analisadas na ordem em que aparecem no arquivo.
Como essa regra de precedência não corresponde à ordem do arquivo, isso ajuda a facilitar a leitura se você seguir a ordem de precedência nos arquivos rc: começar com opções
common
na parte de cima e terminar com os comandos mais específicos na parte de baixo do arquivo. Dessa forma, a ordem em que as opções são lidas é a mesma em que são aplicadas, o que é mais intuitivo.
Os argumentos especificados em uma linha de um arquivo rc podem incluir argumentos que não são opções, como nomes de destinos de build e assim por diante. Elas, como as opções especificadas nos mesmos arquivos, têm precedência menor do que seus irmãos na linha de comando e sempre são anexadas à lista explícita de argumentos que não são de opção.
--config
Além de definir padrões de opções, o arquivo rc pode ser usado para agrupar opções
e fornecer uma abreviação para agrupamentos comuns. Para fazer isso, adicione um sufixo :name
ao comando. Essas opções são ignoradas por padrão, mas serão
incluídas quando a opção --config=name
estiver presente,
seja na linha de comando ou em um arquivo .bazelrc
, recursivamente, mesmo dentro de
outra definição de configuração. As opções especificadas por command:name
só serão
expandidas para os comandos aplicáveis, na ordem de precedência descrita acima.
--config=foo
se expande para as opções definidas nos
arquivos rc "no local" para que as opções
especificadas para a configuração tenham a mesma precedência que a opção --config=foo
teve.
Essa sintaxe não se estende ao uso de startup
para definir
opções de inicialização. A configuração startup:config-name --some_startup_option
no arquivo .bazelrc será ignorada.
--enable_platform_specific_config
As configurações específicas da plataforma no .bazelrc
podem ser ativadas automaticamente usando
--enable_platform_specific_config
. Por exemplo, se o SO do host for o Linux e o comando build
for executado, a configuração build:linux
será ativada automaticamente. Os identificadores de SO aceitos são linux
, macos
, windows
, freebsd
e openbsd
. Ativar essa sinalização é equivalente a usar --config=linux
no Linux, --config=windows
no Windows e assim por diante.
Consulte --enable_platform_specific_config.
Exemplo
Confira este exemplo do arquivo ~/.bazelrc
:
# Bob's Bazel option defaults
startup --host_jvm_args=-XX:-UseParallelGC
import /home/bobs_project/bazelrc
build --show_timestamps --keep_going --jobs 600
build --color=yes
query --keep_going
# Definition of --config=memcheck
build:memcheck --strip=never --test_timeout=3600
Outros arquivos que regem o comportamento do Bazel
.bazelignore
É possível especificar diretórios no espaço de trabalho que você quer que o Bazel ignore, como projetos relacionados que usam outros sistemas de compilação. Coloque um arquivo chamado
.bazelignore
na raiz do espaço de trabalho
e adicione os diretórios que você quer que o Bazel ignore, um por
linha. As entradas são relativas à raiz do espaço de trabalho.
Arquivo global do Bazel
O Bazel lê os arquivos bazelrc opcionais nesta ordem:
- Arquivo rc-file do sistema localizado em
etc/bazel.bazelrc
. - Workspace rc-file localizado em
$workspace/tools/bazel.rc
. - Arquivo rc-inicial localizado em
$HOME/.bazelrc
Cada arquivo Bazelrc listado aqui tem uma sinalização correspondente que pode ser usada para
desativá-los (por exemplo, --nosystem_rc
, --noworkspace_rc
, --nohome_rc
). Você também
pode fazer com que o Bazel ignore todos os bazelrcs passando a opção
de inicialização --ignore_all_rc_files
.