Guía de migración de Bzlmod

Informar un problema . Ver fuente . Por la noche · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Debido a las deficiencias del WORKSPACE, Bzlmod se encargará de reemplazar el sistema heredado WORKSPACE. El archivo WORKSPACE se inhabilitará por de forma predeterminada en Bazel 8 (a fines de 2024) y se quitará en Bazel 9 (a fines de 2025). Con esta guía, podrás migrar tu proyecto a Bzlmod y soltar WORKSPACE recuperar dependencias externas.

WORKSPACE vs. Bzlmod

WORKSPACE y Bzlmod de Bazel ofrecen funciones similares con una sintaxis diferente. Esta en la que se explica cómo migrar de funciones específicas de WORKSPACE a Bzlmod.

Define la raíz de un lugar de trabajo de Bazel

El archivo WORKSPACE marca la raíz de origen de un proyecto de Bazel. Esta responsabilidad se reemplaza por MODULE.bazel en Bazel 6.3 y versiones posteriores. Con la versión de Bazel anteriores a 6.3, debería haber un archivo WORKSPACE o WORKSPACE.bazel en la raíz de tu lugar de trabajo, tal vez con comentarios como los siguientes:

• Espacio de trabajo

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

Cómo habilitar Bzlmod en tu Bazelrc

.bazelrc te permite establecer marcas que se aplican cada vez que ejecutas Bazel. Para habilitar Bzlmod, usa la marca --enable_bzlmod y aplícala al comando common para se aplica a cada comando:

• .bazelrc

  # Enable Bzlmod for every Bazel command
  common --enable_bzlmod
  

Especifica el nombre del repositorio para tu lugar de trabajo

• Espacio de trabajo

  Se usa la función workspace para especificar un nombre de repositorio para tu lugar de trabajo. Esto permite que un objetivo //foo:bar en el lugar de trabajo al que se hará referencia como @<workspace name>//foo:bar Si no se especifica, el nombre del repositorio predeterminado para tu el espacio de trabajo es __main__.

  ## WORKSPACE
  workspace(name = "com_foo_bar")
  

• Bzlmod

  Se recomienda hacer referencia a los destinos en el mismo lugar de trabajo con el Sintaxis //foo:bar sin @<repo name>. Pero si necesitas la sintaxis anterior , puedes usar el nombre del módulo especificado por el Función module como repositorio de la fuente de datos. Si el nombre del módulo es diferente del nombre del repositorio necesario, puedes usar el atributo repo_name de la module para anular el el nombre del repositorio.

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

Recupera dependencias externas como módulos de Bazel

Si tu dependencia es un proyecto de Bazel, deberías poder depender de ella como un Módulo de Bazel cuando también adopta Bzlmod.

• Espacio de trabajo

  Con WORKSPACE, es común usar el http_archive o git_repository reglas del repositorio para descargar las fuentes del proyecto 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 puedes ver, es un patrón común que los usuarios deben cargar las dependencias desde una macro de la dependencia. Supón que tanto bazel_skylib como rules_java depende de platform, la versión exacta de platform según el orden de las macros.

• Bzlmod

  Con Bzlmod, siempre que tu dependencia esté disponible en Bazel Central Registry o tu Bazel personalizado en el registro, puedes depender de él con un directiva bazel_dep.

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

  Bzlmod resuelve las dependencias del módulo de Bazel de forma transitiva con el MVS. Por lo tanto, el valor máximo se selecciona automáticamente la versión requerida de platform.

Cómo anular una dependencia como módulo de Bazel

Como módulo raíz, puedes anular las dependencias del módulo de Bazel en diferentes maneras.

Para obtener más información, consulta la sección sobre anulaciones información.

Puedes encontrar algunos ejemplos de usos en la ejemplos en un repositorio de confianza.

Cómo recuperar dependencias externas con extensiones de módulo

Si tu dependencia no es un proyecto de Bazel o aún no está disponible en ninguna plataforma de Bazel puedes introducirlo usando use_repo_rule o módulo de servicio.

• Espacio de trabajo

  Descarga un archivo con http_file. regla de repositorio.

  ## 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

  Con Bzlmod, puedes usar la directiva use_repo_rule en tu MODULE.bazel para crear directamente una instancia de repositorios:

  ## 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",
  )
  

  De forma interna, esto se implementa mediante una extensión de módulo. Si necesitas realizar una lógica más compleja que invocar una regla de repositorio, también podrías implementa una extensión de módulo por tu cuenta. Deberás mover la definición en un archivo .bzl, que también te permite compartir la definición entre WORKSPACE y Bzlmod durante el período de migración

  ## 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",
      )
  

  Implementa una extensión de módulo para cargar la macro de dependencias. Puedes definir en el mismo archivo .bzl de la macro, pero para mantener la compatibilidad con versiones anteriores de Bazel, es mejor definirlo en un archivo .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 que el proyecto raíz pueda ver el repositorio, debes declarar el usos de la extensión del módulo y del repositorio en el archivo MODULE.bazel.

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

