Guia de migração do Bzlmod

Relatar um problema Conferir código-fonte Por noite · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

Devido às falhas de ESPAÇO DE TRABALHO, Bzlmod vai substituir o sistema WORKSPACE legado. O arquivo WORKSPACE será desativado por por padrão no Bazel 8 (final de 2024) e será removida no Bazel 9 (final de 2025). Este guia ajuda você a migrar seu projeto para Bzlmod e inserir WORKSPACE para busca de dependências externas.

WORKSPACE x Bzlmod

O ESPAÇO DE TRABALHO e o Bzlmod do Bazel oferecem recursos semelhantes com sintaxes diferentes. Isso explica como migrar de funcionalidades específicas do WORKSPACE para BZLmod.

Definir a raiz de um espaço de trabalho do Bazel

O arquivo WORKSPACE marca a raiz de origem de um projeto do Bazel. Essa responsabilidade foi substituído por MODULE.bazel no Bazel versão 6.3 e posterior. Com a versão do Bazel Antes da versão 6.3, ainda deve haver um arquivo WORKSPACE ou WORKSPACE.bazel em à raiz do espaço de trabalho, talvez com comentários como:

• ESPAÇO DE TRABALHO

  # This file marks the root of the Bazel workspace.
  # See MODULE.bazel for external dependencies setup.
  

Ativar o Bzlmod no seu Bazel

.bazelrc permite definir sinalizações que são aplicadas sempre que o Bazel é executado. Para ativar Bzlmod, use a flag --enable_bzlmod e aplique-a ao comando common para ela se aplica a todos os comandos:

• .bazelrc

  # Enable Bzlmod for every Bazel command
  common --enable_bzlmod
  

Especifique o nome do repositório do seu espaço de trabalho

• ESPAÇO DE TRABALHO

  A função workspace é usada para especificar um nome de repositório para seu espaço de trabalho. Isso permite que um segmento //foo:bar no espaço de trabalho a ser referenciado como @<workspace name>//foo:bar. Se não for especificado, o nome do repositório padrão do espaço de trabalho é __main__.

  ## WORKSPACE
  workspace(name = "com_foo_bar")
  

• Bzlmod

  É recomendável fazer referência aos destinos no mesmo espaço de trabalho com o Sintaxe //foo:bar sem @<repo name>. Mas se você precisar da sintaxe antiga , é possível usar o nome do módulo especificado pelo Função module como repositório. nome. Se o nome do módulo for diferente do nome do repositório necessário, é possível usar o atributo repo_name do função module para substituir a nome do repositório.

  ## MODULE.bazel
  module(
      name = "bar",
      repo_name = "com_foo_bar",
  )
  

Buscar dependências externas como módulos do Bazel

Se sua dependência for um projeto do Bazel, você poderá contar com ele como um Módulo do Bazel quando também adota o Bzlmod.

• ESPAÇO DE TRABALHO

  Com o WORKSPACE, é comum usar o http_archive ou git_repository regras de repositório para fazer o download das origens do projeto do Bazel.

  ## WORKSPACE
  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
  
  http_archive(
      name = "bazel_skylib",
      urls = ["https://github.com/bazelbuild/bazel-skylib/releases/download/1.4.2/bazel-skylib-1.4.2.tar.gz"],
      sha256 = "66ffd9315665bfaafc96b52278f57c7e2dd09f5ede279ea6d39b2be471e7e3aa",
  )
  load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
  bazel_skylib_workspace()
  
  http_archive(
      name = "rules_java",
      urls = ["https://github.com/bazelbuild/rules_java/releases/download/6.1.1/rules_java-6.1.1.tar.gz"],
      sha256 = "76402a50ae6859d50bd7aed8c1b8ef09dae5c1035bb3ca7d276f7f3ce659818a",
  )
  load("@rules_java//java:repositories.bzl", "rules_java_dependencies", "rules_java_toolchains")
  rules_java_dependencies()
  rules_java_toolchains()
  

  Como você pode notar, é um padrão comum que os usuários precisam carregar dependências de uma macro da dependência. Considere bazel_skylib e rules_java depende de platform, a versão exata de platform dependência é determinada pela ordem das macros.

