Bzlmod es el nombre en clave del nuevo sistema de dependencias externas que se introdujo en Bazel 5.0. Se introdujo para abordar varios problemas del sistema anterior que no se podían solucionar de forma incremental. Consulta la sección Planteamiento del problema del documento de diseño original para obtener más detalles.
En Bazel 5.0, Bzlmod no se activa de forma predeterminada. Se debe especificar la marca --experimental_enable_bzlmod para que se aplique 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.
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 externas basado en WORKSPACE se centra en los
repositorios (o repos), creados 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 principales de dependencia.
Un módulo es, en esencia, 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 similar a los conceptos conocidos en otros sistemas de administración de dependencias: un artefacto de Maven, un paquete de npm, un clúster 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 repositorio.
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 lugar de trabajo (junto al archivo WORKSPACE). A diferencia del archivo WORKSPACE, no necesitas especificar 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 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 sentencias 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:
- 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. El más popular, con mucho, es SemVer, pero también hay proyectos destacados que usan diferentes esquemas, como Abseil, cuyas versiones se basan en fechas (por ejemplo, 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 prescribe que la parte "release" de la versión debe constar de 3 segmentos:
MAJOR.MINOR.PATCH. En Bazel, este requisito se flexibiliza para permitir cualquier cantidad de segmentos. - En SemVer, cada uno de los segmentos de la parte "release" debe ser solo dígitos. En Bazel, esto se relaja para permitir letras, y la semántica de comparación coincide con los “identificadores” en la parte “prelanzamiento”.
- Además, no se aplican las semánticas de los aumentos de versiones principales, secundarias y de parches. (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 si y solo si lo mismo ocurre cuando se comparan como versiones de módulos de Bazel.
Resolución de la versión
El problema de 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 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 que especifique 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 posterior, no la seleccionamos. Esto tiene el beneficio adicional de que la selección de versiones es de alta fidelidad y reproducible.
La resolución de versiones se realiza de forma local en tu máquina, no por el registro.
Nivel de compatibilidad
Ten en cuenta que la suposición de MVS sobre la retrocompatibilidad es factible porque solo trata las versiones de un módulo que no son retrocompatibles 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 porque la versión principal está codificada en la ruta de acceso 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 cada versión del módulo en su directiva module(). Con esta información en 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 con diferentes nombres de repositorio (por ejemplo, ambos
@io_bazel_skylib y @bazel_skylib significan
Bazel skylib), o se puede usar el mismo
nombre de repositorio 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 repositorio, estamos adoptando el mecanismo de asignación de repositorios en el nuevo sistema. Estos son dos conceptos importantes:
Nombre canónico del repositorio: Es el nombre ú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 de 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 aparente del repositorio: 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 diferentes 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 del repositorio aparente al nombre del repositorio canónico.
Usamos la asignación de repositorios para resolver el nombre del repositorio cuando se crea una etiqueta. Ten en cuenta que no hay conflictos de nombres de repositorio canónicos, y los usos de los nombres de repositorio aparentes se pueden descubrir analizando el archivo MODULE.bazel. Por lo tanto, los conflictos se pueden detectar y resolver fácilmente sin afectar a otras dependencias.
Dependencias estrictas
El nuevo formato de especificación de dependencias nos permite realizar verificaciones más estrictas. En particular, ahora aplicamos la regla de 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 en función de la asignación de repositorios. Básicamente, la asignación de repositorios para cada repo contiene todas sus dependencias directas, y no se puede ver ningún otro repositorio. Las dependencias visibles de cada repositorio se determinan de la siguiente manera:
- Un repositorio de módulos de Bazel puede ver todos los repositorios 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 registro compatible 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 registros de un solo módulo, que son simplemente repositorios de git que contienen la 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, los responsables de mantenimiento, el archivo MODULE.bazel de cada versión y cómo recuperar la fuente de cada versión. En particular, no es necesario que publique los archivos de origen.
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 espejos que se usarán para los archivos de origen.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 en 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: 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 del módulo en el registro. Ten en cuenta que no es necesariamente 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 eliminadas de este módulo. Por el momento, esto no realiza ninguna acción, pero, en el futuro, se omitirán las versiones quitadas 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 para 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 comprobació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 asigna un nombre a un archivo de parche para aplicarlo al archivo extraído. Los archivos de parches 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 repositorio, que se calcula de la siguiente manera:- Si la ruta de acceso es absoluta, se usará tal como está.
- Si la ruta es relativa y
module_base_pathes una ruta absoluta, la ruta se resuelve en<module_base_path>/<path>. - Si path y
module_base_pathson rutas relativas, path se resuelve en<registry_path>/<module_base_path>/<path>. El registro debe alojarse de forma local y--registry=file://<registry_path>debe usarlo. 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 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. Los colaboradores pueden enviar solicitudes de extracción. Consulta las Políticas y los 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 que usan las canalizaciones de CI del BCR para garantizar la interoperabilidad entre los módulos del BCR.
Selecciona registros
La marca --registry de Bazel repetible se puede usar para especificar la lista de
registros desde los que se solicitarán módulos, de modo que puedas configurar tu proyecto para recuperar
dependencias de un registro interno o de terceros. Los registros anteriores tienen prioridad. Para tu comodidad, puedes colocar 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 los módulos en el gráfico de dependencias, realizando la lógica necesaria para resolver las dependencias y, por último, creando repositorios llamando a reglas de repositorio. 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ódulo 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 datos llamados etiquetas para que las extensiones los lean. Luego, después de que se complete la resolución de la versión del módulo, se ejecutarán las extensiones del módulo. Cada extensión se ejecuta una vez después de la resolución del módulo (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, B 1.2, etc. son módulos de Bazel.
Puedes considerar cada uno como un archivo MODULE.bazel. Cada módulo puede especificar algunas etiquetas para extensiones de módulo. Aquí, algunas se especifican para la extensión "maven" y otras para "cargo". Cuando se finaliza este gráfico de dependencias (por ejemplo, tal vez B 1.2 tenga un bazel_dep en D 1.3, pero se actualizó a D 1.4 debido a C), se ejecutan las extensiones "maven" y se leen todas las etiquetas maven.*, y se usa la información que contiene para decidir qué repositorios crear.
Del mismo modo, ocurre con la extensión "cargo".
Uso de extensiones
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é dentro del alcance. Considera el siguiente ejemplo, un fragmento de un archivo MODULE.bazel para usar una extensión hipotética de "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 la 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 deseas usar en tu módulo, usa la directiva use_repo para declararlos. Esto es para satisfacer la condición de dependencias estrictas 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 forman 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, 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ódulo se definen de manera similar a las reglas de repo con la función module_extension.
Ambos tienen una función de implementación. Sin embargo, mientras que las reglas del repositorio tienen una serie de atributos, las extensiones de módulos tienen una serie de tag_class, cada una de las cuales tiene una serie de 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 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 debería llamar a las reglas de repositorio para generar repositorios:
# @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 una serie de repositorios con la regla hipotética del repositorio maven_single_jar.