Gravar arquivos de configuração do Bazelrc

Informar um problema Ver código-fonte

O Bazel aceita muitas opções. Algumas opções são variadas com frequência (por exemplo, --subcommands), enquanto outras permanecem as mesmas em várias versões (como --package_path). Para evitar a especificação dessas opções inalteradas para cada versão (e outros comandos), você pode 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 surgir um conflito. Todas as opções que controlam quais desses arquivos são carregados são as opções de inicialização, o que significa que elas precisam ocorrer após 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 o arquivo não existir.

    Se outro local especificado pelo sistema for necessário, crie um binário personalizado do Bazel 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 WORKSPACE principal).

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

  3. O arquivo RC principal, 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 o arquivo não existir.

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

    Essa sinalização é opcional, mas também pode ser especificada várias vezes.

    /dev/null indica que todos os outros --bazelrcs serão ignorados, o que é útil para desativar a pesquisa de um arquivo rc de usuário, como em builds de lançamento.

    Por 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 do 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 linha. As linhas e linhas vazias 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 de 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 falhará se o arquivo de import estiver ausente (ou não puder ser lido), mas não para um arquivo de 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 depois têm precedência em relação aos importados anteriormente.

Opções padrão

A maioria das linhas de um Bazelrc define valores de opção padrão. A primeira palavra de cada linha especifica quando esses padrões são aplicados:

  • startup: opções de inicialização que aparecem antes do comando e que são descritas em bazel help startup_options.
  • common: opções que precisam ser aplicadas a todos os comandos do Bazel compatíveis. 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 alguns outros comandos do Bazel. Observe que 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 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, como build ou query, ao qual as opções se aplicam. Essas opções também se aplicam a todos os comandos herdados 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. Os usuários do CVS, outra ferramenta com uma interface de linha de comando "kniser do exército suíço", encontrarão a sintaxe semelhante à de .cvsrc. Por exemplo, as linhas:

build --test_tmpdir=/tmp/foo --verbose_failures
build --test_tmpdir=/tmp/bar

são combinadas como:

build --test_tmpdir=/tmp/foo --verbose_failures --test_tmpdir=/tmp/bar

então as sinalizações efetivas são --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 diz build -c opt, mas a sinalização da linha de comando é -c dbg, a sinalização da linha de comando tem precedência.

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

    A especificidade é definida pela herança. Alguns comandos herdam opções de outros, o que torna o comando herdado mais específico do que o comando base. Por exemplo, test herda do comando build, então todas as sinalizações 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 diz:

    test -c dbg --test_env=PATH
build -c opt --verbose_failures

    então bazel build //foo usará -c opt --verbose_failures e bazel test //foo usará --verbose_failures -c dbg --test_env=PATH.

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

    • Todos os comandos são herdados 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 e aquery
    • coverage herda de test

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

  • Como essa regra de precedência não corresponde à ordem do arquivo, isso facilitará a leitura se você seguir a ordem de precedência dentro de arquivos rc: comece com as opções de common na parte superior e termine com os comandos mais específicos na parte inferior do arquivo. Dessa forma, a ordem em que as opções são lidas é a mesma em que elas 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 os nomes dos destinos de compilação e assim por diante. Assim como as opções especificadas nos mesmos arquivos, eles têm menor precedência que os irmãos na linha de comando e são sempre prefixados com a lista explícita de argumentos que não são de opção.

--config

Além de definir padrões de opção, o arquivo rc pode ser usado para agrupar opções e fornecer uma abreviação para agrupamentos comuns. Isso é feito adicionando 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 serão expandidas apenas 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.

Essa sintaxe não se estende ao uso de startup para definir opções de inicialização. A definição de startup:config-name --some_startup_option no .bazelrc será ignorada.

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.

O arquivo global do Bazelrc

O Bazel lê arquivos bazelrc opcionais nesta ordem:

  1. Arquivo rc do sistema localizado em etc/bazel.bazelrc.
  2. Arquivo rc do Workspace localizado em $workspace/tools/bazel.rc.
  3. Arquivo rc doméstico localizado em $HOME/.bazelrc

Cada arquivo do 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 o Bazel ignorar todos os Bazelrcs transmitindo a opção de inicialização --ignore_all_rc_files.