• Bzlmod

  Com o Bzlmod, desde que sua dependência esteja disponível no Bazel Central Registry ou seu Bazel personalizado de registros, basta usar um serviço diretiva bazel_dep.

  ## MODULE.bazel
  bazel_dep(name = "bazel_skylib", version = "1.4.2")
  bazel_dep(name = "rules_java", version = "6.1.1")
  

  O Bzlmod resolve as dependências do módulo do Bazel de forma transitiva usando a Algoritmo MVS. Portanto, o máximo a versão necessária do platform é selecionada automaticamente.

Substituir uma dependência como um módulo do Bazel

Como módulo raiz, é possível substituir as dependências do módulo do Bazel em diferentes de várias formas.

Leia a seção substituições para mais informações imprecisas ou inadequadas.

É possível encontrar alguns exemplos de usos na exemplos repositório de dados.

Buscar dependências externas com extensões de módulo

Se a dependência não for um projeto do Bazel ou ainda não estiver disponível em nenhum você pode introduzi-lo usando use_repo_rule ou módulo extensões.

• ESPAÇO DE TRABALHO

  Faça o download de um arquivo usando http_file. regra de repositório.

  ## WORKSPACE
  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
  
  http_file(
      name = "data_file",
      url = "http://example.com/file",
      sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  )
  

• Bzlmod

  Com o Bzlmod, você pode usar a diretiva use_repo_rule no seu MODULE.bazel para instanciar repositórios diretamente:

  ## MODULE.bazel
  http_file = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
  http_file(
      name = "data_file",
      url = "http://example.com/file",
      sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  )
  

  Internamente, isso é implementado usando uma extensão de módulo. Se você precisar executar uma lógica mais complexa do que simplesmente invocar uma regra de repositório, também é possível implementar uma extensão de módulo por conta própria. Você vai precisar mover a definição em um arquivo .bzl, que também permite compartilhar a definição entre WORKSPACE e Bzlmod durante o período de migração.

  ## repositories.bzl
  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
  def my_data_dependency():
      http_file(
          name = "data_file",
          url = "http://example.com/file",
          sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      )
  

  Implemente uma extensão de módulo para carregar a macro de dependências. É possível definir no mesmo arquivo .bzl da macro, mas para manter a compatibilidade com versões mais antigas do Bazel, é melhor defini-lo em um arquivo .bzl separado.

  ## extensions.bzl
  load("//:repositories.bzl", "my_data_dependency")
  def _non_module_dependencies_impl(_ctx):
      my_data_dependency()
  
  non_module_dependencies = module_extension(
      implementation = _non_module_dependencies_impl,
  )
  

  Para tornar o repositório visível para o projeto raiz, declare o usos da extensão do módulo e do repositório no arquivo MODULE.bazel.

  ## MODULE.bazel
  non_module_dependencies = use_extension("//:extensions.bzl", "non_module_dependencies")
  use_repo(non_module_dependencies, "data_file")
  

Resolver dependências externas conflitantes com a extensão do módulo

Um projeto pode fornecer uma macro que apresenta repositórios externos com base entradas dos autores da chamada. Mas e se houver vários autores de chamadas no gráfico de dependências e causam um conflito?

Suponha que o projeto foo forneça a seguinte macro, que usa version como um argumento.

## repositories.bzl in foo {:#repositories.bzl-foo}
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
def data_deps(version = "1.0"):
    http_file(
        name = "data_file",
        url = "http://example.com/file-%s" % version,
        # Omitting the "sha256" attribute for simplicity
    )

• ESPAÇO DE TRABALHO

  Com o ESPAÇO DE TRABALHO, é possível carregar a macro de @foo e especificar a versão da dependência de dados necessária. Suponha que você tenha outra dependência @bar, que também depende de @foo, mas exige uma versão diferente dos dados. .

  ## WORKSPACE
  
  # Introduce @foo and @bar.
  ...
  
  load("@foo//:repositories.bzl", "data_deps")
  data_deps(version = "2.0")
  
  load("@bar//:repositories.bzl", "bar_deps")
  bar_deps() # -> which calls data_deps(version = "3.0")
  

  Nesse caso, o usuário final deve ajustar cuidadosamente a ordem das macros na WORKSPACE para conseguir a versão de que precisam. Este é um dos maiores problemas com o WORKSPACE, já que ele não oferece uma maneira sensata de resolver dependências.

