Gerenciar dependências externas com o Bzlmod

Informar um problema Ver código-fonte Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Bzlmod é o nome de código do novo sistema de dependência externa introduzido no Bazel 5.0. Ele foi introduzido para resolver vários problemas do antigo sistema que não podiam ser corrigidos de forma incremental. Consulte a seção "Declaração do problema" do documento de design original para mais detalhes.

No Bazel 5.0, o Bzlmod não é ativado por padrão. A flag --experimental_enable_bzlmod precisa ser especificada para que o seguinte entre em vigor. Como o nome da flag sugere, esse recurso está em fase experimental. As APIs e os comportamentos podem mudar até o lançamento oficial do recurso.

Para migrar seu projeto para o Bzlmod, siga o guia de migração do Bzlmod. Você também pode encontrar exemplos de usos do Bzlmod no repositório de exemplos (em inglês).

Módulos do Bazel

O antigo sistema de dependência externa baseado em WORKSPACE é centrado em repositórios (ou repos), criados com regras de repositório (ou regras de repositório). Embora os repositórios ainda sejam um conceito importante no novo sistema, os módulos são as unidades principais de dependência.

Um módulo é essencialmente um projeto do Bazel que pode ter várias versões, cada uma publicando metadados sobre outros módulos de que depende. Isso é análogo a conceitos conhecidos em outros sistemas de gerenciamento de dependências: um artefato do Maven, um pacote do npm, uma caixa do Cargo, um módulo do Go etc.

Um módulo simplesmente especifica as dependências usando pares name e version, em vez de URLs específicos em WORKSPACE. As dependências são pesquisadas em um registro do Bazel. Por padrão, o registro central do Bazel. No seu espaço de trabalho, cada módulo é transformado em um repositório.

MODULE.bazel

Cada versão de cada módulo tem um arquivo MODULE.bazel que declara as dependências e outros metadados. Este é um exemplo básico:

module(
    name = "my-module",
    version = "1.0",
)

bazel_dep(name = "rules_cc", version = "0.0.1")
bazel_dep(name = "protobuf", version = "3.19.0")

O arquivo MODULE.bazel precisa estar localizado na raiz do diretório do espaço de trabalho (ao lado do arquivo WORKSPACE). Ao contrário do arquivo WORKSPACE, não é necessário especificar as dependências transitivas. Em vez disso, especifique dependências diretas, e os arquivos MODULE.bazel das suas dependências serão processados para descobrir dependências transitivas automaticamente.

O arquivo MODULE.bazel é semelhante aos arquivos BUILD, porque não oferece suporte a nenhuma forma de fluxo de controle. Além disso, ele proíbe instruções load. As diretivas MODULE.bazel arquivos de suporte são:

Formato da versão

O Bazel tem um ecossistema diverso, e os projetos usam vários esquemas de controle de versões. O mais conhecido é o SemVer, mas também há projetos importantes que usam esquemas diferentes, como o Abseil, que tem versões baseadas em data, por exemplo, 20210324.2.

Por esse motivo, o Bzlmod adota uma versão mais flexível da especificação SemVer. As diferenças incluem:

  • A SemVer determina que a parte "release" da versão precisa consistir em três segmentos: MAJOR.MINOR.PATCH. No Bazel, esse requisito é relaxado para permitir qualquer número de segmentos.
  • No SemVer, cada um dos segmentos na parte "lançamento" precisa ter apenas dígitos. No Bazel, isso é relaxado para permitir letras também, e a semântica de comparação corresponde aos "identificadores" na parte "pré-lançamento".
  • Além disso, a semântica de aumentos de versão principal, secundária e de patch não é aplicada. No entanto, consulte o nível de compatibilidade para saber como indicamos a compatibilidade com versões anteriores.

Qualquer versão válida do SemVer é uma versão válida do módulo do Bazel. Além disso, duas versões do SemVer, a e b, comparam a < b se as mesmas retenções são comparadas às versões do módulo Bazel.

Resolução da versão

O problema de dependência diamante é um item básico no espaço de gerenciamento de dependências com controle de versões. Suponha que você tenha o seguinte gráfico de dependências:

       A 1.0
      /     \
   B 1.0    C 1.1
     |        |
   D 1.0    D 1.1