Resuelve conflictos de dependencias externas con la extensión de módulos

Un proyecto puede proporcionar una macro que introduzca repositorios externos basados en de sus emisores. Pero ¿qué sucede si hay varios emisores en la gráfico de dependencias y causan un conflicto?

Supongamos que el proyecto foo proporciona la siguiente macro que toma version como un 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
    )

• Espacio de trabajo

  Con WORKSPACE, puedes cargar la macro desde @foo y especificar la versión. de la dependencia de datos que necesitas. Supongamos que tienes otra dependencia @bar, que también depende de @foo, pero requiere una versión diferente de los datos dependencia.

  ## 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")
  

  En este caso, el usuario final debe ajustar cuidadosamente el orden de las macros en la WORKSPACE para obtener la versión que necesitan. Este es uno de los principales problemas puntos con WORKSPACE, ya que no proporciona una manera sensata de resolver las dependencias.

• Bzlmod

  Con Bzlmod, el autor del proyecto foo puede usar la extensión del módulo para resolver el problema. conflictos. Por ejemplo, supongamos que tiene sentido seleccionar siempre el la versión máxima requerida de la dependencia de datos entre todos los módulos de 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")
  

  En este caso, el módulo raíz requiere la versión de datos 2.0, mientras que su La dependencia bar requiere 3.0. La extensión del módulo en foo puede resolver este conflicto y seleccionar automáticamente la versión 3.0 para los datos dependencia.

Cómo integrar un administrador de paquetes de terceros

Luego de la última sección, dado que la extensión del módulo proporciona una forma de recopilar información del gráfico de dependencias, realizar una lógica personalizada para resolver y llamar a las reglas de repositorios para ingresar repositorios externos, una excelente manera para que los autores de reglas mejoren los conjuntos de reglas que se integran administradores de paquetes para lenguajes específicos.

Para obtener más información, consulta la página de extensiones de módulos. sobre cómo usar las extensiones de módulo.

A continuación, se muestra una lista de los conjuntos de reglas que ya adoptaron Bzlmod para recuperar dependencias desde diferentes administradores de paquetes:

• rules_jvm_external
• rules_go
• rules_python

En la página de inicio de ejemplos en un repositorio de confianza.

Detecta cadenas de herramientas en la máquina anfitrión

Cuando las reglas de compilación de Bazel necesitan detectar qué cadenas de herramientas están disponibles en tu host. nueva, usan reglas de repositorio para inspeccionar la máquina anfitrión y generar información de la cadena de herramientas como repositorios externos.

• Espacio de trabajo

  Dada la siguiente regla de repositorio para detectar una cadena de herramientas de 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,
  )
  

  Puedes cargar la regla del repositorio en WORKSPACE.

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

• Bzlmod

  Con Bzlmod, puedes ingresar el mismo repositorio usando una extensión de módulo, que es similar a presentar el repositorio @data_file en el último sección.

  ## 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"),
  )
  

  Luego, usa la extensión en el archivo 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")
  

Registra cadenas de herramientas y plataformas de ejecución

Siguiendo la última sección, después de presentar una cadena de herramientas de hosting del repositorio (p.ej., local_config_sh), es probable que desees registrar el de la cadena de herramientas.

• Espacio de trabajo

  Con WORKSPACE, puedes registrar la cadena de herramientas de las siguientes maneras.

  1. Puedes registrar la cadena de herramientas del archivo .bzl y cargar la macro en el 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. También puedes registrar la cadena de herramientas en el archivo WORKSPACE directamente.

     ## 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

  Con Bzlmod, las register_toolchains y register_execution_platforms Las APIs solo están disponibles en el archivo MODULE.bazel. No puedes llamar native.register_toolchains en una extensión 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")
  

Las cadenas de herramientas y las plataformas de ejecución registradas en WORKSPACE WORKSPACE.bzlmod y el archivo MODULE.bazel de cada módulo de Bazel siguen esto. orden de prioridad durante la selección de la cadena de herramientas (de mayor a menor):

1. plataformas de ejecución y cadenas de herramientas registradas en el directorio MODULE.bazel.
2. plataformas de ejecución y cadenas de herramientas registradas en el archivo WORKSPACE archivo WORKSPACE.bzlmod.
3. plataformas de ejecución y cadenas de herramientas registradas por módulos que son (transitivas) del módulo raíz.
4. cuando no se usa WORKSPACE.bzlmod: cadenas de herramientas registradas en WORKSPACE sufijo.