• Bzlmod

  Com o Bzlmod, o autor do projeto foo pode usar a extensão de módulo para resolver conflitos de segurança. Por exemplo, vamos supor que faça sentido sempre selecionar o versão máxima necessária da dependência de dados entre todos os módulos do Bazel.

  ## extensions.bzl in foo
  load("//:repositories.bzl", "data_deps")
  
  data = tag_class(attrs={"version": attr.string()})
  
  def _data_deps_extension_impl(module_ctx):
      # Select the maximal required version in the dependency graph.
      version = "1.0"
      for mod in module_ctx.modules:
          for data in mod.tags.data:
              version = max(version, data.version)
      data_deps(version)
  
  data_deps_extension = module_extension(
      implementation = _data_deps_extension_impl,
      tag_classes = {"data": data},
  )
  

  ## MODULE.bazel in bar
  bazel_dep(name = "foo", version = "1.0")
  
  foo_data_deps = use_extension("@foo//:extensions.bzl", "data_deps_extension")
  foo_data_deps.data(version = "3.0")
  use_repo(foo_data_deps, "data_file")
  

  ## MODULE.bazel in root module
  bazel_dep(name = "foo", version = "1.0")
  bazel_dep(name = "bar", version = "1.0")
  
  foo_data_deps = use_extension("@foo//:extensions.bzl", "data_deps_extension")
  foo_data_deps.data(version = "2.0")
  use_repo(foo_data_deps, "data_file")
  

  Neste caso, o módulo raiz exige a versão de dados 2.0, enquanto a dependência bar requer 3.0. A extensão do módulo em foo pode corretamente resolver o conflito e selecionar automaticamente a versão 3.0 para os dados .

Integrar um gerenciador de pacotes de terceiros

Seguindo a última seção, já que a extensão de módulo fornece uma maneira de coletar informações do gráfico de dependências, executar lógica personalizada para resolver dependências e chamar regras de repositório para introduzir repositórios externos, esse é uma ótima maneira de os autores de regras aprimorarem os conjuntos de regras que integram gerenciadores de pacotes para linguagens específicas.

Leia a página de extensões de módulo para saber mais sobre como usar extensões de módulo.

Aqui está uma lista dos conjuntos de regras que já adotaram o Bzlmod para buscar dependências de diferentes gerenciadores de pacotes:

• rules_jvm_external
• rules_go
• rules_python

Um exemplo mínimo que integra um pseudogerenciador de pacotes está disponível no exemplos repositório de dados.

Detectar os conjuntos de ferramentas na máquina host

Quando as regras de build do Bazel precisam detectar quais conjuntos de ferramentas estão disponíveis no host. máquina virtual, eles usam regras de repositório para inspecionar a máquina host e gerar informações do conjunto de ferramentas como repositórios externos.

• ESPAÇO DE TRABALHO

  Considere a seguinte regra de repositório para detectar um conjunto de ferramentas do shell.

  ## local_config_sh.bzl
  def _sh_config_rule_impl(repository_ctx):
      sh_path = get_sh_path_from_env("SH_BIN_PATH")
  
      if not sh_path:
          sh_path = detect_sh_from_path()
  
      if not sh_path:
          sh_path = "/shell/binary/not/found"
  
      repository_ctx.file("BUILD", """
  load("@bazel_tools//tools/sh:sh_toolchain.bzl", "sh_toolchain")
  sh_toolchain(
      name = "local_sh",
      path = "{sh_path}",
      visibility = ["//visibility:public"],
  )
  toolchain(
      name = "local_sh_toolchain",
      toolchain = ":local_sh",
      toolchain_type = "@bazel_tools//tools/sh:toolchain_type",
  )
  """.format(sh_path = sh_path))
  
  sh_config_rule = repository_rule(
      environ = ["SH_BIN_PATH"],
      local = True,
      implementation = _sh_config_rule_impl,
  )
  

  É possível carregar a regra de repositório no espaço de trabalho.

  ## WORKSPACE
  load("//:local_config_sh.bzl", "sh_config_rule")
  sh_config_rule(name = "local_config_sh")
  