Qual versão do D deve ser usada? Para resolver essa questão, o Bzlmod usa o algoritmo de seleção mínima de versão (MVS, na sigla em inglês) introduzido no sistema de módulos Go. O MVS assume que todas as novas versões de um módulo são compatíveis com versões anteriores e, portanto, simplesmente escolhe a versão mais recente especificada por qualquer dependente (D 1.1 no nosso exemplo). Ela é chamada de "mínima" porque a D 1.1 é a versão mínima que pode atender aos nossos requisitos. Mesmo que a D 1.2 ou uma versão mais recente exista, não a selecionamos. Isso tem a vantagem extra de a seleção da versão ser de alta fidelidade e reprodutível.

A resolução de versão é realizada localmente na sua máquina, não pelo registro.

Nível de compatibilidade

A suposição do MVS sobre a compatibilidade com versões anteriores é viável porque ela simplesmente trata versões incompatíveis de um módulo como um módulo separado. Em termos de SemVer, isso significa que A 1.x e A 2.x são considerados módulos distintos e podem coexistir no gráfico de dependências resolvido. Isso é possível porque a versão principal é codificada no caminho do pacote no Go, então não há conflitos no momento da compilação ou vinculação.

No Bazel, não temos essas garantias. Portanto, precisamos de uma maneira de indicar o número da "versão principal" para detectar versões incompatíveis com versões anteriores. Esse número é chamado de nível de compatibilidade e é especificado por cada versão do módulo na diretiva module(). Com essas informações, podemos gerar um erro quando detectamos que versões do mesmo módulo com diferentes níveis de compatibilidade existem no gráfico de dependência resolvido.

Nomes de repositório

No Bazel, cada dependência externa tem um nome de repositório. Às vezes, a mesma dependência pode ser usada com nomes de repositório diferentes (por exemplo, @io_bazel_skylib e @bazel_skylib significam Bazel skylib), ou o mesmo nome de repositório pode ser usado para dependências diferentes em projetos diferentes.

No Bzlmod, os repositórios podem ser gerados por módulos do Bazel e extensões de módulo (link em inglês). Para resolver conflitos de nome de repositório, estamos adotando o mecanismo de mapeamento de repositório no novo sistema. Dois conceitos importantes:

  • Nome do repositório canônico: o nome do repositório globalmente exclusivo para cada repositório. Esse será o nome do diretório em que o repositório está armazenado.
    Ele é construído da seguinte maneira (Aviso: o formato de nome canônico não é uma API da qual você depende, ele está sujeito a mudanças a qualquer momento):

    • Para repositórios de módulo do Bazel: module_name~version
      (exemplo). @bazel_skylib~1.0.3)
    • Para repositórios de extensões de módulo: module_name~version~extension_name~repo_name
      (exemplo). @rules_cc~0.0.1~cc_configure~local_config_cc)

  • Nome aparente do repositório: o nome do repositório a ser usado nos arquivos BUILD e .bzl em um repositório. A mesma dependência pode ter nomes aparentes diferentes em repositórios diferentes.
    É determinado da seguinte forma:

    • Para repositórios de módulos do Bazel: module_name por padrão ou o nome especificado pelo atributo repo_name em bazel_dep.
    • Para repositórios de extensão de módulo: nome do repositório introduzido por use_repo.

Cada repositório tem um dicionário de mapeamento de repositório das dependências diretas, que é um mapa do nome aparente do repositório para o nome canônico. Usamos o mapeamento de repositório para resolver o nome do repositório ao criar um rótulo. Não há conflito de nomes de repositório canônicos, e os usos de nomes de repositórios aparentes podem ser descobertos analisando o arquivo MODULE.bazel. Portanto, os conflitos podem ser facilmente detectados e resolvidos sem afetar outras dependências.

Dependências rigorosas

O novo formato de especificação de dependência nos permite realizar verificações mais rigorosas. Em particular, agora exigimos que um módulo só possa usar repositórios criados a partir das dependências diretas. Isso ajuda a evitar quebras acidentais e difíceis de depurar quando algo no gráfico de dependência transitiva muda.

As dependências rígidas são implementadas com base no mapeamento de repositório. Basicamente, o mapeamento de repositório para cada repositório contém todas as dependências diretas. Qualquer outro repositório não fica visível. As dependências visíveis de cada repositório são determinadas da seguinte maneira:

  • Um repositório de módulo do Bazel pode acessar todos os repositórios introduzidos no arquivo MODULE.bazel usando bazel_dep e use_repo.
  • Um repositório de extensão de módulo pode conferir todas as dependências visíveis do módulo que fornece a extensão, além de todos os outros repositórios gerados pela mesma extensão de módulo.

