Como encontrar comportamentos não herméticos nas regras do espaço de trabalho

No exemplo a seguir, uma máquina host é a máquina em que o Bazel é executado.

Ao usar a execução remota, as etapas de versão e/ou teste reais não estão acontecendo na máquina host, mas são enviadas para o sistema de execução remota. No entanto, as etapas envolvidas na resolução de regras do espaço de trabalho estão acontecendo na máquina host. Se as regras de espaço de trabalho acessam informações sobre a máquina host para uso durante a execução, é provável que sua versão seja interrompida devido a incompatibilidades entre os ambientes.

Como parte da adaptação de regras do Bazel para execução remota, é necessário encontrar e corrigir essas regras do espaço de trabalho. Nesta página, descrevemos como encontrar regras de espaço de trabalho potencialmente problemáticas usando o registro do espaço de trabalho.

Como encontrar regras não herméticas

As regras do espaço de trabalho permitem que o desenvolvedor adicione dependências a espaços de trabalho externos, mas são ricas o suficiente para permitir que o processamento arbitrário aconteça no processo. Todos os comandos relacionados estão acontecendo localmente e podem ser uma fonte potencial de não hermeticidade. Geralmente, um comportamento não hermético é introduzido no repository_ctx, o que permite interagir com a máquina host.

A partir do Bazel 0.18, é possível conseguir um registro de algumas ações potencialmente não herméticas. Basta adicionar a sinalização --experimental_workspace_rules_log_file=[PATH] ao seu comando do Bazel. Aqui, [PATH] é um nome de arquivo em que o registro será criado.

Observações:

• o log captura os eventos à medida que são executados. Se algumas etapas forem armazenadas em cache, elas não aparecerão no registro. Portanto, para receber um resultado completo, não se esqueça de executar bazel clean --expunge com antecedência.

• Às vezes, as funções podem ser executadas novamente. Nesse caso, os eventos relacionados aparecerão no registro várias vezes.

• No momento, as regras do Workspace registram apenas eventos do Starlark.

Para descobrir o que foi executado durante a inicialização do espaço de trabalho:

1. Execute bazel clean --expunge. Esse comando limpará o cache local e todos os repositórios em cache, garantindo que toda a inicialização seja executada novamente.

2. Adicione --experimental_workspace_rules_log_file=/tmp/workspacelog ao seu comando do Bazel e execute a versão.

   Isso produz um arquivo proto binário listando mensagens do tipo WorkspaceEvent.

3. Faça o download do código-fonte do Bazel e vá para a pasta do Bazel usando o comando abaixo. Você precisa do código-fonte para analisar o registro do espaço de trabalho com o analisador do espaço de trabalho.

   git clone https://github.com/bazelbuild/bazel.git
   cd bazel
   

4. No repositório do código-fonte do Bazel, converta todo o registro do espaço de trabalho em texto.

   bazel build src/tools/workspacelog:parser
   bazel-bin/src/tools/workspacelog/parser --log_path=/tmp/workspacelog > /tmp/workspacelog.txt
   

5. A saída pode ser bastante detalhada e incluir resultados de regras integradas do Bazel.

   Para excluir regras específicas do resultado, use a opção --exclude_rule. Exemplo:

   bazel build src/tools/workspacelog:parser
   bazel-bin/src/tools/workspacelog/parser --log_path=/tmp/workspacelog \
       --exclude_rule "//external:local_config_cc" \
       --exclude_rule "//external:dep" > /tmp/workspacelog.txt
   

6. Abra /tmp/workspacelog.txt e verifique se há operações não seguras.

O registro consiste em mensagens do WorkspaceEvent que descrevem algumas ações potencialmente não herméticas realizadas em um repository_ctx.

As ações que foram destacadas como possivelmente não herméticas são:

• execute: executa um comando arbitrário no ambiente de host. Verifique se eles podem introduzir dependências no ambiente do host.

• download, download_and_extract: para garantir builds herméticos, verifique se sha256 está especificado

• file, template: ele não é hermético, mas pode ser um mecanismo para inserir dependências no ambiente do host no repositório. Verifique se você entende a origem da entrada e que ela não depende do ambiente do host.

• os: ele não é hermético, mas uma maneira fácil de ter dependências no ambiente de host. Um build hermético geralmente não chama isso. Ao avaliar se o uso é hermético, lembre-se de que isso é executado no host, e não nos workers. Conseguir especificações do ambiente do host geralmente não é uma boa ideia para versões remotas.

• symlink: geralmente é seguro, mas procure sinalizações em vermelho. Todos os links simbólicos para fora do repositório ou para um caminho absoluto causariam problemas no worker remoto. Se o link simbólico for criado com base nas propriedades da máquina host, provavelmente também será problemático.

• which: a verificação de programas instalados no host geralmente é um problema, já que os workers podem ter configurações diferentes.