Arquivo de bloqueio do Bazel

O recurso de arquivo de bloqueio no Bazel permite a gravação de versões ou dependências específicas de bibliotecas de software ou pacotes exigidos por um projeto. Ele faz isso armazenando o resultado da resolução do módulo e da avaliação da extensão. O arquivo de bloqueio promove builds reproduzíveis, garantindo ambientes de desenvolvimento consistentes. Além disso, ele melhora a eficiência do build, permitindo que o Bazel pule as partes do processo de resolução que não são afetadas por mudanças nas dependências do projeto. Além disso, o arquivo de bloqueio melhora a estabilidade, evitando atualizações inesperadas ou mudanças interruptivas em bibliotecas externas, reduzindo assim o risco de introduzir bugs.

Geração de arquivos de bloqueio

O arquivo de bloqueio é gerado na raiz do espaço de trabalho com o nome MODULE.bazel.lock. Ele é criado ou atualizado durante o processo de build, especificamente após a resolução do módulo e a avaliação da extensão. É importante ressaltar que ele inclui apenas dependências que estão incluídas na invocação atual do build.

Quando ocorrem mudanças no projeto que afetam as dependências dele, o arquivo de bloqueio é atualizado automaticamente para refletir o novo estado. Isso garante que o arquivo de bloqueio permaneça focado no conjunto específico de dependências necessárias para o build atual, fornecendo uma representação precisa das dependências resolvidas do projeto.

Uso de arquivos de bloqueio

O arquivo de bloqueio pode ser controlado pela flag --lockfile_mode para personalizar o comportamento do Bazel quando o estado do projeto é diferente do arquivo de bloqueio. Os modos disponíveis são:

• update (padrão): use as informações presentes no arquivo de bloqueio para pular downloads de arquivos de registro conhecidos e evitar a reavaliação de extensões cujos resultados ainda estão atualizados. Se houver informações ausentes, elas serão adicionadas ao arquivo de bloqueio. Nesse modo, o Bazel também evita atualizar informações mutáveis, como versões retiradas, para dependências que não foram alteradas.
• refresh: como update, mas as informações mutáveis são sempre atualizadas ao mudar para esse modo e aproximadamente a cada hora enquanto estiver nesse modo.
• error: como update, mas se alguma informação estiver ausente ou desatualizada, o Bazel vai falhar com um erro. Esse modo nunca muda o arquivo de bloqueio nem realiza solicitações de rede durante a resolução. As extensões de módulo que se marcaram como reproducible ainda podem realizar solicitações de rede, mas sempre devem produzir o mesmo resultado.
• off: o arquivo de bloqueio não é verificado nem atualizado.

Benefícios do arquivo de bloqueio

O arquivo de bloqueio oferece vários benefícios e pode ser usado de várias maneiras:

• Builds reproduzíveis. Ao capturar as versões ou dependências específicas de bibliotecas de software, o arquivo de bloqueio garante que os builds sejam reproduzíveis em diferentes ambientes e ao longo do tempo. Os desenvolvedores podem contar com resultados consistentes e previsíveis ao criar projetos.

• Resoluções incrementais rápidas. O arquivo de bloqueio permite que o Bazel evite o download de arquivos de registro que já foram usados em um build anterior. Isso melhora significativamente a eficiência do build, especialmente em cenários em que a resolução pode ser demorada.

• Estabilidade e redução de riscos. O arquivo de bloqueio ajuda a manter a estabilidade, evitando atualizações inesperadas ou mudanças interruptivas em bibliotecas externas. Ao bloquear as dependências em versões específicas, o risco de introduzir bugs devido a atualizações incompatíveis ou não testadas é reduzido.

Conteúdo do arquivo de bloqueio

O arquivo de bloqueio contém todas as informações necessárias para determinar se o estado do projeto mudou. Ele também inclui o resultado da criação do projeto no estado atual. O arquivo de bloqueio consiste em duas partes principais:

1. Hashes de todos os arquivos remotos que são entradas para a resolução do módulo.
2. Para cada extensão de módulo, o arquivo de bloqueio inclui entradas que a afetam, representadas por bzlTransitiveDigest, usagesDigest e outros campos, bem como a saída da execução dessa extensão, chamada de generatedRepoSpecs

Confira um exemplo que demonstra a estrutura do arquivo de bloqueio, com explicações para cada seção:

{
  "lockFileVersion": 10,
  "registryFileHashes": {
    "https://bcr.bazel.build/bazel_registry.json": "8a28e4af...5d5b3497",
    "https://bcr.bazel.build/modules/foo/1.0/MODULE.bazel": "7cd0312e...5c96ace2",
    "https://bcr.bazel.build/modules/foo/2.0/MODULE.bazel": "70390338... 9fc57589",
    "https://bcr.bazel.build/modules/foo/2.0/source.json": "7e3a9adf...170d94ad",
    "https://registry.mycorp.com/modules/foo/1.0/MODULE.bazel": "not found",
    ...
  },
  "selectedYankedVersions": {
    "foo@2.0": "Yanked for demo purposes"
  },
  "moduleExtensions": {
    "//:extension.bzl%lockfile_ext": {
      "general": {
        "bzlTransitiveDigest": "oWDzxG/aLnyY6Ubrfy....+Jp6maQvEPxn0pBM=",
        "usagesDigest": "aLmqbvowmHkkBPve05yyDNGN7oh7QE9kBADr3QIZTZs=",
        ...,
        "generatedRepoSpecs": {
          "hello": {
            "bzlFile": "@@//:extension.bzl",
            ...
          }
        }
      }
    },
    "//:extension.bzl%lockfile_ext2": {
      "os:macos": {
        "bzlTransitiveDigest": "oWDzxG/aLnyY6Ubrfy....+Jp6maQvEPxn0pBM=",
        "usagesDigest": "aLmqbvowmHkkBPve05y....yDNGN7oh7r3QIZTZs=",
        ...,
        "generatedRepoSpecs": {
          "hello": {
            "bzlFile": "@@//:extension.bzl",
            ...
          }
        }
      },
      "os:linux": {
        "bzlTransitiveDigest": "eWDzxG/aLsyY3Ubrto....+Jp4maQvEPxn0pLK=",
        "usagesDigest": "aLmqbvowmHkkBPve05y....yDNGN7oh7r3QIZTZs=",
        ...,
        "generatedRepoSpecs": {
          "hello": {
            "bzlFile": "@@//:extension.bzl",
            ...
          }
        }
      }
    }
  }
}

Hashes de arquivos de registro

A seção registryFileHashes contém os hashes de todos os arquivos de registros remotos acessados durante a resolução do módulo. Como o algoritmo de resolução é totalmente determinístico quando recebe as mesmas entradas e todas as entradas remotas são hash, isso garante um resultado de resolução totalmente reproduzível, evitando a duplicação excessiva de informações remotas no arquivo de bloqueio. Isso também exige a gravação quando um registro específico não continha um determinado módulo, mas um registro com precedência menor continha (consulte a entrada "não encontrado" no exemplo). Essas informações inerentemente mutáveis podem ser atualizadas usando bazel mod deps --lockfile_mode=refresh.

O Bazel usa os hashes do arquivo de bloqueio para pesquisar arquivos de registro no cache do repositório antes de fazer o download deles, o que acelera as resoluções subsequentes.

Versões retiradas selecionadas

A seção selectedYankedVersions contém as versões retiradas de módulos que foram selecionados pela resolução do módulo. Como isso geralmente resulta em um erro ao tentar criar, essa seção só não está vazia quando as versões retiradas são explicitamente permitidas usando --allow_yanked_versions ou BZLMOD_ALLOW_YANKED_VERSIONS.

Esse campo é necessário porque, em comparação com os arquivos de módulo, as informações de versão retiradas são inerentemente mutáveis e, portanto, não podem ser referenciadas por um hash. Essas informações podem ser atualizadas usando bazel mod deps --lockfile_mode=refresh.

Extensões de módulo

A seção moduleExtensions é um mapa que inclui apenas as extensões usadas na invocação atual ou invocadas anteriormente, excluindo todas as extensões que não são mais utilizadas. Em outras palavras, se uma extensão não estiver mais sendo usada no gráfico de dependências, ela será removida do mapa moduleExtensions.

Se uma extensão for independente do sistema operacional ou do tipo de arquitetura, essa seção vai apresentar apenas uma única entrada "geral". Caso contrário, várias entradas serão incluídas, nomeadas de acordo com o SO, a arquitetura ou ambos, com cada uma correspondendo ao resultado da avaliação da extensão nessas especificidades.