• Bzlmod

  Com o Bzlmod, você pode introduzir o mesmo repositório usando uma extensão de módulo, o que é semelhante à introdução do repositório @data_file no último nesta seção.

  ## local_config_sh_extension.bzl
  load("//:local_config_sh.bzl", "sh_config_rule")
  
  sh_config_extension = module_extension(
      implementation = lambda ctx: sh_config_rule(name = "local_config_sh"),
  )
  

  Em seguida, use a extensão no arquivo MODULE.bazel.

  ## MODULE.bazel
  sh_config_ext = use_extension("//:local_config_sh_extension.bzl", "sh_config_extension")
  use_repo(sh_config_ext, "local_config_sh")
  

Registrar conjuntos de ferramentas e plataformas de execução

Seguindo a última seção, após a introdução de um conjunto de ferramentas de hospedagem de repositório do aplicativo (por exemplo, local_config_sh), registre o conjunto de ferramentas.

• ESPAÇO DE TRABALHO

  Com o WORKSPACE, você pode registrar o conjunto de ferramentas das seguintes maneiras.

  1. É possível registrar o conjunto de ferramentas do arquivo .bzl e carregar a macro no WORKSPACE.

     ## local_config_sh.bzl
     def sh_configure():
         sh_config_rule(name = "local_config_sh")
         native.register_toolchains("@local_config_sh//:local_sh_toolchain")
     

     ## WORKSPACE
     load("//:local_config_sh.bzl", "sh_configure")
     sh_configure()
     

  2. Ou registre o conjunto de ferramentas diretamente no arquivo WORKSPACE.

     ## WORKSPACE
     load("//:local_config_sh.bzl", "sh_config_rule")
     sh_config_rule(name = "local_config_sh")
     register_toolchains("@local_config_sh//:local_sh_toolchain")
     

• Bzlmod

  Com o Bzlmod, os register_toolchains e register_execution_platforms As APIs estão disponíveis apenas no arquivo MODULE.bazel. Não é possível chamar native.register_toolchains em uma extensão de módulo.

  ## MODULE.bazel
  sh_config_ext = use_extension("//:local_config_sh_extension.bzl", "sh_config_extension")
  use_repo(sh_config_ext, "local_config_sh")
  register_toolchains("@local_config_sh//:local_sh_toolchain")
  

Os conjuntos de ferramentas e as plataformas de execução registrados em WORKSPACE WORKSPACE.bzlmod e o arquivo MODULE.bazel de cada módulo do Bazel seguem este ordem de precedência durante a seleção do conjunto de ferramentas (da maior para a menor):

1. conjuntos de ferramentas e plataformas de execução registrados no módulo MODULE.bazel.
2. conjuntos de ferramentas e plataformas de execução registrados nos WORKSPACE ou arquivo WORKSPACE.bzlmod.
3. conjuntos de ferramentas e plataformas de execução registrados por módulos (transitivas) do módulo raiz.
4. quando não estiver usando WORKSPACE.bzlmod: conjuntos de ferramentas registrados no WORKSPACE. sufixo.

Introduzir repositórios locais

Talvez seja necessário introduzir uma dependência como um repositório local quando você precisar de uma versão local da dependência para depuração ou se quiser incorporar uma do seu espaço de trabalho como um repositório externo.

• ESPAÇO DE TRABALHO

  Com o WORKSPACE, isso é feito por duas regras de repositório nativas, local_repository e new_local_repository

  ## WORKSPACE
  local_repository(
      name = "rules_java",
      path = "/Users/bazel_user/workspace/rules_java",
  )
  

