Guía de migración de Bzlmod

Informar un problema Ver fuente Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Debido a las deficiencias de WORKSPACE, Bzlmod reemplazará el sistema WORKSPACE heredado. El archivo WORKSPACE ya está inhabilitado en Bazel 8 (finales de 2024) y se quitará en Bazel 9 (finales de 2025). Esta guía te ayuda a migrar tu proyecto a Bzlmod y a descartar WORKSPACE para administrar las dependencias externas.

¿Por qué migrar a Bzlmod?

  • Hay muchas ventajas en comparación con el sistema heredado de WORKSPACE, lo que ayuda a garantizar un crecimiento saludable del ecosistema de Bazel.

  • Si tu proyecto es una dependencia de otros proyectos, migrar a Bzlmod desbloqueará su migración y les facilitará depender de tu proyecto.

  • La migración a Bzlmod es un paso necesario para usar versiones futuras de Bazel (obligatorio en Bazel 9).

¿Cómo migrar a Bzlmod?

Proceso de migración recomendado:

  1. Usa la herramienta de migración como herramienta auxiliar para optimizar el proceso de migración lo más posible. Consulta las secciones de la herramienta de migración y cómo usarla.
  2. Si quedan errores después de usar la herramienta de migración, resuélvelos de forma manual. Para comprender las principales diferencias entre los conceptos dentro de los archivos WORKSPACE y MODULE.bazel, consulta la sección WORKSPACE versus Bzlmod.

Herramienta de migración

Para simplificar el proceso, a menudo complejo, de pasar de WORKSPACE a Bzlmod, se recomienda usar el script de migración. Esta herramienta de ayuda automatiza muchos de los pasos involucrados en la migración de tu sistema externo de administración de dependencias.

Funcionalidad principal

Las funciones principales de la secuencia de comandos son las siguientes:

  • Recopilación de información de dependencias: Analiza el archivo WORKSPACE de tu proyecto para identificar los repositorios externos que usan los objetivos de compilación especificados. Usa la marca experimental_repository_resolved_file de Bazel para generar un archivo resolved_deps.py que contenga esta información.
  • Identificación de dependencias directas: Usa bazel query para determinar qué repositorios son dependencias directas para los destinos especificados.
  • Migración a Bzlmod: Traduce las dependencias WORKSPACE pertinentes a sus equivalentes de Bzlmod. Este es un proceso de dos pasos:
    1. Intenta introducir todas las dependencias directas identificadas en el archivo MODULE.bazel.
    2. Intenta compilar los destinos especificados con Bzlmod habilitado y, luego, identifica y corrige de forma iterativa los errores reconocibles. Este paso es necesario, ya que es posible que falten algunas dependencias en el primer paso.
  • Generación del informe de migración: Crea un archivo migration_info.md que documenta el proceso de migración. Este informe incluye una lista de las dependencias directas, las declaraciones de Bzlmod generadas y los pasos manuales que pueden ser necesarios para completar la migración.

La herramienta de migración admite lo siguiente:

  • Dependencias disponibles en el registro central de Bazel
  • Reglas de repositorio personalizadas definidas por el usuario
  • [Próximamente] Dependencias del administrador de paquetes

Nota importante: La herramienta de migración es una utilidad que se ofrece según el criterio del mejor esfuerzo. Siempre verifica la exactitud de sus recomendaciones.

Cómo usar la herramienta de migración

Antes de comenzar:

  • Actualiza a la versión más reciente de Bazel 7, que proporciona compatibilidad sólida con WORKSPACE y Bzlmod.

  • Verifica que el siguiente comando se ejecute correctamente para los principales destinos de compilación de tu proyecto:

    bazel build --nobuild --enable_workspace --noenable_bzlmod <targets>

Una vez que se cumplan los requisitos previos, ejecuta los siguientes comandos para usar la herramienta de migración:

# Clone the Bazel Central Registry repository
git clone https://github.com/bazelbuild/bazel-central-registry.git
cd bazel-central-registry

# Build the migration tool
bazel build //tools:migrate_to_bzlmod

# Create a convenient alias for the tool
alias migrate2bzlmod=$(realpath ./bazel-bin/tools/migrate_to_bzlmod)

# Navigate to your project's root directory and run the tool
cd <your workspace root>
migrate2bzlmod -t <your build targets>

WORKSPACE vs. Bzlmod

WORKSPACE de Bazel y Bzlmod ofrecen funciones similares con una sintaxis diferente. En esta sección, se explica cómo migrar desde funcionalidades específicas de WORKSPACE a Bzlmod.

Cómo definir la raíz de un espacio de trabajo de Bazel

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

  • WORKSPACE

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

Habilita Bzlmod en tu archivo 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 para tu espacio de trabajo

  • WORKSPACE

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

    ## WORKSPACE
