Bzlmod es el nombre interno del nuevo sistema de dependencias externas que se introdujo en Bazel 5.0. Se introdujo para abordar varios puntos problemáticos del sistema anterior que no se podía corregir de forma incremental. Consulta la sección Declaración del problema del documento de diseño original para obtener más detalles.
En Bazel 5.0, Bzlmod no está activado de forma predeterminada; se debe especificar la marca --experimental_enable_bzlmod para que se aplique lo siguiente. Tal como lo sugiere el nombre de la marca, esta función se encuentra actualmente en estado experimental. Las APIs y los comportamientos pueden cambiar hasta que se lance oficialmente.
Para migrar tu proyecto a Bzlmod, sigue la Guía de migración de Bzlmod. También puedes encontrar ejemplos de usos de Bzlmod en el repositorio de ejemplos.
Módulos de Bazel
El antiguo sistema de dependencias externo basado en WORKSPACE se centra en repositorios (o repositorios) creados mediante reglas de repositorio (o reglas de repositorio).
Si bien los repositorios siguen siendo un concepto importante en el nuevo sistema, los módulos son las unidades principales de dependencia.
En esencia, un módulo es un proyecto de Bazel que puede tener varias versiones, cada una de las cuales publica metadatos sobre otros módulos de los que depende. Esto es análogo a conceptos conocidos en otros sistemas de administración de dependencias: un artefacto de Maven, un paquete de npm, un contenedor de Cargo, un módulo de Go, etcétera.
Un módulo simplemente especifica sus dependencias con los pares name y version, en lugar de URLs específicas en WORKSPACE. Luego, se buscan las dependencias en un registro de Bazel; de forma predeterminada, en el registro central de Bazel. En tu espacio de trabajo, cada módulo se convierte en un repositorio.
MODULE.bazel
Cada versión de cada módulo tiene un archivo MODULE.bazel que declara sus dependencias y otros metadatos. A continuación, se muestra un ejemplo básico:
module(
name = "my-module",
version = "1.0",
)
bazel_dep(name = "rules_cc", version = "0.0.1")
bazel_dep(name = "protobuf", version = "3.19.0")
El archivo MODULE.bazel debe estar ubicado en la raíz del directorio del lugar de trabajo
(junto al archivo WORKSPACE). A diferencia del archivo WORKSPACE, no necesitas especificar tus dependencias transitivas. En cambio, solo debes especificar dependencias directas, y sus archivos MODULE.bazel se procesarán para descubrir dependencias transitivas automáticamente.
El archivo MODULE.bazel es similar a los archivos BUILD, ya que no admite ninguna forma de flujo de control. Además, prohíbe las declaraciones load. Las directivas que admiten los archivos MODULE.bazel son las siguientes:
module, para especificar metadatos sobre el módulo actual, incluido su nombre, versión, etcéterabazel_dep, para especificar dependencias directas en otros módulos de Bazel- Anulaciones, que solo puede usar el módulo raíz (es decir, no un módulo que se usa como dependencia) para personalizar el comportamiento de una dependencia directa o transitiva determinada:
- Directivas relacionadas con las extensiones de módulos:
Formato de la versión
Bazel tiene un ecosistema diverso, y los proyectos usan varios esquemas de control de versiones. La más popular es, por mucho, SemVer, pero también hay proyectos importantes que usan diferentes esquemas, como Abseil, cuyas versiones están basadas en fechas, como 20210324.2.
Por este motivo, Bzlmod adopta una versión más relajada de la especificación de SemVer. Las diferencias incluyen las siguientes:
- SemVer establece que la parte de “actualización” de la versión debe tener 3 segmentos:
MAJOR.MINOR.PATCH. En Bazel, este requisito se flexibiliza para que se permita cualquier cantidad de segmentos. - En SemVer, cada uno de los segmentos de la parte “release” debe contener solo dígitos. En Bazel, esto se flexibiliza para permitir letras también, y la semántica de comparación coincide con los "identificadores" de la parte de "prelanzamiento".
- Además, no se aplica la semántica de los aumentos de versión mayor, menor y de parche. (Sin embargo, consulta el nivel de compatibilidad para obtener detalles sobre cómo denotamos la retrocompatibilidad).
Cualquier versión válida de SemVer es una versión válida del módulo de Bazel. Además, dos versiones de SemVer a y b comparan a < b con las mismas conservaciones cuando se comparan con versiones de módulos de Bazel.
Resolución de la versión
El problema de la dependencia de diamante es un elemento básico en el espacio de administración de dependencias con control de versiones. Supongamos que tienes el siguiente gráfico de dependencias:
A 1.0
/ \
B 1.0 C 1.1
| |
D 1.0 D 1.1
¿Qué versión de D debería usar? Para resolver esta pregunta, Bzlmod usa el algoritmo de Selección de versión mínima (MVS) que se introdujo en el sistema del módulo de Go. MVS supone que todas las versiones nuevas de un módulo son retrocompatibles y, por lo tanto, simplemente elige la versión más alta especificada por cualquier dependiente (D 1.1 en nuestro ejemplo). Se llama "mínima" porque, en este caso, D 1.1 es la versión mínima que podría satisfacer nuestros requisitos; incluso si D 1.2 o una versión posterior existe, no la seleccionamos. Esto tiene el beneficio adicional de que la selección de versión es de alta fidelidad y reproducible.
La resolución de la versión se realiza de forma local en tu máquina, no mediante el registro.
Nivel de compatibilidad
Ten en cuenta que la suposición de MVS sobre la retrocompatibilidad es factible porque simplemente trata las versiones incompatibles con versiones anteriores de un módulo como un módulo independiente. En términos de SemVer, eso significa que A 1.x y A 2.x se consideran módulos distintos y pueden coexistir en el gráfico de dependencias resuelto. Esto, a su vez, es posible gracias al hecho de que la versión principal está codificada en la ruta del paquete en Go, por lo que no hay conflictos de tiempo de compilación ni de vinculación.
En Bazel, no tenemos esas garantías. Por lo tanto, necesitamos una forma de indicar el número de "versión principal" para detectar versiones incompatibles con versiones anteriores. Este número se denomina nivel de compatibilidad y se especifica por cada versión del módulo en su directiva module(). Con esta información a mano, podemos arrojar un error cuando detectamos que existen versiones del mismo módulo con diferentes niveles de compatibilidad en el gráfico de dependencias resuelto.
Nombres de repositorios
En Bazel, cada dependencia externa tiene un nombre de repositorio. A veces, se puede usar la misma
dependencia a través de diferentes nombres de repositorio (por ejemplo,
@io_bazel_skylib y @bazel_skylib significan
Bazel skylib) o el mismo
nombre de repositorio se puede usar para dependencias diferentes en proyectos distintos.
En Bzlmod, los repositorios se pueden generar con módulos de Bazel y extensiones de módulos. Para resolver los conflictos de nombres de repositorios, adoptamos el mecanismo de asignación de repositorios en el sistema nuevo. Estos son dos conceptos importantes:
Nombre del repositorio canónico: El nombre del repositorio único a nivel global de cada repositorio. Este será el nombre del directorio en el que se encuentra el repositorio.
Se construye de la siguiente manera (Advertencia: El formato del nombre canónico no es una API de la que debas depender; está sujeto a cambios en cualquier momento):- Para repositorios de módulos de Bazel:
module_name~version
(ejemplo.@bazel_skylib~1.0.3) - Para repositorios de extensiones de módulos:
module_name~version~extension_name~repo_name
(ejemplo.@rules_cc~0.0.1~cc_configure~local_config_cc)
- Para repositorios de módulos de Bazel:
Nombre del repositorio aparente: Es el nombre del repositorio que se usará en los archivos
BUILDy.bzldentro de un repositorio. La misma dependencia podría tener diferentes nombres aparentes en distintos repositorios.
Se determina de la siguiente manera:
Cada repositorio tiene un diccionario de asignación de repositorios de sus dependencias directas, que es un mapa del nombre aparente del repositorio al nombre canónico del repositorio.
Usamos la asignación del repositorio para resolver el nombre del repositorio cuando construimos una etiqueta. Ten en cuenta que no hay conflictos de nombres de repositorios canónicos y los usos de nombres aparentes de repositorios se pueden descubrir mediante el análisis del archivo MODULE.bazel, por lo que los conflictos se pueden detectar y resolver fácilmente sin afectar otras dependencias.
Dependencias estrictas
El nuevo formato de especificación de dependencia nos permite realizar comprobaciones más estrictas. En particular, ahora aplicamos que un módulo solo puede usar repositorios creados a partir de sus dependencias directas. Esto ayuda a evitar fallas accidentales y difíciles de depurar cuando cambia algo en el gráfico de dependencias transitivas.
Las dependencias estrictas se implementan según la asignación de repositorio. En términos sencillos, la asignación de repositorios para cada repositorio contiene todas sus dependencias directas; cualquier otro repositorio no es visible. Las dependencias visibles para cada repositorio se determinan de la siguiente manera:
- Un repositorio de módulos de Bazel puede ver todos los repositorios presentados en el archivo
MODULE.bazela través debazel_depyuse_repo. - Un repositorio de extensión de módulo puede ver todas las dependencias visibles del módulo que proporciona la extensión, además de todos los demás repositorios generados por la misma extensión del módulo.
Registros
Para descubrir dependencias, Bzlmod solicita su información a los registros de Bazel. Un registro de Bazel es solo una base de datos de módulos de Bazel. La única forma de registro admitida es un registro de índices, que es un directorio local o un servidor HTTP estático que sigue un formato específico. En el futuro, planeamos agregar compatibilidad con los registros de un solo módulo, que son simplemente repositorios de Git que contienen la fuente y el historial de un proyecto.
Index Registry
Un registro de índices es un directorio local o un servidor HTTP estático que contiene información sobre una lista de módulos, incluida la página principal, los encargados de mantenimiento, el archivo MODULE.bazel de cada versión y la forma de recuperar la fuente de cada versión. En particular, no es necesario que entregue los archivos de origen.
Un registro de índices debe tener el siguiente formato:
/bazel_registry.json: Es un archivo JSON que contiene metadatos para el registro, como los siguientes:mirrors, que especifica la lista de duplicados que se usarán para los archivos de origenmodule_base_path, que especifica la ruta base para los módulos con el tipolocal_repositoryen el archivosource.json
/modules: Es un directorio que contiene un subdirectorio para cada módulo de este registro./modules/$MODULE: Es un directorio que contiene un subdirectorio para cada versión de este módulo, además del siguiente archivo:metadata.json: Es un archivo JSON que contiene información sobre el módulo, con los siguientes campos:homepage: Es la URL de la página principal del proyecto.maintainers: Es una lista de objetos JSON, cada uno de los cuales corresponde a la información de un encargado de mantenimiento del módulo en el registro. Ten en cuenta que esto no necesariamente es lo mismo que los autores del proyecto.versions: Es una lista de todas las versiones de este módulo que se encuentran en este registro.yanked_versions: Es una lista de las versiones proporcionadas de este módulo. Por el momento, esta no es una operación no-ops, pero en el futuro, las versiones anteriores se omitirán o generarán un error.
/modules/$MODULE/$VERSION: Un directorio que contiene los siguientes archivos:MODULE.bazel: Es el archivoMODULE.bazelde esta versión del módulo.source.json: Es un archivo JSON que contiene información sobre cómo recuperar la fuente de esta versión del módulo.- El tipo predeterminado es "archive" con los siguientes campos:
url: Es la URL del archivo de origen.integrity: La suma de verificación de integridad del subrecurso del archivo.strip_prefix: Es un prefijo de directorio que se debe quitar cuando se extrae el archivo de origen.patches: Una lista de strings, cada una de las cuales nombra un archivo de parche para aplicar al archivo extraído. Los archivos de parche se encuentran en el directorio/modules/$MODULE/$VERSION/patches.patch_strip: Igual que el argumento--stripdel parche Unix.
- Se puede cambiar el tipo para usar una ruta local con estos campos:
type:local_pathpath: Es la ruta local al repositorio, calculada de la siguiente manera:- Si la ruta de acceso es una absoluta, se usará tal como está.
- Si la ruta de acceso es relativa y
module_base_pathes absoluta, la ruta se resuelve como<module_base_path>/<path>. - Si la ruta de acceso y
module_base_pathson rutas relativas, la ruta se resuelve como<registry_path>/<module_base_path>/<path>. El registro se debe alojar de forma local y--registry=file://<registry_path>lo debe usar. De lo contrario, Bazel arrojará un error.
- El tipo predeterminado es "archive" con los siguientes campos:
patches/: Es un directorio opcional que contiene archivos de parches y que solo se usa cuandosource.jsontiene el tipo "archive".
Registro central de Bazel
El registro central de Bazel (BCR) es un registro de índices ubicado en bcr.bazel.build. Su contenido está respaldado por el repositorio de GitHub bazelbuild/bazel-central-registry.
La comunidad de Bazel mantiene el BCR. Se permite que los colaboradores envíen solicitudes de extracción. Consulta Políticas y procedimientos del registro de la central de Bazel.
Además de seguir el formato de un registro de índices normal, el BCR requiere un archivo presubmit.yml para cada versión del módulo (/modules/$MODULE/$VERSION/presubmit.yml). Este archivo especifica algunos objetivos esenciales de compilación y prueba que se pueden usar para verificar la validez de esta versión del módulo. Las canalizaciones de CI de BCR usan este archivo para garantizar la interoperabilidad entre módulos en BCR.
Selecciona registros
Se puede usar la marca repetible --registry de Bazel a fin de especificar la lista de
registros para solicitar módulos a fin de que puedas configurar tu proyecto para recuperar
dependencias de un registro interno o de terceros. Los registros anteriores tienen
prioridad. Para mayor comodidad, puedes colocar una lista de marcas --registry en el archivo .bazelrc de tu proyecto.
Extensiones del módulo
Las extensiones de módulo te permiten extender el sistema de módulos leyendo datos de entrada de módulos en el gráfico de dependencias, realizar la lógica necesaria para resolver dependencias y, por último, crear repositorios con llamadas a reglas de repositorios. Tienen funciones similares a las macros de WORKSPACE actuales, pero son más adecuadas en el mundo de los módulos y las dependencias transitivas.
Las extensiones de módulo se definen en archivos .bzl, al igual que las reglas del repositorio o las macros WORKSPACE. No se invocan directamente, sino que cada módulo puede especificar datos llamados etiquetas para que las extensiones lean. Luego, una vez finalizada la resolución de la versión del módulo, se ejecutan las extensiones del módulo. Cada extensión se ejecuta una vez después de la resolución del módulo (antes de que ocurra cualquier compilación) y lee todas las etiquetas que le pertenecen en todo el gráfico de dependencias.
[ A 1.1 ]
[ * maven.dep(X 2.1) ]
[ * maven.pom(...) ]
/ \
bazel_dep / \ bazel_dep
/ \
[ B 1.2 ] [ C 1.0 ]
[ * maven.dep(X 1.2) ] [ * maven.dep(X 2.1) ]
[ * maven.dep(Y 1.3) ] [ * cargo.dep(P 1.1) ]
\ /
bazel_dep \ / bazel_dep
\ /
[ D 1.4 ]
[ * maven.dep(Z 1.4) ]
[ * cargo.dep(Q 1.1) ]
En el gráfico de dependencias de ejemplo anterior, A 1.1, B 1.2, etc., son módulos de Bazel. Puedes pensar en cada uno como un archivo MODULE.bazel. Cada módulo puede especificar algunas
etiquetas para las extensiones de módulo. En este caso, algunas se especifican para la extensión "maven"
y otras para "cargo". Cuando se finaliza este gráfico de dependencia (por ejemplo, quizás B 1.2 tiene un bazel_dep en D 1.3, pero se actualizó a D 1.4 debido a C), se ejecuta la extensión "maven", y puede leer todas las etiquetas maven.* con la información correspondiente para decidir qué repositorios crear.
Lo mismo ocurre con la extensión "cargo".
Uso de extensiones
Las extensiones se alojan en módulos de Bazel, por lo que, para usar una extensión en
tu módulo, primero debes agregar un bazel_dep en ese módulo y, luego, llamar a
la función integrada use_extension
para incluirla en el alcance. Considera el siguiente ejemplo, un fragmento de un archivo MODULE.bazel para usar una extensión “maven” hipotética definida en el módulo rules_jvm_external:
bazel_dep(name = "rules_jvm_external", version = "1.0")
maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")
Después de incluir la extensión en el alcance, puedes usar la sintaxis de punto para
especificar etiquetas para ella. Ten en cuenta que las etiquetas deben seguir el esquema definido por las clases de etiqueta correspondientes (consulta la definición de la extensión a continuación). A continuación, se muestra un ejemplo en el que se especifican algunas etiquetas maven.dep y maven.pom.
maven.dep(coord="org.junit:junit:3.0")
maven.dep(coord="com.google.guava:guava:1.2")
maven.pom(pom_xml="//:pom.xml")
Si la extensión genera repositorios que deseas usar en tu módulo, usa la directiva use_repo para declararlos. El propósito de esto es cumplir con la condición de dependencias estricta y evitar conflictos de nombres de repositorios locales.
use_repo(
maven,
"org_junit_junit",
guava="com_google_guava_guava",
)
Los repositorios que genera una extensión son parte de su API, por lo que, a partir de las etiquetas que
especificaste, debes saber que la extensión “maven” generará un
repositorio llamado “org_junit_junit”, y otro llamado “com_google_guava_guava”. Con use_repo, tienes la opción de cambiarles el nombre en el alcance de tu módulo, por ejemplo, a "guava" aquí.
Definición de la extensión
Las extensiones de módulo se definen de manera similar a las reglas de repositorio con la función module_extension.
Ambas tienen una función de implementación; pero, si bien las reglas de repositorio tienen varios atributos, las extensiones de módulo tienen varios tag_class, cada uno de los cuales tiene varios atributos. Las clases de etiqueta definen esquemas para las etiquetas que usa esta extensión. Continuando con el ejemplo de la extensión hipotética “maven” anterior:
# @rules_jvm_external//:extensions.bzl
maven_dep = tag_class(attrs = {"coord": attr.string()})
maven_pom = tag_class(attrs = {"pom_xml": attr.label()})
maven = module_extension(
implementation=_maven_impl,
tag_classes={"dep": maven_dep, "pom": maven_pom},
)
Estas declaraciones aclaran que las etiquetas maven.dep y maven.pom se pueden especificar mediante el esquema de atributos definido previamente.
La función de implementación es similar a una macro WORKSPACE, con la excepción de que obtiene un objeto module_ctx, que otorga acceso al gráfico de dependencias y a todas las etiquetas pertinentes. Luego, la función de
implementación debe llamar a las reglas del repositorio para generarlos:
# @rules_jvm_external//:extensions.bzl
load("//:repo_rules.bzl", "maven_single_jar")
def _maven_impl(ctx):
coords = []
for mod in ctx.modules:
coords += [dep.coord for dep in mod.tags.dep]
output = ctx.execute(["coursier", "resolve", coords]) # hypothetical call
repo_attrs = process_coursier(output)
[maven_single_jar(**attrs) for attrs in repo_attrs]
En el ejemplo anterior, repasamos todos los módulos del gráfico de dependencias (ctx.modules), cada uno de los cuales es un objeto bazel_module cuyo campo tags expone todas las etiquetas maven.* del módulo. Luego, invocamos la utilidad Coursier de la CLI
para contactar a Maven y realizar la resolución. Por último, usamos el resultado de la resolución para crear varios repositorios mediante la regla hipotética maven_single_jar del repositorio.