Registros do Bazel

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.7

O Bzlmod descobre dependências solicitando informações dos registros do Bazel, que são bancos de dados de módulos do Bazel. No momento, o Bzlmod é compatível apenas com registros de índice (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 mantenedores, o arquivo MODULE.bazel de cada versão e como buscar a origem de cada versão. É importante ressaltar que ele não precisa veicular os próprios 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. O URL espelhado é uma concatenação do próprio espelho e do URL de origem do módulo especificado pelo arquivo source.json sem o protocolo. Por exemplo, se o URL de origem de um módulo for https://foo.com/bar/baz e mirrors contiver ["https://mirror1.com/", "https://example.com/mirror2/"], os URLs que o Bazel vai tentar em ordem serão https://mirror1.com/foo.com/bar/baz, https://example.com/mirror2/foo.com/bar/baz e, por fim, o próprio URL de origem original https://foo.com/bar/baz.
    • module_base_path: especificando 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 neste 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 e os seguintes campos:
      • homepage: o URL da página inicial do projeto.
      • maintainers: uma lista de objetos JSON, cada um correspondendo às informações de um mantenedor do módulo no registro. Isso não é necessariamente o mesmo que os autores do projeto.
      • versions: uma lista de todas as versões deste módulo encontradas neste registro.
      • yanked_versions: um mapa de versões yanked deste módulo. As chaves precisam ser versões a serem removidas, e os valores precisam ser descrições de por que a versão foi removida, de preferência com um link 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 é "archive", que representa um repositório http_archive com os seguintes campos:
        • url: o URL do arquivo de origem
        • integrity: o checksum de Integridade de subrecursos 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 dos arquivos de patch.
        • patch_strip: igual ao argumento --strip do Unix patch.
        • 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 arquivo do URL. Se o arquivo não tiver uma extensão, especifique 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 repositório git, com estes campos:
        • type: git_repository
        • Os seguintes campos, conforme descrito em https://bazel.build/rules/lib/repo/git:
          • remote
          • commit
          • shallow_since
          • tag
          • init_submodules
          • verbose
          • strip_prefix
      • 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 forma:
          • Se path for um caminho absoluto, ele vai permanecer 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 vai gerar um erro.
    • patches/: um diretório opcional que contém arquivos de patch, usado apenas quando source.json tem o tipo "archive".

metadata.json

metadata.json é um arquivo JSON opcional que contém informações sobre o módulo, com os seguintes campos:

  • versions: uma matriz de strings, cada uma indicando uma versão do módulo disponível neste registro. Essa matriz precisa corresponder aos filhos do diretório do módulo.
  • yanked_versions: um objeto JSON que especifica as versões retiradas deste módulo. As chaves precisam ser versões a serem removidas, e os valores precisam ser descrições de por que a versão foi removida, de preferência com um link para mais informações.

O BCR exige mais informações no arquivo metadata.json.

source.json

source.json é um arquivo JSON obrigatório que contém informações sobre como buscar uma versão específica de um módulo. O esquema desse arquivo depende do campo type, que tem como padrão archive.

  • Se type for archive (o padrão), essa versão do módulo será apoiada por uma regra de repositório http_archive. Ela será buscada ao fazer o download de um arquivo de um determinado URL e extrair o conteúdo dele. Ele aceita os seguintes campos:
    • url: uma string, o URL do arquivo de origem
    • mirror_urls: uma lista de strings, os URLs espelhados do arquivo de origem. Os URLs são testados em ordem após url como backups.
    • integrity: uma string, o checksum de [Integridade de subrecursos][subresource-integrity] do arquivo.
    • strip_prefix: uma string, o prefixo de diretório a ser removido ao extrair o arquivo de origem
    • overlay: um objeto JSON que contém arquivos de sobreposição para serem colocados em cima do arquivo extraído. Os arquivos de patch estão localizados no diretório /modules/$MODULE/$VERSION/overlay. As chaves são os nomes dos arquivos de sobreposição, e os valores são o checksum de integridade dos arquivos de sobreposição. As sobreposições são aplicadas antes dos arquivos de patch.
    • patches: um objeto JSON 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 dos arquivos de patch. Os patches são aplicados depois dos arquivos de sobreposição.
    • patch_strip: um número, igual ao argumento --strip de Unix patch.
    • archive_type: uma string, o tipo de arquivo do arquivo baixado (igual a type em http_archive).
  • Se type for git_repository, essa versão do módulo será apoiada por uma regra de repositório git_repository. Ela será buscada clonando um repositório Git.
    • Os seguintes campos são aceitos e encaminhados diretamente para a regra de repositório git_repository subjacente: remote, commit, shallow_since, tag, init_submodules, verbose e strip_prefix.
  • Se type for local_path, essa versão do módulo será apoiada por uma regra de repositório local_repository; ela será vinculada a um diretório no disco local. Ele é compatível com o seguinte campo:
    • path: o caminho local para o repositório, calculado da seguinte forma:
      • Se path for um caminho absoluto, ele vai permanecer 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 vai gerar um erro.

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. 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 pull. Consulte as diretrizes de contribuição do BCR.

Além de seguir o formato de um registro de índice normal, o BCR exige um arquivo presubmit.yml 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 módulos.

Como selecionar registros

A flag repetível do Bazel --registry pode ser usada para especificar a lista de registros de onde solicitar módulos. Assim, você pode configurar seu projeto para buscar dependências de um registro interno ou de terceiros. Registros anteriores têm precedência. Para facilitar, você pode colocar uma lista de flags --registry no arquivo .bazelrc do 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 ramificação main do fork my-org, você definiria --registry=https://raw.githubusercontent.com/my-org/bazel-central-registry/main/.

Usar a flag --registry impede que o registro central do Bazel seja usado por padrão, mas você pode adicioná-lo novamente com --registry=https://bcr.bazel.build.