Presenta repositorios locales

Es posible que debas ingresar una dependencia como repositorio local cuando necesites un una versión local de la dependencia para la depuración o si deseas incorporar de tu lugar de trabajo como repositorio externo.

• Espacio de trabajo

  Con WORKSPACE, esto se logra con dos reglas de repositorio nativo: local_repository y new_local_repository

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

• Bzlmod

  Con Bzlmod, puedes usar local_path_override a anular un módulo con una ruta local.

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

  Nota: Con local_path_override, solo puedes ingresar un directorio local como módulo de Bazel, lo que significa que debería tener un archivo MODULE.bazel y su las dependencias transitivas se consideran durante el período de resolución. Además, todas las directivas de anulación de módulo solo se pueden usar en el módulo raíz.

  También es posible introducir un repositorio local con extensión de módulo. Sin embargo, no puedes llamar a native.local_repository en la extensión del módulo. hay esfuerzos continuos por integrar todas las reglas de los repositorios nativos (consultar #18285 para el progreso). Luego, puedes llamar al local_repository de starlark correspondiente en un módulo . También es trivial implementar una versión personalizada de local_repository si esto es un problema de bloqueo para ti.

Vincular destinos

La regla bind en WORKSPACE dejó de estar disponible. no se admite en Bzlmod. Se introdujo para asignar a un objetivo un alias en la paquete especial //external. Todos los usuarios que dependan de esta opción deberían migrar.

Por ejemplo, si tienes

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

Esto permite que otros destinos dependan de //external:openssl. Puedes migrar de esta manera:

• Reemplaza todos los usos de //external:openssl por @my-ssl//src:openssl-lib

• O usa la regla de compilación alias

  • Define el siguiente destino en un paquete (p. ej., //third_party).

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

  • Reemplaza todos los usos de //external:openssl por //third_party:openssl.

Recuperación y sincronización

Los comandos Fetch and Sync se usan para descargar repositorios externos de forma local y mantener los actualizaste. A veces, también para permitir la compilación sin conexión con --nofetch. después de recuperar todos los repositorios necesarios para una compilación.

• Espacio de trabajo

  La sincronización realiza una recuperación forzada de todos los repositorios o de un configurado, mientras que la recuperación solo se usa para recuperar datos de una objetivo.

• Bzlmod

  El comando de sincronización ya no es aplicable, pero recuperar ofertas diversas opciones. Puedes recuperar un destino, un repositorio, un conjunto de repositorios configurados o todos los repositorios involucrados en la resolución de dependencias y las extensiones del módulo. El resultado de la recuperación se almacena en caché y, para forzarla, debes incluir el --force durante el proceso de recuperación.

Migración

En esta sección, se proporciona información y orientación útiles para migrar a Bzlmod el proceso de administración de recursos.

Conoce tus dependencias en WORKSPACE

El primer paso de la migración es comprender qué dependencias tienes. Integra podría ser difícil determinar qué dependencias exactas se introdujeron en el WORKSPACE porque las dependencias transitivas suelen cargarse con *_deps o usar las macros.

Inspecciona una dependencia externa con un archivo resuelto en el espacio de trabajo

Por suerte, la bandera --experimental_repository_resolved_file puede ayudarte. Básicamente, esta marca genera un “archivo de bloqueo” de todas las métricas las dependencias en tu último comando de Bazel. Puedes encontrar más detalles en este blog publicación.

Se puede usar de dos maneras:

1. Recuperar información de las dependencias externas necesarias para compilar ciertos destinos

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

2. Para recuperar información de todas las dependencias externas definidas en el archivo WORKSPACE.

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

   Con el comando bazel sync, puedes recuperar todas las dependencias definidas en el archivo WORKSPACE, que incluye lo siguiente:

   • bind usos
   • register_toolchains y register_execution_platforms usos

   Sin embargo, si tu proyecto es multiplataforma, es posible que la sincronización de Bazel falle en ciertos ya que algunas reglas de repositorios solo podrían ejecutarse correctamente en y plataformas de Google Cloud.

Luego de ejecutar el comando, deberías tener información de tu dependencias en el archivo resolved.bzl.

Cómo inspeccionar una dependencia externa con bazel query

También puedes saber que bazel query se puede usar para inspeccionar reglas del repositorio con

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

Aunque es más conveniente y rápida, la consulta de bazel puede ser versión de dependencia externa, así que ten cuidado de usarlo. Consulta e inspección externas las dependencias con Bzlmod se logra con un nuevo subcomando.

Dependencias predeterminadas integradas

Si revisas el archivo que genera --experimental_repository_resolved_file, encontrarás muchas dependencias que no están definidas en tu WORKSPACE. Esto se debe a que Bazel agrega prefijos y sufijos al WORKSPACE del usuario el contenido del archivo para insertar algunas dependencias predeterminadas, que suelen ser necesarias reglas nativas (p.ej., @bazel_tools, @platforms y @remote_java_tools). Con Bzlmod, esas dependencias se presentan con un módulo integrado bazel_tools , que es una dependencia predeterminada para cada módulo de Bazel.

Modo híbrido para una migración gradual

Bzlmod y WORKSPACE pueden funcionar en paralelo, lo que permite migrar dependencias del archivo WORKSPACE a Bzlmod para que sea un proceso gradual.

Nota: En la práctica, cargar “*_deps” Las macros en WORKSPACE a menudo causan confusión. con dependencias de Bzlmod, por lo que te recomendamos que comiences con WORKSPACE.bzlmod y evita cargar dependencias transitivas con macros.

WORKSPACE.bzlmod

Durante la migración, es posible que los usuarios de Bazel necesiten alternar entre compilaciones con y sin Bzlmod habilitado. Se implementa la compatibilidad con WORKSPACE.bzlmod el proceso de forma más fluida.

WORKSPACE.bzlmod tiene la misma sintaxis que WORKSPACE. Cuando Bzlmod está habilitado, Si también existe un archivo WORKSPACE.bzlmod en la raíz del lugar de trabajo:

• WORKSPACE.bzlmod entra en vigencia y se ignora el contenido de WORKSPACE.
• No se requieren prefijos o sufijos agregado al archivo WORKSPACE.bzlmod.

El uso del archivo WORKSPACE.bzlmod puede facilitar la migración por los siguientes motivos:

• Cuando Bzlmod está inhabilitado, puedes volver a recuperar dependencias del archivo WORKSPACE original.
• Cuando Bzlmod esté habilitado, podrás realizar un mejor seguimiento de las dependencias restantes migrar con WORKSPACE.bzlmod.

Visibilidad del repositorio

Bzlmod puede controlar qué otros repositorios son visibles desde un determinado en el repositorio, marca los nombres de los repositorios y las reglas dependencias para obtener más información.

Este es un resumen de las visibilidades del repositorio de diferentes tipos en los repositorios cuando también se tiene en cuenta WORKSPACE.

	Desde el repositorio principal	Desde los repositorios del módulo de Bazel	De los repositorios de extensión de módulo	Desde los repositorios de WORKSPACE
El repositorio principal	Visible	Si el módulo raíz es una dependencia directa	Si el módulo raíz es una dependencia directa del módulo que aloja la extensión del módulo	Visible
Repositorios del módulo de Bazel	Dependencias directas	Dependencias directas	Dependencias directas del módulo que aloja la extensión del módulo	Dependencias directas del módulo raíz
Repositorios de extensión de módulo	Dependencias directas	Dependencias directas	Las dependencias directas del módulo que alojan la extensión del módulo y todos los repositorios generados por la misma extensión del módulo	Dependencias directas del módulo raíz
Repositorios de WORKSPACE	Todo visible	No visible	No visible	Todo visible

Nota: En el módulo raíz, si se define un repositorio @foo en WORKSPACE y @foo también se usa como repositorio aparente. nombre en MODULE.bazel y, luego, @foo se refiere al que se introdujo en MODULE.bazel.

Nota: Para un repositorio generado por una extensión de módulo @bar, si @foo se usa como un nombre aparente de repositorio de otro repositorio generado por la misma extensión del módulo y las dependencias del módulo que aloja la extensión del módulo y, luego, para el repositorio @bar, @foo se refiere a este último.

Proceso de migración

Un proceso de migración típico de Bzlmod puede verse de la siguiente manera:

1. Comprende qué dependencias tienes en WORKSPACE.
2. Agrega un archivo MODULE.bazel vacío en la raíz de tu proyecto.
3. Agrega un archivo WORKSPACE.bzlmod vacío para anular el contenido del archivo WORKSPACE.
4. Crea tus destinos con Bzlmod habilitado y verifica cuál repositorio es que faltaban.
5. Verifica la definición del repositorio faltante en la dependencia resuelta .
6. Introduce la dependencia faltante como un módulo de Bazel a través de un módulo. o déjala en WORKSPACE.bzlmod para migrarla más tarde.
7. Regresa a 4 y repite el proceso hasta que todas las dependencias estén disponibles.

Herramienta de migración

Hay una secuencia de comandos auxiliar de migración interactiva a Bzlmod que puede ayudarte a comenzar.

La secuencia de comandos hace lo siguiente:

• Genera y analiza el archivo WORKSPACE resuelto.
• Imprime la información del repositorio del archivo resuelto en lenguaje natural.
• Ejecutar el comando de compilación de Bazel, detectar mensajes de error reconocidos y recomendar un y cómo realizar la migración.
• Verifica si una dependencia ya está disponible en BCR.
• Agrega una dependencia al archivo MODULE.bazel.
• Agrega una dependencia a través de una extensión de módulo.
• Agrega una dependencia al archivo WORKSPACE.bzlmod.

Para usarlo, asegúrate de tener instalada la versión más reciente de Bazel y ejecuta la siguiente 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>

Nota: La secuencia de comandos de migración no es perfecta y es posible que no esté actualizada, ya que Bzlmod está evolucionando, así que siempre verifica que la solución recomendada sea correcta.

Publica módulos de Bazel

Si tu proyecto de Bazel es una dependencia para otros proyectos, puedes publicar tu proyecto en el Registro Central de Bazel.

Para poder verificar tu proyecto en BCR, necesitas una URL de archivo de origen de el proyecto. Ten en cuenta lo siguiente cuando crees el archivo de origen:

• Asegúrate de que el archivo dirija a una versión específica.

  BCR solo acepta archivos de origen con versión porque Bzlmod debe realizar una comparación de versiones durante la resolución de dependencias.

• Asegúrate de que la URL del archivo sea estable.

  Bazel verifica el contenido del archivo con un valor de hash, por lo que debes asegúrate de que la suma de comprobación del archivo descargado nunca cambie. Si la URL es de GitHub, crea y sube un archivo de la versión en la página de la versión. GitHub no garantizará la suma de comprobación de los archivos de origen generados en demanda. En resumen, las URL en forma de https://github.com/<org>/<repo>/releases/download/... se considera estable mientras que https://github.com/<org>/<repo>/archive/... no. Consulta GitHub Archivar suma de comprobación Interrupción para obtener más contexto.

• Asegúrate de que el árbol de fuentes siga el diseño del repositorio original.

  En caso de que tu repositorio sea muy grande y quieras crear una distribución de tamaño reducido eliminando las fuentes innecesarias, haz asegúrate de que el árbol de fuentes seccionado sea un subconjunto del árbol de fuentes original. Esta hace que sea más fácil para los usuarios finales anular el módulo con una versión versión de archive_override y git_override.

• Incluye un módulo de prueba en un subdirectorio que pruebe las aplicaciones más comunes. APIs.

  Un módulo de prueba es un proyecto de Bazel con sus propios WORKSPACE y MODULE.bazel. ubicado en un subdirectorio del archivo de origen, que depende del módulo que se publicará. Debe contener ejemplos o algunos de integración que abarcan tus APIs más comunes. Cheque módulo de prueba para aprender a configurarlo.

Cuando la URL del archivo fuente esté lista, sigue la contribución de BCR. lineamientos para enviar tu módulo a BCR con un repositorio Solicitud de extracción.

Es muy recomendable configurar la opción Publicar en BCR GitHub para tu para automatizar el proceso de envío de tu módulo a BCR.

Prácticas recomendadas

En esta sección, se documentan algunas prácticas recomendadas administrar tus dependencias externas.

Divide los objetivos en diferentes paquetes para evitar recuperar dependencias innecesarias.

Marca #12835, donde dev las dependencias para las pruebas se fuerzan a recuperarse de manera innecesaria para compilar objetivos que no los necesitan. En realidad, no es específico de Bzlmod, pero seguir estas prácticas facilita la especificación correcta de dependencias de desarrollo.

Cómo especificar dependencias de desarrollo

Puedes configurar el atributo dev_dependency como verdadero para bazel_dep y directivas use_extension para no se propagan a proyectos dependientes. Como módulo raíz, puedes usar el Marca --ignore_dev_dependency para verificar si tus destinos seguir compilando sin dependencias de desarrollo ni anulaciones.

Progreso de la migración de la comunidad

Puedes consultar Bazel Central Registry para encontrar si tus dependencias ya están disponibles. De lo contrario, no dudes en unirte debate de GitHub para vota a favor o publica las dependencias que bloquean la migración.

Cómo informar problemas

Consulta la lista de problemas de Bazel en GitHub para obtener información sobre Bzlmod conocidos. problemas. No dudes en informar sobre nuevos problemas o solicitudes de funciones que te ayuden a desbloquear la migración.