Registros de Bazel

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

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 tener el siguiente formato:

• /bazel_registry.json: Es un archivo JSON opcional que contiene metadatos para el registro.
• /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 del módulo llamado $MODULE, así como el archivometadata.json que contiene los metadatos de este módulo.
• /modules/$MODULE/$VERSION: Es un directorio que contiene los siguientes archivos:
  • MODULE.bazel: Es el archivo MODULE.bazel de esta versión del módulo. Ten en cuenta que este es el archivo MODULE.bazel que se lee durante la resolución de dependencias externas de Bazel, no el del archivo fuente (a menos que haya una anulación no de registro). También ten en cuenta que es mejor usar este archivo para establecer la versión de un lanzamiento y evitar hacerlo en el archivo MODULE.bazel del archivo fuente. Para obtener más información sobre el control de versiones de módulos, consulta las preguntas frecuentes.
  • source.json: Un archivo JSON que contiene información sobre cómo recuperar el código fuente de esta versión del módulo
  • patches/: Es un directorio opcional que contiene archivos de parche, que solo se usa cuando source.json tiene el tipo "archive".
  • overlay/: Es un directorio opcional que contiene archivos de superposición y solo se usa cuando source.json tiene el tipo "archive".

bazel_registry.json

bazel_registry.json es un archivo opcional que especifica los metadatos que se aplican a todo el registro. Puede contener los siguientes campos:

• mirrors: Es un array de cadenas que especifica la lista de duplicados que se usarán para los archivos fuente.
  • La URL duplicada es una concatenación del duplicado en sí y la URL de origen del módulo especificada 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: Es una cadena que especifica la ruta de acceso base para los módulos con el tipo local_path en el archivo source.json.

metadata.json

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

• versions: Es un array de cadenas, en el que cada una denota 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: Es un objeto JSON que especifica las versiones retiradas de este módulo. Las claves deben ser las versiones que se quitarán, y los valores deben ser descripciones de por qué se quita la versión, idealmente con un vínculo a más información.

Ten en cuenta que la 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 recuperar 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 se basa en una regla de repo http_archive; se recupera descargando un archivo de una URL determinada y extrayendo su contenido. Admite los siguientes campos:
  • url: Es una cadena, la URL del archivo fuente.
  • mirror_urls: Es una lista de cadenas, las URLs duplicadas del archivo fuente. Las URLs se prueban en orden después de url como copias de seguridad.
  • integrity: Es una cadena, la suma de verificación de Integridad de subrecursos del archivo.
  • strip_prefix: Es una cadena, el prefijo del directorio que se debe quitar cuando se extrae el archivo fuente.
  • overlay: Es 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: Es un objeto JSON que contiene archivos de parches 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 y en el orden en que aparecen en patches.
  • patch_strip: Es un número, igual que el argumento --strip de Unix patch.
  • archive_type: Es una cadena que indica el tipo de archivo del archivo descargado (igual que type en http_archive).
• Si type es git_repository, esta versión del módulo se basa en una regla de repo git_repository, y se recupera clonando un repositorio de Git.
  • Se admiten los siguientes campos, que se reenvían directamente a la regla de repo 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 se basa en una regla de repo de local_repository y se vincula con un symlink a un directorio en el disco local. Admite el siguiente campo:
  • path: Es la ruta de acceso local al repo, que se calcula de la siguiente manera:
    • Si path es una ruta de acceso absoluta, se mantiene como está.
    • Si path es una ruta relativa y module_base_path es una ruta absoluta, se resuelve como <module_base_path>/<path>.
    • Si path y module_base_path son rutas relativas, 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.

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 la interfaz 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 para la contribución de 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 destinos de compilación y prueba esenciales que puedes usar para verificar la validez de esta versión del módulo. Las canalizaciones de CI de BCR también usan esto 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 desde los que se solicitan 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 mayor comodidad, puedes incluir 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 de --registry necesita una dirección de GitHub sin procesar en raw.githubusercontent.com. Por ejemplo, en la rama main de la bifurcación my-org, deberías establecer --registry=https://raw.githubusercontent.com/my-org/bazel-central-registry/main/.

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