Registros do Bazel

O Bzlmod descobre as dependências solicitando as informações dos registros do Bazel: bancos de dados dos módulos do Bazel. Atualmente, o Bzlmod oferece suporte apenas a registros de índice: diretórios locais ou servidores HTTP estáticos que seguem um formato específico.

Registro do índice

Um registro de índice é um diretório local ou um servidor HTTP estático que contém informações sobre uma lista de módulos, incluindo a página inicial, os mantenedores, o arquivo MODULE.bazel de cada versão e como buscar a origem de cada versão. Mais especificamente, ele não precisa exibir os próprios arquivos de origem.

Um registro de índice precisa seguir o formato abaixo:

• /bazel_registry.json: um arquivo JSON com os metadados do registro, como:
  • mirrors: especifica a lista de espelhos a serem usados nos arquivos de origem.
  • module_base_path: especifica o caminho base para módulos com tipo local_repository no arquivo source.json.
• /modules: um diretório que contém um subdiretório para cada módulo deste registro.
• /modules/$MODULE: um diretório que contém um subdiretório para cada versão deste módulo, além de:
  • metadata.json: um arquivo JSON com informações sobre o módulo, com os seguintes campos:
    • homepage: o URL da página inicial do projeto.
    • maintainers: uma lista de objetos JSON, cada um correspondente às informações de um mantenedor do módulo no registro. Observe que isso não é necessariamente igual aos autores do projeto.
    • versions: uma lista de todas as versões deste módulo que podem ser encontradas nesse registro.
    • yanked_versions: um mapa de versões avançadas deste módulo. As chaves precisam ser versões de yank e os valores devem ser descrições de por que a versão é puxada, com um link ideal para mais informações.
• /modules/$MODULE/$VERSION: é um diretório que contém os seguintes arquivos:
  • MODULE.bazel: o arquivo MODULE.bazel desta versão do módulo.
  • source.json: um arquivo JSON com informações sobre como buscar a origem desta versão do módulo.
    • O tipo padrão é "arquivo", que representa um repositório http_archive, com os seguintes campos:
      • url: o URL do arquivo de origem.
      • integrity: a soma de verificação Integridade do subrecurso do arquivo
      • strip_prefix: um prefixo de diretório a ser removido ao extrair o arquivo de origem.
      • patches: um mapa contendo arquivos de patch a serem aplicados ao arquivo extraído. Os arquivos de patch estão localizados no diretório /modules/$MODULE/$VERSION/patches. As chaves são os nomes de arquivos de patch, e os valores são a soma de verificação de integridade dos arquivos de patch.
      • patch_strip: igual ao argumento --strip do Unix patch.
      • archive_type: o tipo de arquivo do download (o mesmo que type em http_archive). Por padrão, o tipo de arquivo é determinado pela extensão do URL. Se o arquivo não tiver extensão, você poderá especificar explicitamente uma das seguintes opções: "zip", "jar", "war", "aar", "tar", "tar.gz", "tgz", "tar.xz", "txz", "tar.zst", "tzst", tar.bz2, "ar" ou "deb".
    • O tipo pode ser alterado para usar um caminho local, representando um repositório local_repository, com estes campos:
      • type: local_path
      • path: o caminho local para o repositório, calculado da seguinte maneira:
        • Se path for um caminho absoluto, ele permanece como está
        • Se path for um caminho relativo e module_base_path for um caminho absoluto, ele será resolvido como <module_base_path>/<path>
        • Se path e module_base_path forem caminhos relativos, ele será resolvido como <registry_path>/<module_base_path>/<path>. O registro precisa ser hospedado localmente e usado por --registry=file://<registry_path>. Caso contrário, o Bazel emitirá um erro
  • patches/: um diretório opcional que contém arquivos de patch, usado somente quando source.json tem o tipo "arquivado".

Registro central do Bazel

O Bazel Central Registry (BCR) em https://bcr.bazel.build/ é um registro de índice com conteúdo apoiado pelo repositório do GitHub bazelbuild/bazel-central-registry (em inglês). Navegue pelo conteúdo usando o front-end da Web em https://registry.bazel.build/.

A comunidade do Bazel mantém o BCR, e os colaboradores podem enviar solicitações de envio. Consulte as diretrizes de contribuição do BCR.

Além de seguir o formato de um registro de índice normal, a BCR exige um arquivo presubmit.yml para cada versão do módulo (/modules/$MODULE/$VERSION/presubmit.yml). Esse arquivo especifica alguns destinos de compilação e teste essenciais que podem ser usados para verificar a validade dessa versão do módulo. Os pipelines de CI do BCR também usam isso para garantir a interoperabilidade entre os módulos.

Como selecionar registros

A sinalização --registry repetível do Bazel pode ser usada para especificar a lista de registros em que os módulos serão solicitados. Assim, será possível configurar o projeto para buscar dependências em um registro interno ou de terceiros. Os registros anteriores têm precedência. Por conveniência, é possível colocar uma lista de sinalizações --registry no arquivo .bazelrc do projeto.

Se o registro estiver hospedado no GitHub (por exemplo, como uma bifurcação de bazelbuild/bazel-central-registry), seu valor de --registry precisará de um endereço bruto do GitHub em raw.githubusercontent.com. Por exemplo, na ramificação main da bifurcação my-org, defina --registry=https://raw.githubusercontent.com/my-org/bazel-central-registry/main/.

O uso da sinalização --registry impede que o Bazel Central Registry seja usado por padrão, mas é possível adicioná-lo de volta adicionando --registry=https://bcr.bazel.build.