Guía de migración de Bzlmod

Informar un problema Ver fuente

Debido a las deficiencias de WORKSPACE, Bzlmod reemplazará el sistema WORKSPACE heredado en versiones futuras de Bazel. Esta guía te ayuda a migrar tu proyecto a Bzlmod y descartar WORKSPACE para recuperar dependencias externas.

WORKSPACE frente a Bzlmod

WORKSPACE y Bzlmod de Bazel ofrecen funciones similares con una sintaxis diferente. En esta sección, 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. En las versiones de Bazel anteriores a la 6.3, debería haber un archivo WORKSPACE o WORKSPACE.bazel en la raíz del lugar de trabajo, quizás con comentarios como los siguientes:

  • Espacio de trabajo

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

Habilita 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 que se aplique a todos los comandos:

  • .bazelrc

    # Enable Bzlmod for every Bazel command
common --enable_bzlmod

Especifica el nombre del repositorio de tu lugar de trabajo

  • Espacio de trabajo

    La función workspace se usa a fin de especificar un nombre de repositorio para tu lugar de trabajo. Esto permite que se haga referencia a un //foo:bar de destino en el lugar de trabajo como @<workspace name>//foo:bar. Si no se especifica, el nombre predeterminado del repositorio de tu lugar de trabajo es __main__.

    ## WORKSPACE
workspace(name = "com_foo_bar")

  • Bzlmod

    Se recomienda hacer referencia a destinos en el mismo lugar de trabajo con la sintaxis //foo:bar sin @<repo name>. Sin embargo, si necesitas la sintaxis anterior, puedes usar el nombre del módulo que especifica la función module como nombre del repositorio. Si el nombre del módulo es diferente del nombre del repositorio que se necesita, puedes usar el atributo repo_name de la función module para anular 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 las reglas del repositorio http_archive o git_repository para descargar las fuentes del proyecto de 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 dependencias transitivas de una macro de la dependencia. Supongamos que bazel_skylib y rules_java dependen de platform; la versión exacta de la dependencia platform se determina según el orden de las macros.

  • Bzlmod

    Con Bzlmod, siempre que tu dependencia esté disponible en el registro central de Bazel o en tu registro de Bazel personalizado, simplemente puedes depender de él con una 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 dependencias de módulos de Bazel de forma transitiva mediante el algoritmo MVS. Por lo tanto, la versión máxima requerida de platform se selecciona automáticamente.

Anula una dependencia como módulo de Bazel

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

Para obtener más información, consulta la sección de overrides.

Puedes encontrar algunos ejemplos de uso en el repositorio de ejemplos.

Recupera dependencias externas con extensiones de módulo

Si tu dependencia no es un proyecto de Bazel o aún no está disponible en ningún registro de Bazel, puedes ingresarla con use_repo_rule o extensiones de módulos.

  • Espacio de trabajo

    Descarga un archivo con la regla de repositorio http_file.

    ## 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 el archivo MODULE.bazel para crear instancias de repositorios de forma directa:

    ## 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 con una extensión de módulo. Si necesitas realizar una lógica más compleja que solo invocar una regla de repositorio, también puedes implementar una extensión de módulo por tu cuenta. Deberás mover la definición a 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 definirla en el mismo archivo .bzl de la macro, pero, para mantener la compatibilidad con versiones anteriores de Bazel, es mejor definirla en un archivo .bzl independiente.

    ## 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 repositorio sea visible para el proyecto raíz, debes declarar los usos de la extensión del módulo y el 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")

Resolver conflictos de dependencias externas con la extensión de módulo

Un proyecto puede proporcionar una macro que introduzca repositorios externos basados en las entradas de sus emisores. Pero ¿qué sucede si hay varios emisores en el gráfico de dependencia y generan un conflicto?

Supongamos que el proyecto foo proporciona la siguiente macro, que toma version como 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 la dependencia de datos.

    ## 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 el ESPACIO DE TRABAJO para obtener la versión que necesita. Este es uno de los mayores problemas de WORKSPACE, ya que en realidad no proporciona una forma razonable de resolver dependencias.

  • Bzlmod

    Con Bzlmod, el autor del proyecto foo puede usar la extensión del módulo para resolver conflictos. Por ejemplo, supongamos que tiene sentido seleccionar siempre 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 dependencia bar requiere 3.0. La extensión del módulo en foo puede resolver correctamente este conflicto y seleccionar automáticamente la versión 3.0 para la dependencia de datos.

Cómo integrar el administrador de paquetes de terceros

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

Consulta la página de extensiones de módulos para obtener más información sobre su uso.

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

En el repositorio de ejemplos, puedes encontrar un ejemplo mínimo que integra un pseudoadministrador de paquetes.

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 máquina host, usan reglas del repositorio para inspeccionarla 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 con una extensión de módulo, que es similar a introducir el repositorio @data_file en la última 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

