Registros de Bazel

Bzlmod descubre las dependencias solicitando su información de los registros de Bazel, que son bases de datos de módulos de Bazel. Actualmente, Bzlmod solo admite registros de índice — directorios locales o servidores HTTP estáticos que siguen un formato específico.

Registro de índice

Un registro de índice es un directorio local o un servidor HTTP estático que contiene información sobre una lista de módulos, incluidas su página principal, sus mantenedores, el archivo MODULE.bazel de cada versión y cómo obtener la fuente de cada versión. En particular, no es necesario que entregue 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: Especifica la lista de espejos que se usarán para los archivos de origen. La URL duplicada es una concatenación del espejo en sí y la URL de origen del módulo especificado por su archivo source.json sin el protocolo. Por ejemplo, si la URL de origen de un módulo es https://foo.com/bar/baz, y mirrors contiene ["https://mirror1.com/", "https://example.com/mirror2/"], las URLs que Bazel intentará en orden son https://mirror1.com/foo.com/bar/baz, https://example.com/mirror2/foo.com/bar/baz, y, por último, la URL de origen original https://foo.com/bar/baz.
    • module_base_path: Especifica la ruta base para los módulos con el tipo local_repository en el archivo source.json.
  • /modules: Un directorio que contiene un subdirectorio para cada módulo de este registro.
  • /modules/$MODULE: Un directorio que contiene un subdirectorio para cada versión de este módulo, así como lo siguiente:
    • metadata.json: Un archivo JSON que contiene información sobre el módulo, con los siguientes campos:
      • homepage: La URL de la página principal del proyecto.
      • maintainers: 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 siempre es lo mismo que los autores del proyecto.
      • versions: Una lista de todas las versiones de este módulo que se encuentran en este registro.
      • yanked_versions: Un mapa de las versiones retiradas de este módulo. Las claves deben ser las versiones que se retirarán y los valores deben ser descripciones de por qué se retira la versión, idealmente con un vínculo a más información.
  • /modules/$MODULE/$VERSION: Un directorio que contiene los siguientes archivos:
    • MODULE.bazel: El archivo MODULE.bazel de esta versión del módulo.
    • source.json: Un archivo JSON que contiene información sobre cómo obtener la fuente de esta versión del módulo.
      • El tipo predeterminado es "archive", que representa un repositorio http_archive, con los siguientes campos:
        • url: La URL del archivo de origen.
        • integrity: La suma de verificación de integridad de subrecursos del archivo.
        • strip_prefix: Un prefijo de directorio que se quitará cuando se extraiga el archivo de origen.
        • patches: Un mapa que contiene archivos de parche para aplicar al archivo extraído. Los archivos de parche se encuentran en el directorio /modules/$MODULE/$VERSION/patches. Las claves son los nombres de los archivos de parche y los valores son la suma de verificación de integridad de los archivos de parche.
        • patch_strip: Es lo mismo que el argumento --strip de patch de Unix.
        • archive_type: El tipo de archivo del archivo descargado (lo mismo que type en http_archive). De forma predeterminada, el tipo de archivo se determina a partir de la extensión de archivo de la URL. Si el archivo no tiene extensión, puedes especificar explícitamente una de las siguientes: "zip", "jar", "war", "aar", "tar", "tar.gz", "tgz", "tar.xz", "txz", "tar.zst", "tzst", tar.bz2, "ar" o "deb".
      • El tipo se puede cambiar para usar un repositorio de Git, con estos campos:
        • type: git_repository
        • Los siguientes campos, como se describe en https://bazel.build/rules/lib/repo/git:
          • remote
          • commit
          • shallow_since
          • tag
          • init_submodules
          • verbose
          • strip_prefix
      • El tipo se puede cambiar para usar una ruta de acceso local, que representa un repositorio local_repository, con estos campos:
        • type: local_path
        • path: La ruta de acceso local al repositorio, que se calcula de la siguiente manera:
          • Si path es una ruta de acceso absoluta, permanece como está.
          • Si path es una ruta de acceso relativa y module_base_path es una ruta de acceso absoluta, se resuelve en <module_base_path>/<path>.
          • Si path y module_base_path son rutas de acceso relativas, se resuelve en <registry_path>/<module_base_path>/<path>. El registro debe alojarse de forma local y usarse con --registry=file://<registry_path>. De lo contrario, Bazel mostrará un error.
    • patches/: Un directorio opcional que contiene archivos de parche, que solo se usa cuando source.json tiene el tipo "archive".

metadata.json

