Gravar arquivos de configuração bazelrc

O Bazel aceita muitas 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 em todos os builds (e outros comandos), é possível especificar 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 seguintes locais, 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 se houver um conflito. Todas as opções que controlam quais desses arquivos são carregados são opções de inicialização, o que significa que elas precisam aparecer depois de bazel e antes do comando (build, test etc.).

1. 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 é um erro se esse arquivo não existir.

   Se for necessário outro local especificado pelo sistema, 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.

2. 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 arquivo principal MODULE.bazel).

   Não é um erro se esse arquivo não existir.

3. O arquivo RC da casa, 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 é um erro se esse arquivo não existir.

4. O arquivo RC da variável de ambiente, se o caminho estiver definido com a variável de ambiente BAZELRC.

   A variável de ambiente pode incluir vários caminhos separados por vírgulas.

5. O arquivo RC especificado pelo usuário, se especificado com --bazelrc=file

   Essa flag é opcional, mas também pode ser especificada várias vezes.

   /dev/null indica que todos os --bazelrcs futuros 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 e y.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 global bazelrc.

Sintaxe e semântica de .bazelrc

Como todos os arquivos "rc" do UNIX, o arquivo .bazelrc é um arquivo de texto com uma gramática baseada em linhas. 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 import estiver faltando (ou não puder ser lido), mas não se o arquivo try-import estiver faltando.

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 em arquivos importados depois têm precedência sobre os arquivos importados antes.

Padrões de opções

A maioria das linhas de um bazelrc 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êm antes do comando e são descritas em bazel help startup_options.
• common: opções que devem ser aplicadas a todos os comandos do Bazel que as aceitam. Se um comando não for compatível com uma opção especificada dessa forma, ela será ignorada desde que seja válida para algum outro comando do Bazel. Isso só se aplica 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 vai 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 forma, ele vai falhar.
• command: comando do Bazel, como build ou query, a que as opções se aplicam. Essas opções também se aplicam a todos os comandos que herdam do comando especificado. Por exemplo, test herda de build.

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. Usuários do CVS, outra ferramenta com uma interface de linha de comando "canivete suíço", vão achar a sintaxe semelhante à do .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

Portanto, as flags efetivas são --verbose_failures e --test_tmpdir=/tmp/bar.

Precedência de 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 diz build -c opt, mas a flag da linha de comando é -c dbg, a flag da linha de comando tem precedência.

• No arquivo rc, a precedência é regida pela especificidade: linhas de um comando mais específico têm precedência sobre linhas de um comando menos específico.

  A especificidade é definida por herança. Alguns comandos herdam opções de outros, tornando o comando de herança mais específico do que o comando de base. Por exemplo, test herda do comando build. Portanto, todas as flags bazel build são válidas para bazel test, e todas as linhas build também se aplicam a bazel test, a menos que haja uma linha test 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, e bazel test //foo vai usar --verbose_failures -c dbg --test_env=PATH.

  O gráfico de herança (especificidade) é:

  • Todos os comandos herdam de common
  • Os seguintes comandos herdam de (e são mais específicos que) build: test, run, clean, mobile-install, info, print_action, config, cquery e aquery.
  • coverage, fetch e vendor herdam de test

• Duas linhas que especificam opções para o mesmo comando com igual especificidade são analisadas na ordem em que aparecem no arquivo.

• Como essa regra de precedência não corresponde à ordem dos arquivos, é melhor seguir a ordem de precedência nos arquivos rc: comece com as opções common na parte de cima e termine com os comandos mais específicos na parte de baixo do arquivo. Assim, 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. Esses argumentos, assim como as opções especificadas nos mesmos arquivos, têm precedência menor do que os irmãos na linha de comando e sempre são adicionados antes da lista explícita de argumentos que não são opções.

--config

Além de definir opções padrão, o arquivo rc pode ser usado para agrupar opções e fornecer um atalho para agrupamentos comuns. Para 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, de forma recursiva, mesmo dentro de outra definição de configuração. As opções especificadas por command:name só serão expandidas para comandos aplicáveis, na ordem de precedência descrita acima.

--config=foo se expande para as opções definidas nos arquivos rc "in-place", para que as opções especificadas para a configuração tenham a mesma precedência que a opção --config=foo.

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 .bazelrc será ignorada.

--enable_platform_specific_config

No .bazelrc, é possível usar configurações específicas da plataforma que serão ativadas automaticamente com base no SO do host. Por exemplo, se o SO do host for Linux e o comando build for executado, a configuração build:linux será ativada automaticamente. Os identificadores de SO compatíveis são linux, macos, windows, freebsd e openbsd.

Isso é equivalente a usar --config=linux no Linux, --config=windows no Windows e assim por diante. Isso pode ser desativado com --enable_platform_specific_config=false.

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

O arquivo .bazelignore não permite semântica de glob. O Bazel 8 apresenta o arquivo REPO.bazel, que permite outra diretiva, ignore_directories(). Ele usa uma lista de diretórios a serem ignorados, assim como o .bazelignore, mas com semântica de glob. Consulte #24203.

O arquivo global bazelrc

O Bazel lê os arquivos bazelrc opcionais nesta ordem:

1. Arquivo rc do sistema localizado em /etc/bazel.bazelrc.
2. Arquivo rc do espaço de trabalho localizado em $workspace/tools/bazel.rc.
3. Arquivo rc doméstico localizado em $HOME/.bazelrc

Cada arquivo bazelrc listado aqui tem uma flag 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 transmitindo a opção de inicialização --ignore_all_rc_files.