Registros do Bazel

Nightly · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 7.7

O Bazel descobre dependências solicitando informações dos registros do Bazel: bancos de dados de módulos do Bazel. O Bazel oferece suporte apenas a um tipo de registro, os 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 ter o seguinte formato:

  • /bazel_registry.json: um arquivo JSON opcional que contém metadados para o registro.
  • /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 do módulo chamado $MODULE, bem como o arquivo metadata.json que contém metadados para esse módulo.
  • /modules/$MODULE/$VERSION: um diretório que contém os seguintes arquivos:
    • MODULE.bazel: o arquivo MODULE.bazel dessa versão do módulo. Observe que este é o arquivo MODULE.bazel lido durante a resolução de dependência externa do Bazel, não o do arquivo de origem (a menos que haja uma substituição não registrada). Também é recomendável usar esse arquivo para definir a versão de um lançamento e evitar fazer isso no arquivo MODULE.bazel de origem. Para saber mais sobre o controle de versões de módulos, consulte as Perguntas frequentes.
    • source.json: um arquivo JSON que contém informações sobre como buscar a origem dessa versão do módulo
    • patches/: um diretório opcional que contém arquivos de patch, usado apenas quando source.json tem o tipo "arquivo"
    • overlay/: um diretório opcional que contém arquivos de sobreposição, usado apenas quando source.json tem o tipo "arquivo"

bazel_registry.json

bazel_registry.json é um arquivo opcional que especifica metadados aplicados a todo o registro. Ele pode conter os seguintes campos:

  • mirrors: uma matriz de strings que especifica a lista de espelhos a serem usados para arquivos de origem.
    • O URL espelhado é uma concatenação do 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 URL de origem original https://foo.com/bar/baz.
  • module_base_path: uma string que especifica o caminho base para módulos com local_path tipo no source.json arquivo

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 denotando uma versão do módulo disponível nesse registro. Essa matriz precisa corresponder aos filhos do diretório do módulo.
  • yanked_versions: um objeto JSON que especifica as versões _retiradas_ desse módulo. As chaves precisam ser versões a serem retiradas, e os valores precisam ser descrições do motivo pelo qual a versão foi retirada, idealmente contendo 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 type campo, que é archive por padrão.

  • 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 fazendo o download de um arquivo de um URL especificado e extraindo o conteúdo dele. Ele oferece suporte aos 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 do arquivo
    • strip_prefix: uma string, o prefixo do diretório a ser removido ao extrair o arquivo de origem
    • overlay: um objeto JSON que contém arquivos de sobreposição a serem colocados na parte de 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 após os arquivos de sobreposição e em a ordem em que aparecem em patches.
    • patch_strip: um número, o mesmo que o argumento --strip do Unix patch.
    • archive_type: uma string, o tipo de arquivo do arquivo baixado (o mesmo que type em http_archive).
  • Se type for git_repository, essa versão do módulo será apoiada por uma git_repository regra de repositório. Ela será buscada clonando um repositório Git.
    • Os seguintes campos são compatíveis e encaminhados diretamente para a regra de repositório git_repository subjacente: remote, commit, shallow_since, tag, init_submodules, verbose, e strip_prefix, patch_strip.
    • patches: um objeto JSON que contém arquivos de patch a serem aplicados ao repositório clonado. 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 na ordem em que aparecem em patches.
  • Se type for local_path, essa versão do módulo será apoiada por uma local_repository regra de repositório. Ela será vinculada simbolicamente a um diretório no disco local. Ele oferece suporte ao seguinte campo:
    • 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

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.