Registros do Bazel

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

Registro de í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 responsáveis pela manutenção, o arquivo MODULE.bazel de cada versão e como buscar a origem de cada versão. Ele não precisa veicular os arquivos de origem.

Um registro de índice precisa seguir o formato abaixo:

• /bazel_registry.json: um arquivo JSON que contém metadados para o registro como:
  • mirrors: especifica a lista de espelhos a serem usados para arquivos de origem
  • module_base_path: especifica o caminho base para módulos com local_repository tipo no arquivo source.json
• /modules: um diretório que contém um subdiretório para cada módulo nesse registro
• /modules/$MODULE: um diretório que contém um subdiretório para cada versão desse módulo, além de:
  • metadata.json: um arquivo JSON que contém 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 correspondendo a informações de um responsável pela manutenção do módulo no registro. Isso não é necessariamente o mesmo que os autores do projeto
    • versions: uma lista de todas as versões desse módulo a serem encontradas em esse registro
    • yanked_versions: um mapa de versões retiradas desse módulo. As chaves precisam ser versões a serem retiradas, e os valores precisam ser descrições de por que a versão foi retirada, idealmente contendo um link para mais informações
• /modules/$MODULE/$VERSION: um diretório que contém os seguintes arquivos:
  • MODULE.bazel: o arquivo MODULE.bazel dessa versão do módulo
  • source.json: um arquivo JSON que contém informações sobre como buscar a origem dessa versão do módulo
    • O tipo padrão é "archive", que representa um http_archive repo, com os seguintes campos:
      • url: o URL do arquivo de origem
      • integrity: o checksum de integridade de sub-recurso do arquivo
      • strip_prefix: um prefixo de diretório a ser removido ao extrair o arquivo de origem
      • patches: um mapa que contém 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 dos arquivos de patch, e os valores são o checksum de integridade de os arquivos de patch
      • patch_strip: igual ao argumento --strip do patch do Unix.
      • archive_type: o tipo de arquivo do arquivo baixado (igual a 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 um dos seguintes: "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 local_repository repo, 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 permanecerá como está
        • Se path for um caminho relativo e module_base_path for um caminho absoluto, ele será resolvido para <module_base_path>/<path>
        • Se path e module_base_path forem caminhos relativos, ele será resolvido para <registry_path>/<module_base_path>/<path>. O registro precisa ser hospedado localmente e usado por --registry=file://<registry_path>. Caso contrário, o Bazel vai gerar um erro
  • patches/: um diretório opcional que contém arquivos de patch, usado apenas quando source.json tem o tipo "archive"

Registro central do Bazel

O Registro central do Bazel (BCR, na sigla em inglês) em https://bcr.bazel.build/ é um registro de índice com conteúdo apoiado pelo repositório do GitHub bazelbuild/bazel-central-registry. Você pode navegar 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, o BCR exige um presubmit.yml arquivo para cada versão do módulo (/modules/$MODULE/$VERSION/presubmit.yml). Esse arquivo especifica alguns destinos essenciais de build e teste 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

O flag repetível do Bazel --registry pode ser usado para especificar a lista de registros dos quais solicitar módulos. Assim, você pode configurar seu projeto para buscar dependências de um registro interno ou de terceiros. Os registros anteriores têm precedência. Para sua conveniência, você pode colocar uma lista de --registry flags no .bazelrc arquivo do seu projeto.

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

O uso do flag --registry impede que o Registro central do Bazel seja usado por padrão, mas você pode adicioná-lo novamente incluindo --registry=https://bcr.bazel.build.