Registros

O Bzlmod descobre dependências solicitando as informações deles dos registros do Bazel. Um registro do Bazel é simplesmente um banco de dados de módulos do Bazel. A única forma de registros aceita é um registro de índice, que é um diretório local ou um servidor HTTP estático seguindo um formato específico. No futuro, planejamos adicionar suporte a registros de módulo único, que são simplesmente repositórios do Git que contêm a origem e o histórico de um projeto.

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. Ele não precisa exibir os arquivos de origem.

Um registro de índice precisa seguir o formato abaixo:

  • /bazel_registry.json: um arquivo JSON com metadados para o registro, como:
    • mirrors, especificando a lista de espelhos a serem usados para arquivos de origem.
    • module_base_path, especificando o caminho de base para módulos com o tipo local_repository 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 deste módulo, além do seguinte arquivo:
    • metadata.json: um arquivo JSON contendo 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 às informações de um mantenedor do módulo no registro. Isso não é necessariamente igual aos autores do projeto.
      • versions: uma lista de todas as versões desse módulo encontradas neste registro.
      • yanked_versions: uma lista de versões retiradas deste módulo. No momento, isso não faz nada, mas no futuro, as versões retiradas serão ignoradas ou gerarão um erro.
  • /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 com informações sobre como buscar a fonte dessa versão do módulo.
      • O tipo padrão é "arquivo" com os seguintes campos:
        • url: o URL do arquivo de origem.
        • integrity: o checksum de integridade de subrecurso do arquivo.
        • strip_prefix: um prefixo de diretório para remover ao extrair o arquivo de origem.
        • patches: uma lista de strings, cada uma com o nome de um arquivo de patch a ser aplicado ao arquivo extraído. Os arquivos de patch estão localizados no diretório /modules/$MODULE/$VERSION/patches.
        • patch_strip: igual ao argumento --strip do patch do Unix.
      • O tipo pode ser alterado para usar um caminho local com estes campos:
        • type: local_path
        • path: o caminho local para o repo, calculado da seguinte maneira:
          • Se o caminho for absoluto, ele será usado como está.
          • Se o caminho for relativo e module_base_path for absoluto, o caminho será resolvido para <module_base_path>/<path>.
          • Se o caminho e module_base_path forem caminhos relativos, o caminho 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".

Registro central do Bazel

O registro central do Bazel (BCR) é um registro de índice localizado em bcr.bazel.build. O conteúdo é apoiado pelo repositório do GitHub bazelbuild/bazel-central-registry.

O BCR é mantido pela comunidade do Bazel. Os colaboradores podem enviar pull requests. Consulte Políticas e procedimentos do registro central do Bazel.

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 de build e teste essenciais que podem ser usados para verificar a validade dessa versão do módulo e é usado pelos pipelines de CI do BCR para garantir a interoperabilidade entre os módulos no BCR.

Seleção de registros

A flag repetível --registry do Bazel pode ser usada para especificar a lista de registros para solicitar módulos. Assim, é possível 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.

Extensões do módulo

As extensões de módulo permitem que você estenda o sistema de módulo lendo dados de entrada de módulos no gráfico de dependência, executando a lógica necessária para resolver dependências e, por fim, criando repositórios chamando regras de repositório. Elas são semelhantes em função às macros WORKSPACE atuais, mas são mais adequadas para o mundo dos módulos e dependências transitivas.

As extensões do módulo são definidas em arquivos .bzl, assim como as regras de repositório ou as macros WORKSPACE. Eles não são invocados diretamente. Em vez disso, cada módulo pode especificar partes de dados chamadas de tags para que as extensões leiam. Depois que a resolução da versão do módulo é concluída, as extensões do módulo são executadas. Cada extensão é executada uma vez após a resolução do módulo (ainda antes de qualquer build) e lê todas as tags que pertencem a ela em todo o gráfico de dependências.

          [ A 1.1                ]
          [   * maven.dep(X 2.1) ]
          [   * maven.pom(...)   ]
              /              \
   bazel_dep /                \ bazel_dep
            /                  \
[ B 1.2                ]     [ C 1.0                ]
[   * maven.dep(X 1.2) ]     [   * maven.dep(X 2.1) ]
[   * maven.dep(Y 1.3) ]     [   * cargo.dep(P 1.1) ]
            \                  /
   bazel_dep \                / bazel_dep
              \              /
          [ D 1.4                ]
          [   * maven.dep(Z 1.4) ]
          [   * cargo.dep(Q 1.1) ]

