Bzlmod es el nombre interno del nuevo sistema de dependencias externas que se introdujo en Bazel 5.0. Se introdujo para abordar varios puntos débiles del sistema anterior que no se podían corregir de forma incremental; consulta la sección de la 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 surta efecto lo siguiente. Como sugiere el nombre de la marca, esta función es experimental por el momento. Las APIs y los comportamientos pueden cambiar hasta que se lance oficialmente la función.
Para migrar tu proyecto a Bzlmod, sigue la Guía de migración de Bzlmod. También puedes encontrar ejemplos de uso de Bzlmod en el repositorio de ejemplos.
Módulos de Bazel
El antiguo sistema de dependencias externas basado en WORKSPACE se centra en los repositorios (o repos), que se crean a través de reglas de repositorio (o reglas de repo).
Si bien los repositorios siguen siendo un concepto importante en el nuevo sistema, los módulos son las unidades centrales de dependencia.
Un módulo es, básicamente, 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 crate de Cargo, un módulo de Go, etcétera.
Un módulo simplemente especifica sus dependencias con pares name y version, en lugar de URLs específicas en WORKSPACE. Luego, las dependencias se buscan en un registro de Bazel; de forma predeterminada, el registro central de Bazel. En tu espacio de trabajo, cada módulo se convierte en un repo.
MODULE.bazel
Cada versión de cada módulo tiene un archivo MODULE.bazel que declara sus dependencias y otros metadatos. Este es 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 espacio de trabajo (junto al archivo WORKSPACE). A diferencia del archivo WORKSPACE, no es necesario que especifiques tus dependencias transitivas. En su lugar, solo debes especificar las dependencias directas, y los archivos MODULE.bazel de tus dependencias se procesan para descubrir las dependencias transitivas de forma automática.
El archivo MODULE.bazel es similar a los archivos BUILD, ya que no admite ninguna forma de flujo de control y, además, prohíbe las instrucciones load. Las directivas que admiten los archivos MODULE.bazel son las siguientes:
module, para especificar metadatos sobre el módulo actual, incluidos su nombre, versión, etcéterabazel_dep, para especificar dependencias directas en otros módulos de Bazel- Invalidaciones, 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 determinada dependencia directa o transitiva:
- Directivas relacionadas con las extensiones de módulo:
Formato de versión
Bazel tiene un ecosistema diverso, y los proyectos usan varios esquemas de versiones. La más popular es SemVer, pero también hay proyectos destacados que usan otros esquemas, como Abseil, cuyas versiones se basan en la fecha (por ejemplo, 20210324.2).
Por este motivo, Bzlmod adopta una versión más flexible de la especificación de SemVer. Las diferencias incluyen lo siguiente:
- SemVer indica que la parte de "versión" debe constar de 3 segmentos:
MAJOR.MINOR.PATCH. En Bazel, este requisito se relaja para permitir cualquier cantidad de segmentos. - En SemVer, cada uno de los segmentos de la parte de "versión" debe contener solo dígitos. En Bazel, esto se relaja para permitir también letras, y la semántica de comparación coincide con los "identificadores" en la parte de "versión preliminar".
- Además, no se aplican las semánticas de los aumentos de versiones principales, secundarias y de parches. (Sin embargo, consulta nivel de compatibilidad para obtener detalles sobre cómo denotamos la retrocompatibilidad).
Cualquier versión de SemVer válida es una versión de módulo de Bazel válida. Además, dos versiones de SemVer a y b se comparan a < b si se cumple la misma condición cuando se comparan como versiones de módulos de Bazel.
Resolución de versiones
El problema de dependencia de diamante es un elemento básico en el espacio de administración de dependencias versionadas. 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 se debe usar? Para resolver esta pregunta, Bzlmod usa el algoritmo de selección de versión mínima (MVS) que se introdujo en el sistema de módulos de Go. El 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 elemento dependiente (D 1.1 en nuestro ejemplo). Se llama "mínima" porque D 1.1 es la versión mínima que podría satisfacer nuestros requisitos; incluso si existe D 1.2 o una versión más reciente, no las seleccionamos. Esto tiene el beneficio adicional de que la selección de versión es de alta fidelidad y reproducible.
La resolución de versiones se realiza de forma local en tu máquina, no en el registro.
Nivel de compatibilidad
Ten en cuenta que la suposición de MVS sobre la retrocompatibilidad es factible porque simplemente trata las versiones de un módulo que no son retrocompatibles como un módulo independiente. En términos de SemVer, esto significa que A 1.x y A 2.x se consideran módulos distintos y pueden coexistir en el grafo de dependencias resuelto. A su vez, esto es posible gracias a que la versión principal está codificada en la ruta del paquete en Go, por lo que no hay conflictos en el tiempo de compilación ni en el tiempo 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 en la directiva module() de cada versión del módulo. Con esta información, 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, la misma dependencia se puede usar a través de diferentes nombres de repositorios (por ejemplo, tanto @io_bazel_skylib como @bazel_skylib significan Bazel skylib), o el mismo nombre de repositorio se puede usar para diferentes dependencias en diferentes proyectos.
En Bzlmod, los módulos de Bazel y las extensiones de módulos pueden generar repositorios. Para resolver los conflictos de nombres de repositorios, adoptaremos el mecanismo de asignación de repositorios en el nuevo sistema. Estos son dos conceptos importantes:
Nombre canónico del repositorio: Es el nombre del repositorio único a nivel global para 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, ya que está sujeto a cambios en cualquier momento):- Para repositorios de módulos de Bazel:
module_name~version
(Ejemplo.@bazel_skylib~1.0.3) - Para los 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 de repositorio aparente: Es el nombre del repositorio que se usará en los archivos
BUILDy.bzldentro de un repositorio. La misma dependencia podría tener nombres aparentes diferentes en distintos repositorios.
Se determina de la siguiente manera:
Cada repositorio tiene un diccionario de asignación de repositorio de sus dependencias directas, que es un mapa del nombre de repositorio aparente al nombre de repositorio canónico.
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 de repositorios aparentes se pueden descubrir analizando el 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 dependencias nos permite realizar verificaciones 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 interrupciones accidentales y difíciles de depurar cuando cambia algo en el gráfico de dependencias transitivas.
Las dependencias estrictas se implementan en función de la asignación de repositorios. Básicamente, la asignación del repositorio para cada repo contiene todas sus dependencias directas, y no se ve ningún otro repositorio. Las dependencias visibles para cada repositorio se determinan de la siguiente manera:
- Un repo de módulos de Bazel puede ver todos los repos introducidos 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 de módulo.
Registros
Bzlmod descubre las dependencias solicitando su información a los registros de Bazel. Un registro de Bazel es simplemente una base de datos de módulos de Bazel. La única forma de registros admitida es un registro de índice, 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 el código fuente y el historial de un proyecto.
Registro de índices
Un registro de índice es un directorio local o un servidor HTTP estático que contiene información sobre una lista de módulos, incluida su página principal, sus mantenedores, el archivo MODULE.bazel de cada versión y cómo recuperar el código fuente de cada versión. En particular, no necesita publicar los archivos fuente por sí mismo.
Un registro de índice debe seguir el siguiente formato:
/bazel_registry.json: 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 fuente.module_base_path, que especifica la ruta de acceso 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, así como el siguiente archivo:metadata.json: Es un archivo JSON que contiene información sobre el módulo, con los siguientes campos:homepage: URL de la página principal del proyectomaintainers: Es una lista de objetos JSON, cada uno de los cuales corresponde a la información de un mantenedor del módulo en el registro. Ten en cuenta que no necesariamente son los mismos 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 versiones retiradas de este módulo. Actualmente, esta acción no tiene efecto, pero, en el futuro, se omitirán las versiones retiradas o se generará un error.
/modules/$MODULE/$VERSION: Es 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: URL del archivo fuente.integrity: Es la suma de verificación de Integridad de subrecursos del archivo.strip_prefix: Es un prefijo de directorio que se quita cuando se extrae el archivo fuente.patches: Es una lista de cadenas, cada una de las cuales nombra un archivo de parche que se aplicará al archivo extraído. Los archivos de parche se encuentran en el directorio/modules/$MODULE/$VERSION/patches.patch_strip: Es igual que el argumento--stripdel parche de Unix.
- El tipo se puede cambiar para usar una ruta de acceso local con estos campos:
type:local_pathpath: Es la ruta de acceso local al repo, que se calcula de la siguiente manera:- Si la ruta de acceso es absoluta, se usará tal cual.
- Si la ruta es relativa y
module_base_pathes una ruta absoluta, la ruta se resuelve en<module_base_path>/<path>. - Si la ruta de acceso y
module_base_pathson rutas de acceso relativas, la ruta de acceso se resuelve en<registry_path>/<module_base_path>/<path>. El registro debe alojarse de forma local y debe usarlo--registry=file://<registry_path>. 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 parche, 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 se basa en el repositorio de GitHub bazelbuild/bazel-central-registry.
La comunidad de Bazel mantiene el BCR, y los colaboradores pueden enviar solicitudes de extracción. Consulta las Políticas y procedimientos del Registro Central de Bazel.
Además de seguir el formato de un registro de índice normal, el BCR requiere un archivo presubmit.yml para cada versión del módulo (/modules/$MODULE/$VERSION/presubmit.yml). Este archivo especifica algunos destinos de compilación y prueba esenciales que se pueden usar para verificar la validez de esta versión del módulo, y las canalizaciones de CI del BCR lo usan para garantizar la interoperabilidad entre los módulos del BCR.
Selecciona registros
La marca repetible de Bazel --registry se puede usar para especificar la lista de registros desde los que se solicitan módulos, por lo que puedes configurar tu proyecto para recuperar dependencias de un registro interno o de terceros. Los registros anteriores tienen prioridad. Para mayor comodidad, puedes incluir una lista de marcas --registry en el archivo .bazelrc de tu proyecto.
Extensiones de módulos
Las extensiones de módulos te permiten extender el sistema de módulos leyendo datos de entrada de módulos en todo el gráfico de dependencias, realizando la lógica necesaria para resolver las dependencias y, finalmente, creando repositorios llamando a reglas de repositorios. Son similares en función a las macros WORKSPACE actuales, pero son más adecuadas en el mundo de los módulos y las dependencias transitivas.
Las extensiones de módulos se definen en archivos .bzl, al igual que las reglas de repo o las macros WORKSPACE. No se invocan directamente, sino que cada módulo puede especificar fragmentos de datos llamados etiquetas para que las extensiones los lean. Luego, después de que se resuelve 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 (aún antes de que se realice cualquier compilación) y puede leer 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 y B 1.2, etcétera, son módulos de Bazel. Puedes considerar que cada uno es un archivo MODULE.bazel. Cada módulo puede especificar algunas etiquetas para las extensiones de módulos. Aquí se especifican algunas para la extensión "maven" y otras para "cargo". Cuando se finaliza este gráfico de dependencias (por ejemplo, tal vez B 1.2 realmente tiene una 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.*, y usa la información que contienen para decidir qué repositorios crear.
Lo mismo sucede con la extensión "cargo".
Uso de la extensión
Las extensiones se alojan en los propios 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 que esté disponible. Considera el siguiente ejemplo, un fragmento de un archivo MODULE.bazel para usar una hipotética extensión "maven" 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 etiquetas correspondientes (consulta la definición de extensión a continuación). Este es 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 quieres usar en tu módulo, usa la directiva use_repo para declararlos. Esto es para satisfacer la condición de deps estrictas y evitar conflictos locales con el nombre del repo.
use_repo(
maven,
"org_junit_junit",
guava="com_google_guava_guava",
)
Los repositorios que genera una extensión forman parte de su API, por lo que, a partir de las etiquetas que especificaste, deberías saber que la extensión "maven" generará un repositorio llamado "org_junit_junit" y otro llamado "com_google_guava_guava". Con use_repo, puedes cambiarles el nombre de forma opcional en el alcance de tu módulo, como a "guava" aquí.
Definición de la extensión
Las extensiones de módulos se definen de manera similar a las reglas de repositorios, con la función module_extension.
Ambas tienen una función de implementación, pero mientras que las reglas del repositorio tienen varios atributos, las extensiones de módulos tienen varios tag_classes, cada uno de los cuales tiene varios atributos. Las clases de etiquetas 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 dejan en claro que se pueden especificar las etiquetas maven.dep y maven.pom con el esquema de atributos definido anteriormente.
La función de implementación es similar a una macro de WORKSPACE, excepto 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 repo para generar repos:
# @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, revisamos 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 de CLI Coursier para comunicarnos con Maven y realizar la resolución. Por último, usamos el resultado de la resolución para crear varios repositorios con la regla hipotética maven_single_jar.