Como chamar o Bazel usando scripts

É possível chamar o Bazel de scripts para executar um build, executar testes ou consultar o gráfico de dependências. O Bazel foi projetado para permitir a criação de scripts eficazes, mas esta seção lista alguns detalhes que você precisa considerar para tornar seus scripts mais robustos.

Como escolher a base de saída

A opção --output_base controla onde o processo do Bazel precisa gravar as saídas de um build, além de vários arquivos de trabalho usados internamente pelo Bazel. Um deles é um bloqueio que protege contra a mutação simultânea da base de saída por vários processos do Bazel.

A escolha do diretório de saída correto para o script depende de vários fatores. Se você precisar colocar as saídas de build em um local específico, isso vai determinar a base de saída que você precisa usar. Se você estiver fazendo uma chamada "somente leitura" para o Bazel (como bazel query), os fatores de bloqueio serão mais importantes. Em particular, se você precisar executar várias instâncias do script simultaneamente, lembre-se de que cada processo do servidor Blaze pode processar no máximo uma invocação por vez. Dependendo da situação, pode ser melhor que cada instância do script aguarde a vez ou que você use --output_base para executar e usar vários servidores Blaze.

Se você usar o valor de base de saída padrão, vai competir pelo mesmo bloqueio usado pelos comandos interativos do Bazel do usuário. Se o usuário emitir comandos de longa duração, como builds, seu script terá que esperar a conclusão desses comandos antes de continuar.

Observações sobre o modo de servidor

Por padrão, o Bazel usa um processo de servidor de longa duração como uma otimização. Ao executar o Bazel em um script, não se esqueça de chamar shutdown quando terminar de usar o servidor ou especifique --max_idle_secs=5 para que os servidores ociosos sejam desligados imediatamente.

Qual código de saída vou receber?

O Bazel tenta diferenciar falhas devido ao código-fonte em consideração de erros externos que impedem a execução adequada do Bazel. A execução do Bazel pode resultar nos seguintes códigos de saída:

Códigos de saída comuns a todos os comandos:

• 0: sucesso
• 2: problema na linha de comando, flags incorretas ou ilegais ou combinação de comandos ou variáveis de ambiente incorretas. Sua linha de comando precisa ser modificada.
• 8: o build foi interrompido, mas encerrado de forma ordenada.
• 9: o bloqueio do servidor é mantido e --noblock_for_lock foi transmitido.

• 32: falha no ambiente externo não está nesta máquina.

• 33: o Bazel ficou sem memória e travou. Você precisa modificar a linha de comando.

• 34: reservado para uso interno do Google.

• 35: reservado para uso interno do Google.

• 36: problema ambiental local, suspeita de permanente.

• 37: exceção não tratada / erro interno do Bazel.

• 38: erro temporário ao publicar resultados no serviço de eventos de build.

• 39: os blobs necessários pelo Bazel são removidos do cache remoto.

• 41-44: reservado para uso interno do Google.

• 45: erro persistente ao publicar resultados no serviço de eventos do build.

• 47: reservado para uso interno do Google.

• 49: reservado para uso interno do Google.

Códigos de retorno para comandos bazel build, bazel test:

• 1: falha na criação.
• 3: a compilação foi concluída, mas alguns testes falharam ou expiraram.
• 4: o build foi concluído, mas nenhum teste foi encontrado, mesmo que o teste tenha sido solicitado.

Para bazel run:

• 1: falha na criação.
• Se o build for bem-sucedido, mas o subprocesso executado retornar um código de saída diferente de zero, ele também será o código de saída do comando.

Para bazel query:

• 3: sucesso parcial, mas a consulta encontrou um ou mais erros no conjunto de arquivos BUILD de entrada. Portanto, os resultados da operação não são 100% confiáveis. Isso provavelmente se deve a uma opção --keep_going na linha de comando.
• 7: falha no comando.

Futuras versões do Bazel podem adicionar outros códigos de saída, substituindo o código de saída de falha genérica 1 por um valor diferente que não seja zero com um significado específico. No entanto, todos os valores de saída diferentes de zero sempre vão constituir um erro.

Como ler o arquivo .bazelrc

Por padrão, o Bazel lê o arquivo .bazelrc do diretório base do espaço de trabalho ou do diretório inicial do usuário. A decisão de usar ou não essa opção é uma escolha do script. Se o script precisar ser perfeitamente hermético (como ao fazer builds de lançamento), desative a leitura do arquivo .bazelrc usando a opção --bazelrc=/dev/null. Se você quiser executar um build usando as configurações preferidas do usuário, o comportamento padrão é melhor.

Registro de comando

A saída do Bazel também está disponível em um arquivo de registro de comando, que pode ser encontrado com o seguinte comando:

bazel info command_log

O arquivo de registro de comando contém os streams stdout e stderr intercalados do comando mais recente do Bazel. A execução de bazel info vai substituir o conteúdo desse arquivo, já que ele se torna o comando mais recente do Bazel. No entanto, o local do arquivo de registro de comando não vai mudar, a menos que você mude a configuração das opções --output_base ou --output_user_root.

Como analisar a saída

A saída do Bazel é bastante fácil de analisar para várias finalidades. Duas opções que podem ser úteis para seu script são --noshow_progress, que suprime mensagens de progresso, e --show_result n, que controla se as mensagens "build up-to-date" são impressas ou não. Essas mensagens podem ser analisadas para descobrir quais destinos foram criados e o local dos arquivos de saída criados. Especifique um valor muito grande de n se você depender dessas mensagens.

Resolver problemas de desempenho com a criação de perfis

Consulte a seção Criação de perfis de desempenho.