Cada entrada no mapa de extensão corresponde a uma extensão usada e é identificada pelo arquivo e nome que a contém. O valor correspondente de cada entrada contém as informações relevantes associadas a essa extensão:

1. O bzlTransitiveDigest é o resumo da implementação da extensão e dos arquivos .bzl carregados transitivamente por ela.
2. O usagesDigest é o resumo dos usos da extensão no gráfico de dependências, que inclui todas as tags.
3. Outros campos não especificados que rastreiam outras entradas para a extensão, como o conteúdo de arquivos ou diretórios que ela lê ou variáveis de ambiente que ela usa.
4. O generatedRepoSpecs codifica os repositórios criados pela extensão com a entrada atual.
5. O campo opcional moduleExtensionMetadata contém metadados fornecidos pela extensão, como se determinados repositórios criados por ela precisam ser importados usando use_repo pelo módulo raiz. Essas informações alimentam o comando bazel mod tidy.

As extensões de módulo podem desativar a inclusão no arquivo de bloqueio definindo os metadados retornados com reproducible = True. Ao fazer isso, elas prometem que sempre criarão os mesmos repositórios quando receberem as mesmas entradas.

Práticas recomendadas

Para maximizar os benefícios do recurso de arquivo de bloqueio, considere as seguintes práticas recomendadas:

• Atualize regularmente o arquivo de bloqueio para refletir mudanças nas dependências ou na configuração do projeto. Isso garante que os builds subsequentes sejam baseados no conjunto de dependências mais atualizado e preciso. Para bloquear todas as extensões de uma só vez, execute bazel mod deps --lockfile_mode=update.

• Inclua o arquivo de bloqueio no controle de versões para facilitar a colaboração e garantir que todos os membros da equipe tenham acesso ao mesmo arquivo de bloqueio, promovendo ambientes de desenvolvimento consistentes em todo o projeto.

• Use bazelisk para executar o Bazel e inclua um arquivo .bazelversion no controle de versões que especifica a versão do Bazel correspondente ao arquivo de bloqueio. Como o Bazel é uma dependência do build, o arquivo de bloqueio é específico da versão do Bazel e muda mesmo entre versões do Bazel compatíveis com versões anteriores. O uso de bazelisk garante que todos os desenvolvedores estejam usando uma versão do Bazel que corresponda ao arquivo de bloqueio.

Ao seguir essas práticas recomendadas, você pode usar o recurso de arquivo de bloqueio no Bazel de maneira eficaz, levando a fluxos de trabalho de desenvolvimento de software mais eficientes, confiáveis e colaborativos.

Conflitos de mesclagem

O formato do arquivo de bloqueio foi projetado para minimizar conflitos de mesclagem, mas eles ainda podem acontecer.

Resolução automática

O Bazel fornece um driver de mesclagem do Git personalizado para ajudar a resolver esses conflitos automaticamente.

Configure o driver adicionando esta linha a um arquivo .gitattributes na raiz do repositório Git:

# A custom merge driver for the Bazel lockfile.
# https://bazel.build/external/lockfile#automatic-resolution
MODULE.bazel.lock merge=bazel-lockfile-merge

Em seguida, cada desenvolvedor que quiser usar o driver precisa registrá-lo uma vez seguindo estas etapas:

1. Instale jq (1.5 ou mais recente).
2. Execute os comandos a seguir:

jq_script=$(curl https://raw.githubusercontent.com/bazelbuild/bazel/master/scripts/bazel-lockfile-merge.jq)
printf '%s\n' "${jq_script}" | less # to optionally inspect the jq script
git config --global merge.bazel-lockfile-merge.name   "Merge driver for the Bazel lockfile (MODULE.bazel.lock)"
git config --global merge.bazel-lockfile-merge.driver "jq -s '${jq_script}' -- %O %A %B > %A.jq_tmp && mv %A.jq_tmp %A"

Resolução manual

Conflitos de mesclagem simples nos campos registryFileHashes e selectedYankedVersions podem ser resolvidos com segurança mantendo todas as entradas de ambos os lados do conflito.

Outros tipos de conflitos de mesclagem não devem ser resolvidos manualmente. Em vez disso:

1. Restaure o estado anterior do arquivo de bloqueio usando git reset MODULE.bazel.lock && git checkout MODULE.bazel.lock.
2. Resolva os conflitos no arquivo MODULE.bazel.
3. Execute bazel mod deps para atualizar o arquivo de bloqueio.