Después de la última sección, después de introducir un repositorio que aloja información de la cadena de herramientas (p.ej., local_config_sh), es probable que desees registrar 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 archivo 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 directamente en el archivo 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

    Con Bzlmod, las APIs de register_toolchains y register_execution_platforms solo están disponibles en el archivo MODULE.bazel. No puedes llamar a 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 este orden de prioridad durante la selección de las cadenas de herramientas (de mayor a menor):

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

Presentación de los repositorios locales

Es posible que debas ingresar una dependencia como repositorio local cuando necesites una versión local de la dependencia para la depuración o si deseas incorporar un directorio en 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 para anular un módulo con una ruta de acceso local.

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

    También es posible ingresar un repositorio local con extensión de módulo. Sin embargo, no puedes llamar a native.local_repository en la extensión de módulo, ya que se realizan esfuerzos continuos por habilitar con estrella todas las reglas del repositorio nativo (verifica #18285 para ver el progreso). Luego, puedes llamar al local_repository de starlark correspondiente en una extensión de módulo. También es insignificante implementar una versión personalizada de la regla del repositorio local_repository si esto es un problema de bloqueo para ti.

Vincular destinos

La regla bind en WORKSPACE está obsoleta y no es compatible con Bzlmod. Se introdujo para asignar un alias a un objetivo en el paquete //external especial. Todos los usuarios que dependan de esta función deberán migrar.

Por ejemplo, si tienes

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

Esto permite que otros destinos dependan de //external:openssl. Para alejarte de esto, puedes hacer lo siguiente:

  • 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 frente a sincronización

Los comandos de recuperación y sincronización se usan para descargar repositorios externos de manera local y mantenerlos actualizados. A veces, también para permitir la compilación sin conexión con la marca --nofetch después de recuperar todos los repositorios necesarios para una compilación.

  • Espacio de trabajo

    La sincronización realiza una recuperación forzada para todos los repositorios o para un conjunto específico de repositorios configurado, mientras que la recuperación solo se usa para recuperar un destino específico.

  • Bzlmod

    El comando de sincronización ya no es aplicable, pero la recuperación ofrece varias opciones. Puedes recuperar un destino, un repositorio, un conjunto de repositorios configurados o todos los repositorios involucrados en la resolución de tu dependencia y las extensiones de módulos. El resultado de la recuperación se almacena en caché y, para forzar una recuperación, debes incluir la opción --force durante el proceso de recuperación.

Migración

En esta sección, se proporciona información y orientación útiles para tu proceso de migración de Bzlmod.

Conoce tus dependencias en WORKSPACE

El primer paso de la migración es comprender qué dependencias tienes. Puede ser difícil determinar qué dependencias exactas se ingresan en el archivo WORKSPACE, ya que las dependencias transitivas a menudo se cargan con macros *_deps.

Inspecciona la dependencia externa con el archivo resuelto de Workspace

Afortunadamente, la marca --experimental_repository_resolved_file puede ayudar. En esencia, esta marca genera un “archivo de bloqueo” de todas las dependencias externas recuperadas en tu último comando de Bazel. Puedes obtener más información en esta entrada de blog.

Puede usarse de dos maneras:

  1. Para recuperar información de 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, incluidas las siguientes:

    • bind usos
    • Usos de register_toolchains y register_execution_platforms

    Sin embargo, si tu proyecto es multiplataforma, la sincronización de Bazel puede fallar en ciertas plataformas porque algunas reglas del repositorio pueden ejecutarse correctamente solo en las plataformas compatibles.

Después de ejecutar el comando, debes tener información de tus dependencias externas en el archivo resolved.bzl.

Cómo inspeccionar una dependencia externa con bazel query

Es posible que también sepas que bazel query se puede usar para inspeccionar reglas del repositorio con

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

Si bien es más conveniente y mucho más rápida, la consulta de Bazel puede ser acerca de la versión de la dependencia externa, así que ten cuidado de usarla. La consulta y la inspección de dependencias externas con Bzlmod se logrará con un subcomando nuevo.

Dependencias predeterminadas integradas

Si verificas 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, en realidad, Bazel agrega prefijos y sufijos al contenido del archivo WORKSPACE del usuario para insertar algunas dependencias predeterminadas, que suelen ser necesarias en las reglas nativas (p.ej., @bazel_tools, @platforms y @remote_java_tools). Con Bzlmod, esas dependencias se introducen con un módulo integrado bazel_tools, que es una dependencia predeterminada para todos los demás módulos de Bazel.

Modo híbrido para una migración gradual

Bzlmod y WORKSPACE pueden trabajar en paralelo, lo que permite que la migración de dependencias del archivo WORKSPACE a Bzlmod sea un proceso gradual.

WORKSPACE.bzlmod

Durante la migración, es posible que los usuarios de Bazel deban cambiar entre compilaciones con Bzlmod habilitado o sin él. Se implementa la compatibilidad con WORKSPACE.bzlmod para que el proceso sea más fluido.

WORKSPACE.bzlmod tiene exactamente 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:

  • Se aplica WORKSPACE.bzlmod, y se ignora el contenido de WORKSPACE.
  • No se agregan prefijos ni sufijos al archivo WORKSPACE.bzlmod.

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

  • Cuando Bzlmod está inhabilitado, recurres a la recuperación de dependencias del archivo WORKSPACE original.
  • Cuando Bzlmod está habilitado, puedes realizar un mejor seguimiento de las dependencias que quedan para migrar con WORKSPACE.bzlmod.

Visibilidad del repositorio

Bzlmod puede controlar qué otros repositorios son visibles de un repositorio determinado. Consulta los nombres de los repositorios y las dependencias strict para obtener más detalles.

A continuación, se muestra un resumen de las visibilidades de los repositorios de diferentes tipos de repositorios cuando también se tiene en cuenta WORKSPACE.

Desde el repositorio principal Desde repositorios de módulos de Bazel Desde repositorios de extensiones del módulo De 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 de módulos 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 Dependencias directas del módulo que aloja la extensión del módulo + todos los repositorios generados por la misma extensión de módulo Dependencias directas del módulo raíz
Repositorios de WORKSPACE Todos visibles No visible No visible Todos visibles

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 del proyecto.
  3. Agrega un archivo WORKSPACE.bzlmod vacío para anular el contenido del archivo WORKSPACE.
  4. Compila tus objetivos con Bzlmod habilitado y verifica qué repositorio falta.
  5. Verifica la definición del repositorio que falta en el archivo de dependencia resuelto.
  6. Introduce la dependencia faltante como un módulo de Bazel, a través de una extensión de módulo, o déjala en WORKSPACE.bzlmod para una migración posterior.
  7. Regresa a la versión 4 y repite el proceso hasta que todas las dependencias estén disponibles.

Herramienta de migración

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

La secuencia de comandos hace lo siguiente:

  • Genera y analiza el archivo resuelto de WORKSPACE.
  • Imprime información del repositorio desde el archivo resuelto de manera legible por humanos.
  • Ejecuta el comando de compilación de Bazel, detecta los mensajes de error reconocidos y recomienda una forma de migrar.
  • 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 el 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>

Publica módulos de Bazel

Si tu proyecto de Bazel es una dependencia de otros proyectos, puedes publicarlo en el registro central de Bazel.

Para poder registrar tu proyecto en BCR, necesitas una URL de archivo de origen del proyecto. Ten en cuenta algunas cuestiones cuando crees el archivo fuente:

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

    BCR solo puede aceptar archivos de origen con versiones porque Bzlmod debe realizar una comparación de versiones durante la resolución de dependencia.

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

    Bazel verifica el contenido del archivo mediante un valor de hash, por lo que debes asegurarte de que la suma de verificació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 verificación de los archivos de origen generados a pedido. En resumen, las URLs con el formato https://github.com/<org>/<repo>/releases/download/... se consideran estables, mientras que https://github.com/<org>/<repo>/archive/... no lo es. Consulta Interrupción de la suma de comprobación de archivo de GitHub 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 desees crear un archivo de distribución con un tamaño reducido mediante la eliminación de fuentes innecesarias, asegúrate de que el árbol de fuentes quitado sea un subconjunto del árbol de fuentes original. Esto facilita que los usuarios finales anulen el módulo a una versión no de lanzamiento mediante archive_override y git_override.

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

    Un módulo de prueba es un proyecto de Bazel con su propio WORKSPACE y archivo MODULE.bazel ubicado en un subdirectorio del archivo de origen, que depende del módulo real que se publicará. Debe contener ejemplos o algunas pruebas de integración que abarquen las APIs más comunes. Consulta el módulo de prueba para aprender a configurarlo.

Cuando tengas lista la URL del archivo de origen, sigue los lineamientos de contribución a BCR para enviar tu módulo a BCR con una solicitud de extracción de GitHub.

Te recomienda configurar la app de GitHub Publica en BCR para tu repositorio a fin de 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 que debes seguir para administrar mejor tus dependencias externas.

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

Marca #12835, donde las dependencias de desarrollo para las pruebas se fuerzan a recuperarse innecesariamente para compilar destinos que no los necesitan. En realidad, no es específico de Bzlmod, pero si sigues estas prácticas, es más fácil especificar correctamente las dependencias de desarrollo.

Cómo especificar las dependencias de desarrollo

Puedes configurar el atributo dev_dependency como verdadero para las directivas bazel_dep y use_extension a fin de que no se propaguen en proyectos dependientes. Como módulo raíz, puedes usar la marca --ignore_dev_dependency para verificar si tus destinos aún se compilan sin dependencias de desarrollo.

Progreso de la migración a las comunidades

Puedes consultar el registro central de Bazel para averiguar si tus dependencias ya están disponibles. De lo contrario, puedes unirte a esta debate de GitHub para votar a favor o publicar las dependencias que bloquean la migración.

Cómo informar problemas

Consulta la lista de problemas de Bazel en GitHub para conocer los problemas conocidos de Bzlmod. Puedes informar problemas nuevos o solicitar funciones que te ayuden a desbloquear la migración.