workspace(name = "com_foo_bar")

  • Bzlmod

    Se recomienda hacer referencia a los destinos en el mismo espacio de trabajo con la sintaxis //foo:bar sin @<repo name>. Sin embargo, si necesitas la sintaxis anterior, puedes usar el nombre del módulo especificado por la función module como el nombre del repositorio. Si el nombre del módulo es diferente del nombre del repositorio necesario, 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 adopte Bzlmod.

  • WORKSPACE

    Con WORKSPACE, es común usar las reglas de 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 necesiten cargar dependencias transitivas desde una macro de la dependencia. Supongamos que tanto bazel_skylib como rules_java dependen de platform. La versión exacta de la dependencia de 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, puedes depender de ella 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 las dependencias de los módulos de Bazel de forma transitiva con el algoritmo MVS. Por lo tanto, la versión máxima requerida de platform se selecciona automáticamente.

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

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

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

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

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

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

  • WORKSPACE

    Descarga un archivo con la regla del 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 tu archivo MODULE.bazel para crear instancias de repositorios directamente:

    ## 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, esto se implementa con una extensión de módulo. Si necesitas realizar una lógica más compleja que simplemente invocar una regla de repo, también puedes implementar una extensión de módulo por tu cuenta. Deberás mover la definición a un archivo .bzl, lo que también te permitirá 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 del módulo para cargar la macro de dependencias. Puedes definirlo 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 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")

Resuelve conflictos de dependencias externas con la extensión del módulo

Un proyecto puede proporcionar una macro que introduce repositorios externos según las entradas de sus llamadores. Pero ¿qué sucede si hay varios llamadores en el gráfico de dependencia y causan 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
    )

  • WORKSPACE

    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 con cuidado el orden de las macros en WORKSPACE para obtener la versión que necesita. Este es uno de los mayores problemas con WORKSPACE, ya que no proporciona una forma sensata de resolver las dependencias.

  • Bzlmod

    Con Bzlmod, el autor del proyecto foo puede usar la extensión del módulo para resolver conflictos. Por ejemplo, supongamos que siempre tiene sentido seleccionar 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.

Integra un administrador de paquetes de terceros

Siguiendo 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 lógica personalizada para resolver dependencias y llamar a reglas de repositorio para introducir 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.

Lee la página sobre las extensiones de módulos para obtener más información sobre cómo usarlas.

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

En el repositorio de ejemplos, se encuentra disponible un ejemplo mínimo que integra un administrador de paquetes pseudo.

Detecta cadenas de herramientas en la máquina host

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

  • WORKSPACE

    Se proporciona la siguiente regla del 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 introducir el mismo repositorio con una extensión de módulo, que es similar a la introducción del 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")

Cómo registrar cadenas de herramientas y plataformas de ejecución

Después de la última sección, luego de introducir información de la cadena de herramientas de hosting del repositorio (p.ej., local_config_sh), probablemente quieras registrar la cadena de herramientas.

  • WORKSPACE

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

    1. Puedes registrar la cadena de herramientas en el 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 precedencia durante la selección de la cadena 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. Las cadenas de herramientas y las plataformas de ejecución registradas por los 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

Presentamos los repositorios locales

