Como chamar o Bazel usando scripts

É possível chamar o Bazel de scripts para realizar 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 a serem considerados para tornar seus scripts mais robustos.

Como escolher a base de saída

A opção --output_base controla onde o processo do Bazel deve gravar as saídas de um build, bem como vários arquivos de trabalho usados internamente pelo Bazel, um dos quais é 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 base de saída correto para o script depende de vários fatores. Se você precisar colocar as saídas do 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 sua situação, pode ser útil que cada instância do script espere a vez ou usar --output_base para executar vários servidores Blaze e usá-los.

Se você usar o valor base de saída padrão, vai disputar o mesmo bloqueio usado pelos comandos interativos do Bazel do usuário. Se o usuário emitir comandos de longa duração, como builds, o script terá que esperar que esses comandos sejam concluídos 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 especificar --max_idle_secs=5 para que os servidores inativos 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 de linha de comando, sinalizações ou combinação de comandos incorretas ou ilegais ou variáveis de ambiente incorretas. A linha de comando precisa ser modificada.
• 8 - O build foi interrompido, mas terminamos com um desligamento ordenado.
• 9 - O bloqueio do servidor é mantido e --noblock_for_lock foi transmitido.

• 32 - Falha no ambiente externo não nesta máquina.

• 33 - O Bazel ficou sem memória e falhou. 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 processada / erro interno do Bazel.

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

• 39 - Os blobs exigidos 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 de 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 no build.
• 3 - Build OK, mas alguns testes falharam ou atingiram o tempo limite.
• 4 - Build bem-sucedido, mas nenhum teste foi encontrado, mesmo que o teste tenha sido solicitado.

Para bazel run:

• 1 - Falha no build.
• 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 e, portanto, os resultados da operação não são 100% confiáveis. Isso provavelmente ocorre devido a uma opção --keep_going na linha de comando.
• 7 - Falha no comando.

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

Como ler o arquivo .bazelrc

Por padrão, o Bazel lê o .bazelrc arquivo do diretório base do espaço de trabalho ou do diretório inicial do usuário. Se isso é desejável ou não é uma escolha para o 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 realizar um build usando as configurações preferidas do usuário, o comportamento padrão será melhor.

Registro de comando

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

bazel info command_log

O arquivo de registro de comandos contém os fluxos stdout e stderr intercalados do comando Bazel mais recente. A execução de bazel info vai substituir o conteúdo desse arquivo, já que ele se torna o comando Bazel mais recente. No entanto, o local do arquivo de registro de comandos não será alterado, 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 muitas finalidades. Duas opções que podem ser úteis para o script são --noshow_progress que suprime as 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 com sucesso e o local dos arquivos de saída criados. Especifique um valor muito grande de n se você depender de ssas mensagens.

Como solucionar problemas de desempenho por criação de perfil

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