metadata.json es un archivo JSON opcional que contiene información sobre el módulo, con los siguientes campos:

  • versions: Un array de cadenas, cada una de las cuales indica una versión del módulo disponible en este registro. Este array debe coincidir con los elementos secundarios del directorio del módulo.
  • yanked_versions: Un objeto JSON que especifica las versiones retiradas de este módulo. Las claves deben ser las versiones que se retirarán y los valores deben ser descripciones de por qué se retira la versión, idealmente con un vínculo a más información.

Ten en cuenta que el BCR requiere más información en el archivo metadata.json.

source.json

source.json es un archivo JSON obligatorio que contiene información sobre cómo obtener una versión específica de un módulo. El esquema de este archivo depende de su campo type, que tiene el valor predeterminado archive.

  • Si type es archive (el valor predeterminado), esta versión del módulo está respaldada por una regla de repositorio http_archive. Se obtiene descargando un archivo de una URL determinada y extrayendo su contenido. Admite los siguientes campos:
    • url: Una cadena, la URL del archivo de origen.
    • mirror_urls: Una lista de cadenas, las URLs duplicadas del archivo de origen. Las URLs se prueban en orden después de url como copias de seguridad.
    • integrity: Una cadena, la suma de verificación de [integridad de subrecursos][subresource-integrity] del archivo.
    • strip_prefix: Una cadena, el prefijo de directorio que se quitará cuando se extraiga el archivo de origen.
    • overlay: Un objeto JSON que contiene archivos de superposición para colocar sobre el archivo extraído. Los archivos de parche se encuentran en el directorio /modules/$MODULE/$VERSION/overlay. Las claves son los nombres de los archivos de superposición y los valores son la suma de verificación de integridad de los archivos de superposición. Las superposiciones se aplican antes que los archivos de parche.
    • patches: Un objeto JSON que contiene archivos de parche para aplicar al archivo extraído. Los archivos de parche se encuentran en el directorio /modules/$MODULE/$VERSION/patches. Las claves son los nombres de los archivos de parche y los valores son la suma de verificación de integridad de los archivos de parche. Los parches se aplican después de los archivos de superposición.
    • patch_strip: Un número, lo mismo que el argumento --strip de Unix patch.
    • archive_type: Una cadena, el tipo de archivo del archivo descargado (lo mismo que type en http_archive).
  • Si type es git_repository, esta versión del módulo está respaldada por una git_repository regla de repositorio. Se obtiene clonando un repositorio de Git.
    • Se admiten los siguientes campos y se reenvían directamente a la regla de repositorio git_repository subyacente: remote, commit, shallow_since, tag, init_submodules, verbose y strip_prefix.
  • Si type es local_path, esta versión del módulo está respaldada por una local_repository regla de repositorio; se vincula simbólicamente a un directorio en el disco local. Admite el siguiente campo:
    • path: La ruta de acceso local al repositorio, que se calcula de la siguiente manera:
      • Si path es una ruta de acceso absoluta, permanece como está.
      • Si path es una ruta de acceso relativa y module_base_path es una ruta de acceso absoluta, se resuelve en <module_base_path>/<path>.
      • Si path y module_base_path son rutas de acceso relativas, se resuelve en <registry_path>/<module_base_path>/<path>. El registro debe alojarse de forma local y usarse con --registry=file://<registry_path>. De lo contrario, Bazel mostrará un error.

Registro central de Bazel

El Registro central de Bazel (BCR) en https://bcr.bazel.build/ es un registro de índice con contenido respaldado por el repositorio de GitHub bazelbuild/bazel-central-registry. Puedes explorar su contenido con el frontend web en https://registry.bazel.build/.

La comunidad de Bazel mantiene el BCR, y los colaboradores pueden enviar solicitudes de extracción. Consulta los lineamientos de contribución del BCR.

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 objetivos esenciales de compilación y prueba que puedes usar para verificar la validez de esta versión del módulo. Las cadenas de procesamiento de CI del BCR también lo usan para garantizar la interoperabilidad entre los módulos.

Selecciona registros

La marca repetible de Bazel --registry se puede usar para especificar la lista de registros de los que se solicitarán módulos, de modo que puedas configurar tu proyecto para obtener 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.

Si tu registro está alojado en GitHub (por ejemplo, como una bifurcación de bazelbuild/bazel-central-registry), tu valor --registry necesita una dirección de GitHub sin procesar en raw.githubusercontent.com. Por ejemplo, en la main rama de la my-org bifurcación, establecerías --registry=https://raw.githubusercontent.com/my-org/bazel-central-registry/main/.

Si usas la marca --registry, se detiene el uso del Registro central de Bazel de forma predeterminada, pero puedes volver a agregarlo con --registry=https://bcr.bazel.build.