No gráfico de dependência de exemplo acima, A 1.1 e B 1.2 são módulos do Bazel. Pense em cada um como um arquivo MODULE.bazel. Cada módulo pode especificar algumas tags para extensões de módulo. Aqui, algumas são especificadas para a extensão "maven" e outras para "cargo". Quando esse gráfico de dependências é finalizado (por exemplo, talvez B 1.2 tenha uma bazel_dep em D 1.3, mas foi atualizado para D 1.4 devido a C), as extensões "maven" são executadas e podem ler todas as tags maven.*, usando as informações nelas para decidir quais repositórios criar. O mesmo vale para a extensão "cargo".

Uso da extensão

As extensões são hospedadas nos próprios módulos do Bazel. Portanto, para usar uma extensão no seu módulo, primeiro você precisa adicionar uma bazel_dep a esse módulo e, em seguida, chamar a função integrada use_extension para incluí-la no escopo. Considere o exemplo a seguir, um snippet de um arquivo MODULE.bazel para usar uma extensão hipotética "maven" definida no módulo rules_jvm_external:

bazel_dep(name = "rules_jvm_external", version = "1.0")
maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")

Depois de incluir a extensão no escopo, use a sintaxe de ponto para especificar tags. As tags precisam seguir o esquema definido pelas classes de tag correspondentes (consulte a definição de extensão abaixo). Confira um exemplo que especifica algumas tags maven.dep e maven.pom.

maven.dep(coord="org.junit:junit:3.0")
maven.dep(coord="com.google.guava:guava:1.2")
maven.pom(pom_xml="//:pom.xml")

Se a extensão gerar repositórios que você quer usar no seu módulo, use a diretiva use_repo para declará-los. Isso é para atender à condição de dependências rígidas e evitar conflitos de nome de repositório local.

use_repo(
    maven,
    "org_junit_junit",
    guava="com_google_guava_guava",
)

Os repositórios gerados por uma extensão fazem parte da API dela. Portanto, com base nas tags especificadas, você sabe que a extensão "maven" vai gerar um repositório chamado "org_junit_junit" e outro chamado "com_google_guava_guava". Com use_repo, você pode renomeá-los no escopo do módulo, como "guava" aqui.

Definição de extensão

As extensões de módulo são definidas de maneira semelhante às regras de repositório, usando a função module_extension. Ambas têm uma função de implementação. No entanto, embora as regras de repo tenham vários atributos, as extensões de módulo têm uma série de tag_classs, cada uma com vários atributos. As classes de tag definem esquemas para tags usadas por essa extensão. Continuando nosso exemplo da hipotética extensão "maven" acima:

# @rules_jvm_external//:extensions.bzl
maven_dep = tag_class(attrs = {"coord": attr.string()})
maven_pom = tag_class(attrs = {"pom_xml": attr.label()})
maven = module_extension(
    implementation=_maven_impl,
    tag_classes={"dep": maven_dep, "pom": maven_pom},
)

Essas declarações deixam claro que as tags maven.dep e maven.pom podem ser especificadas usando o esquema de atributo definido acima.

A função de implementação é semelhante a uma macro WORKSPACE, exceto pelo fato de receber um objeto module_ctx, que concede acesso ao gráfico de dependências e a todas as tags pertinentes. A função de implementação precisa chamar as regras de repositório para gerar repositórios:

# @rules_jvm_external//:extensions.bzl
load("//:repo_rules.bzl", "maven_single_jar")
def _maven_impl(ctx):
  coords = []
  for mod in ctx.modules:
    coords += [dep.coord for dep in mod.tags.dep]
  output = ctx.execute(["coursier", "resolve", coords])  # hypothetical call
  repo_attrs = process_coursier(output)
  [maven_single_jar(**attrs) for attrs in repo_attrs]

No exemplo acima, analisamos todos os módulos no gráfico de dependência (ctx.modules), cada um deles é um objeto bazel_module cujo campo tags expõe todas as tags maven.* no módulo. Em seguida, invocamos o utilitário CLI Coursier para entrar em contato com o Maven e realizar a resolução. Por fim, usamos o resultado da resolução para criar vários repositórios, usando a regra hipotética do repositório maven_single_jar.