Es posible que debas introducir una dependencia como un repositorio local cuando necesites una versión local de la dependencia para depurar o cuando quieras incorporar un directorio en tu espacio de trabajo como repositorio externo.

  • WORKSPACE

    Con WORKSPACE, esto se logra con dos reglas de repositorio nativas, 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 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. Se está trabajando para convertir todas las reglas del repositorio nativo a Starlark (consulta #18285 para ver el progreso). Luego, puedes llamar al local_repository de Starlark correspondiente en una extensión del módulo. También es trivial implementar una versión personalizada de la regla del repositorio local_repository si este es un problema que te impide avanzar.

Vincular destinos

La regla bind en WORKSPACE dejó de estar disponible y no se admite en Bzlmod. Se introdujo para darle un alias a un destino en el paquete especial //external. Todos los usuarios que dependan de esto deben 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 dejar de usar esta opción, haz lo siguiente:

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

    • Sugerencia: Usa el comando bazel query --output=build --noenable_bzlmod --enable_workspace [target] para encontrar información relevante sobre el objetivo.

  • O bien 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 forma 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.

  • WORKSPACE

    Sync realiza una recuperación forzada para todos los repositorios o para un conjunto específico de repositorios configurados, mientras que fetch se usa solo para recuperar un destino específico.

  • Bzlmod

    El comando de sincronización ya no se aplica, 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 dependencias 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 manual

En esta sección, se proporciona información y orientación útiles para tu proceso de migración manual a Bzlmod. Para obtener un proceso de migración más automatizado, consulta la sección proceso de migración recomendado.

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 introducen en el archivo WORKSPACE, ya que las dependencias transitivas suelen cargarse con macros *_deps.

Inspecciona la dependencia externa con el archivo resuelto del espacio de trabajo

Afortunadamente, la marca --experimental_repository_resolved_file puede ayudar. Esta marca genera esencialmente un "archivo de bloqueo" de todas las dependencias externas recuperadas en tu último comando de Bazel. Puedes encontrar más detalles en esta entrada de blog.

Puede usarse de dos formas:

  1. Recupera 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. Recupera 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 incluyen lo siguiente:

    • Usos de bind
    • Usos de register_toolchains y register_execution_platforms

    Sin embargo, si tu proyecto es multiplataforma, es posible que la sincronización de Bazel falle en ciertas plataformas porque algunas reglas del repositorio solo se ejecutan correctamente en las plataformas compatibles.

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

Inspecciona la dependencia externa con bazel query

También puedes usar bazel query para inspeccionar las reglas del repositorio con

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

Si bien es más conveniente y mucho más rápido, bazel query puede mentir sobre la versión de la dependencia externa, por lo que debes tener cuidado al usarlo. La consulta y la inspección de dependencias externas con Bzlmod se lograrán 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, de hecho, agrega prefijos y sufijos al contenido del archivo WORKSPACE del usuario para insertar algunas dependencias predeterminadas, que suelen ser necesarias para 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 la migración gradual

Bzlmod y WORKSPACE pueden funcionar 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 alternar entre compilaciones con Bzlmod habilitado y sin él. Se implementó 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 espacio de trabajo, sucede lo siguiente:

  • WORKSPACE.bzlmod entra en vigencia y se ignora el contenido de WORKSPACE.
  • No se agregan prefijos ni sufijos al archivo WORKSPACE.bzlmod.

Usar el archivo WORKSPACE.bzlmod puede facilitar la migración por los siguientes motivos:

  • Cuando Bzlmod está inhabilitado, vuelves a recuperar las dependencias del archivo WORKSPACE original.
  • Cuando Bzlmod está habilitado, puedes hacer un mejor seguimiento de las dependencias que quedan por migrar con WORKSPACE.bzlmod.

Visibilidad del repositorio

Bzlmod puede controlar qué otros repositorios son visibles desde un repositorio determinado. Consulta Nombres de repositorios y dependencias estrictas para obtener más detalles.

A continuación, se incluye un resumen de la visibilidad de los repositorios de diferentes tipos cuando también se tiene en cuenta WORKSPACE.

Desde el repo principal Desde repositorios de módulos de Bazel Desde repositorios de extensiones de módulos Desde repositorios de WORKSPACE
El repo 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 extensiones de módulos Dependencias directas Dependencias directas Dependencias directas del módulo que aloja 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

Proceso de migración manual

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. Compila tus destinos con Bzlmod habilitado y verifica qué repositorio falta.
  5. Verifica la definición del repositorio faltante 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. Vuelve al paso 4 y repite el proceso hasta que todas las dependencias estén disponibles.

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 el BCR, necesitas la URL de archivo fuente del proyecto. Ten en cuenta algunos aspectos cuando crees el archivo fuente:

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

    El BCR solo puede aceptar archivos fuente con versiones porque Bzlmod necesita 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 asegurarte de que la suma de comprobación del archivo descargado nunca cambie. Si la URL es de GitHub, crea y sube un archivo de versión en la página de versiones. GitHub no garantizará la suma de verificación de los archivos fuente generados a pedido. En resumen, las URLs con el formato https://github.com/<org>/<repo>/releases/download/... se consideran estables, mientras que las URLs con el formato https://github.com/<org>/<repo>/archive/... no. Consulta GitHub Archive Checksum Outage para obtener más contexto.

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

    En caso de que tu repositorio sea muy grande y quieras crear un archivo de distribución con un tamaño reducido quitando las 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 reemplacen el módulo por una versión que no sea de lanzamiento con archive_override y git_override.

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

    Un módulo de prueba es un proyecto de Bazel con sus propios archivos WORKSPACE y MODULE.bazel ubicados en un subdirectorio del archivo fuente que depende del módulo real que se publicará. Debe contener ejemplos o algunas pruebas de integración que cubran tus APIs más comunes. Consulta módulo de prueba para obtener más información sobre cómo configurarlo.

Cuando tengas lista la URL del archivo fuente, sigue los lineamientos para contribuir con el BCR y envía tu módulo al BCR con una solicitud de extracción de GitHub.

Se recomienda configurar la app de GitHub Publish to BCR para tu repositorio y, así, automatizar el proceso de envío de tu módulo al 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 destinos en diferentes paquetes para evitar recuperar dependencias innecesarias.

Consulta #12835, donde se fuerza la recuperación innecesaria de dependencias de desarrollo para compilar destinos que no las necesitan. En realidad, esto no es específico de Bzlmod, pero seguir estas prácticas facilita la especificación correcta de las dependencias de desarrollo.

Cómo especificar dependencias de desarrollo

Puedes establecer el atributo dev_dependency como verdadero para las directivas bazel_dep y use_extension para que no se propaguen a los 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 ni anulaciones.

Progreso de la migración de la comunidad

Puedes consultar el Registro central de Bazel para saber si tus dependencias ya están disponibles. De lo contrario, no dudes en unirte a este debate de GitHub para votar a favor o publicar las dependencias que bloquean tu migración.

Cómo informar problemas

Consulta la lista de problemas de Bazel en GitHub para conocer los problemas conocidos de Bzlmod. No dudes en informar problemas nuevos o solicitar funciones que puedan ayudarte a desbloquear tu migración.