• Bzlmod

  Com o Bzlmod, você pode usar local_path_override para substituir um módulo por um caminho local.

  ## MODULE.bazel
  bazel_dep(name = "rules_java")
  local_path_override(
      module_name = "rules_java",
      path = "/Users/bazel_user/workspace/rules_java",
  )
  

  Observação: com local_path_override, só é possível introduzir um diretório local como um módulo do Bazel, ou seja, ele precisa ter um arquivo MODULE.bazel e o dependências transitivas são levadas em consideração durante e resolução. Além disso, todas as diretivas de substituição de módulo só podem ser usadas por módulo raiz.

  Também é possível introduzir um repositório local com uma extensão de módulo. No entanto, não é possível chamar native.local_repository na extensão de módulo, há um esforço contínuo para estrelar todas as regras de repositório nativo (verifique #18285 para o progresso). Em seguida, você pode chamar o local_repository do starlark correspondente em um módulo. . Também é fácil implementar uma versão personalizada local_repository se esse for um problema de bloqueio para você.

Vincular destinos

A regra bind em WORKSPACE foi descontinuada e incompatível com Bzlmod. Ele foi criado para dar a um destino um alias pacote especial //external. Todos os usuários que dependem disso devem migrar.

Por exemplo, se você tiver

## WORKSPACE
bind(
    name = "openssl",
    actual = "@my-ssl//src:openssl-lib",
)

Isso permite que outros destinos dependam de //external:openssl. É possível migrar se afastando disso por:

• Substitua todos os usos de //external:openssl por @my-ssl//src:openssl-lib.

• Ou use a regra de build alias

  • Defina o seguinte destino em um pacote (por exemplo, //third_party)

    ## third_party/BUILD
    alias(
        name = "openssl",
        actual = "@my-ssl//src:openssl-lib",
    )
    

  • Substitua todos os usos de //external:openssl por //third_party:openssl.

Busca versus sincronização

Os comandos de busca e sincronização são usados para fazer o download de repositórios externos localmente e e atualizá-las. Às vezes, para permitir a criação off-line usando a --nofetch depois de buscar todos os repositórios necessários para um build.

• ESPAÇO DE TRABALHO

  A sincronização executa uma busca forçada para todos os repositórios ou para um determinado conjunto configurado de repositórios, enquanto a busca é usada apenas para buscar um repositório alvo.

• Bzlmod

  O comando de sincronização não é mais aplicável, mas a busca oferece várias opções. É possível buscar um destino, um repositório, um conjunto de repositórios configurados repositórios envolvidos na resolução de dependências e nas extensões de módulo. O resultado da busca é armazenado em cache e, para forçar uma busca, você precisa incluir os Opção --force durante o processo de busca.

Migração

Esta seção fornece informações e orientações úteis para a migração do Bzlmod de desenvolvimento de software.

Conheça suas dependências no WORKSPACE

A primeira etapa da migração é entender quais dependências você tem. Ela pode ser difícil descobrir quais dependências exatas são introduzidas no WORKSPACE porque as dependências transitivas geralmente são carregadas com *_deps. .

Inspecionar dependência externa com o arquivo resolvido do espaço de trabalho

Felizmente, a flag --experimental_repository_resolved_file pode ajudar. Essa flag gera um "arquivo de bloqueio" de todos os servidores externos buscados dependências no último comando do Bazel. Você pode encontrar mais detalhes neste blog post.

Ele pode ser usado de duas maneiras:

1. Para buscar informações de dependências externas necessárias para criar determinados destinos.

   bazel clean --expunge
   bazel build --nobuild --experimental_repository_resolved_file=resolved.bzl //foo:bar
   

2. Para buscar informações de todas as dependências externas definidas no arquivo WORKSPACE.

   bazel clean --expunge
   bazel sync --experimental_repository_resolved_file=resolved.bzl
   

   Com o comando bazel sync, é possível buscar todas as dependências definidas na WORKSPACE, que incluem:

   • bind usos
   • register_toolchains e register_execution_platforms usos

   No entanto, se seu projeto for multiplataforma, a sincronização do Bazel pode falhar em certas plataformas, porque algumas regras de repositório só são executadas plataformas.

Depois de executar o comando, você deve ter informações sobre o ambiente dependências no arquivo resolved.bzl.

Inspecionar dependência externa com bazel query

Talvez você também saiba que bazel query pode ser usado para inspecionar regras de repositório com

bazel query --output=build //external:<repo name>

Embora seja mais conveniente e muito mais rápido, a consulta do Bazel pode conter versão de dependência externa, então tenha cuidado ao usá-lo. Como consultar e inspecionar dependências com o Bzlmod serão alcançadas por uma nova subcomando.

Dependências padrão integradas

Se você verificar o arquivo gerado por --experimental_repository_resolved_file: você vai encontrar muitas dependências que não estão definidas no seu ESPAÇO DE TRABALHO. Isso ocorre porque o Bazel adiciona prefixos e sufixos ao espaço de trabalho do usuário. do arquivo para injetar algumas dependências padrão, que geralmente são exigidas pelos regras nativas (por exemplo, @bazel_tools, @platforms e @remote_java_tools). Com Bzlmod, essas dependências são introduzidas com um módulo integrado. bazel_tools , que é uma dependência padrão para todas as outras Módulo do Bazel.

Modo híbrido para migração gradual

Bzlmod e WORKSPACE podem trabalhar lado a lado, o que permite migrar dependências do arquivo WORKSPACE para Bzlmod para ser um processo gradual.

Observação: na prática, o carregamento de "*_deps" as macros no WORKSPACE geralmente causam confusões com dependências do Bzlmod. Portanto, recomendamos começar com uma WORKSPACE.bzlmod e evite carregar dependências transitivas com macros.

WORKSPACE.bzlmod

Durante a migração, os usuários do Bazel podem precisar alternar entre builds com o sem o Bzlmod ativado. O suporte a WORKSPACE.bzlmod foi implementado para tornar o processo mais fácil.

WORKSPACE.bzlmod tem exatamente a mesma sintaxe que WORKSPACE. Quando o Bzlmod está ativado, se um arquivo WORKSPACE.bzlmod também existir na raiz do espaço de trabalho:

• WORKSPACE.bzlmod entra em vigor, e o conteúdo de WORKSPACE é ignorado.
• Nenhum prefixo ou sufixo é adicionado ao arquivo WORKSPACE.bzlmod.

Usar o arquivo WORKSPACE.bzlmod pode facilitar a migração porque:

• Quando o Bzlmod é desativado, você volta a buscar dependências do WORKSPACE original.
• Quando o Bzlmod está ativado, você pode controlar melhor quais dependências ainda restam para migrar com WORKSPACE.bzlmod.

Visibilidade do repositório

O Bzlmod é capaz de controlar quais outros repositórios são visíveis de um determinado repositório, verifique os nomes dos repositórios e regras dependências para mais detalhes.

Aqui está um resumo das visibilidades dos repositórios de diferentes tipos ao considerar o WORKSPACE.

	No repositório principal	Dos repositórios do módulo do Bazel	De repositórios de extensão de módulos	Dos repositórios do WORKSPACE
O repositório principal	Visível	Se o módulo raiz for uma dependência direta	Se o módulo raiz for uma dependência direta do módulo que hospeda a extensão do módulo	Visível
Repositórios do módulo do Bazel	Dependências diretas	Dependências diretas	Dependências diretas do módulo que hospeda a extensão do módulo	Dependências diretas do módulo raiz
Repositórios de extensão de módulo	Dependências diretas	Dependências diretas	Dependências diretas do módulo que hospeda a extensão do módulo + todos os repositórios gerados pela mesma extensão de módulo	Dependências diretas do módulo raiz
Repositórios do WORKSPACE	Todos visíveis	Não visível	Não visível	Todos visíveis

Observação: para o módulo raiz, se um repositório @foo for definido no ESPAÇO DE TRABALHO e @foo também é usado como um repositório aparente name em MODULE.bazel, depois @foo refere-se àquele introduzido em MODULE.bazel.

Observação: para um repositório @bar gerado por extensão de módulo, se @foo for usado como um nome de repositório aparente de outro repositório gerado pela mesma extensão de módulo e dependências do módulo que hospeda a extensão do módulo e, para o repositório @bar, @foo se refere a segundo.

Processo de migração

Um processo típico de migração do Bzlmod pode ter a seguinte aparência:

1. Entenda quais dependências você tem no ESPAÇO DE TRABALHO.
2. Adicione um arquivo MODULE.bazel vazio à raiz do projeto.
3. Adicione um arquivo WORKSPACE.bzlmod vazio para substituir o conteúdo do arquivo WORKSPACE.
4. Crie seus destinos com o Bzlmod ativado e verifique qual repositório está desaparecidos.
5. Verifique a definição do repositório ausente na dependência resolvida .
6. Introduzir a dependência ausente como um módulo do Bazel usando um módulo. ou deixe-o em WORKSPACE.bzlmod para migração posterior.
7. Volte para a versão 4 e repita até que todas as dependências estejam disponíveis.

Ferramenta de migração

Existe um script auxiliar de migração do Bzlmod interativo que pode ajudar você a começar.

O script faz o seguinte:

• Gere e analise o arquivo resolvido do ESPAÇO DE TRABALHO.
• Imprimir as informações do repositório do arquivo resolvido de uma forma legível por humanos.
• Executar o comando bazel build, detectar mensagens de erro reconhecidas e recomendar uma forma de migrar.
• Verifique se uma dependência já está disponível no BCR.
• Adicione uma dependência ao arquivo MODULE.bazel.
• Adicionar uma dependência usando uma extensão de módulo.
• Adicione uma dependência ao arquivo WORKSPACE.bzlmod.

Para usá-lo, verifique se você tem a versão mais recente do Bazel instalada e execute o seguinte comando:

git clone https://github.com/bazelbuild/bazel-central-registry.git
cd <your workspace root>
<BCR repo root>/tools/migrate_to_bzlmod.py -t <your build targets>

Observação: o script de migração não é perfeito e pode não estar atualizado porque Bzlmod está evoluindo, verifique sempre se a solução recomendada está correta.

Publicar módulos do Bazel

Caso seu projeto do Bazel seja uma dependência de outros projetos, é possível publicar projeto no Bazel Central Registry.

Para verificar seu projeto no BCR, você precisa de um URL do arquivo de origem de o projeto. Observe alguns detalhes ao criar o arquivo de origem:

• Verifique se o arquivo aponta para uma versão específica.

  O BCR só pode aceitar arquivos de origem com controle de versão porque o Bzlmod precisa realizar a comparação de versões durante a resolução da dependência.

• Verifique se o URL do arquivo está estável.

  O Bazel verifica o conteúdo do arquivo por um valor de hash. Portanto, certifique-se de que a soma de verificação do arquivo baixado nunca seja alterada. Se o URL for do GitHub, crie e carregue um arquivo de lançamento na página de lançamento. O GitHub não garante a soma de verificação dos arquivos de origem gerados demanda. Em resumo, URLs na forma de https://github.com/<org>/<repo>/releases/download/... é considerado estável enquanto https://github.com/<org>/<repo>/archive/... não. Confira o GitHub Arquivar soma de verificação interrupção temporária para mais contexto.

• Verifique se a árvore de origem segue o layout do repositório original.

  Caso seu repositório seja muito grande e você queira criar uma distribuição com tamanho reduzido removendo fontes desnecessárias, certifique-se garantir que a árvore de origem removida seja um subconjunto da original. Isso facilita a substituição do módulo por um não lançamento pelos usuários finais versão de archive_override e git_override.

• Inclua um módulo de teste em um subdiretório que teste as configurações mais comuns APIs.

  Um módulo de teste é um projeto do Bazel com o próprio espaço de trabalho e o arquivo MODULE.bazel. localizado em um subdiretório do arquivo de origem, que depende da módulo a ser publicado. Ela deve conter exemplos ou alguns testes de integração que abrangem as APIs mais comuns. Marca de seleção módulo de teste para saber como fazer a configuração.

Quando o URL do arquivo de origem estiver pronto, siga a contribuição do BCR diretrizes para enviar o módulo para o BCR com um GitHub Solicitação de envio.

É altamente recomendado configurar a opção Publicar no App GitHub do BCR repositório para automatizar o processo de envio do módulo para o BCR.

Práticas recomendadas

Esta seção documenta algumas práticas recomendadas que você deve seguir para gerenciar as dependências externas.

Divida os destinos em pacotes diferentes para evitar a busca de dependências desnecessárias.

Confira #12835, onde dev dependências de testes são forçadas a ser buscadas desnecessariamente para a criação para os destinos que não precisam deles. Na verdade, isso não é específico de Bzlmod, mas seguir essas práticas facilita a especificação correta das dependências de desenvolvimento.

Especificar dependências de desenvolvimento

É possível definir o atributo dev_dependency como verdadeiro para bazel_dep e use_extension para que elas não são propagadas para projetos dependentes. Como módulo raiz, é possível usar o a flag --ignore_dev_dependency para verificar se os destinos criar sem dependências de desenvolvimento e substituições.

Progresso da migração da comunidade

Consulte o Bazel Central Registry para encontrar se as dependências já estiverem disponíveis. Caso contrário, fique à vontade para participar Discussão do GitHub para apoie ou publique as dependências que estão bloqueando a migração.

Informar problemas

Consulte a lista de problemas do Bazel no GitHub (em inglês) para encontrar o Bzlmod conhecido. problemas. Fique à vontade para registrar novos problemas ou solicitar recursos que possam ajudar a desbloquear sua migração.