Implementa reglas

Informar un problema Ver fuente

Esta página está destinada a los escritores de reglas que planean poner sus reglas a disposición de otros.

Te recomendamos que inicies un nuevo conjunto de reglas desde el repositorio de plantillas: https://github.com/bazel-contrib/rules-template Esa plantilla sigue las recomendaciones que se indican a continuación y, además, incluye la generación de documentación de la API y configura una canalización de CI/CD para que la distribución del conjunto de reglas sea trivial.

Reglas de hosting y nombres

Las reglas nuevas deberían ir a su propio repositorio de GitHub en tu organización. Inicia un subproceso en GitHub si crees que tus reglas pertenecen a la organización bazelbuild.

Los nombres de repositorios para las reglas de Bazel están estandarizados en el siguiente formato: $ORGANIZATION/rules_$NAME. Consulta ejemplos en GitHub. Para mantener la coherencia, debes seguir este mismo formato cuando publiques tus reglas de Bazel.

Asegúrate de usar una descripción del repositorio de GitHub descriptiva y un título de README.md, por ejemplo:

  • Nombre del repositorio: bazelbuild/rules_go
  • Descripción del repositorio: Go rules for Bazel
  • Etiquetas de repositorio: golang, bazel
  • Encabezado README.md: Reglas de Go para Bazel (ten en cuenta el vínculo a https://bazel.build que guiará a los usuarios que no conocen Bazel al lugar correcto)

Las reglas se pueden agrupar por lenguaje (como Scala), plataforma de entorno de ejecución (como Android) o framework (como Spring).

Contenido del repositorio

Cada repositorio de reglas debe tener un diseño determinado para que los usuarios puedan comprender las reglas nuevas con rapidez.

Por ejemplo, cuando se escriben reglas nuevas para el lenguaje mockascript (inventario), el repositorio de reglas tendrá la siguiente estructura:

/
  LICENSE
  README
  WORKSPACE
  mockascript/
    constraints/
      BUILD
    runfiles/
      BUILD
      runfiles.mocs
    BUILD
    defs.bzl
  tests/
    BUILD
    some_test.sh
    another_test.py
  examples/
    BUILD
    bin.mocs
    lib.mocs
    test.mocs

LUGAR DE TRABAJO

En el WORKSPACE del proyecto, debes definir el nombre que usarán los usuarios para hacer referencia a tus reglas. Si tus reglas pertenecen a la organización bazelbuild, debes usar rules_<lang> (como rules_mockascript). De lo contrario, debes asignar el nombre <org>_rules_<lang> al repositorio (como build_stack_rules_proto). Inicia una conversación en GitHub si crees que tus reglas deben seguir la convención para las reglas de la organización bazelbuild.

En las siguientes secciones, supón que el repositorio pertenece a la organización bazelbuild.

workspace(name = "rules_mockascript")

readme

En el nivel superior, debe haber un README que contenga (al menos) lo que los usuarios deberán copiar y pegar en su archivo WORKSPACE para usar tu regla. En general, será una http_archive que apunte a tu versión de GitHub y una llamada a macro que descarga o configura cualquier herramienta que necesite tu regla. Por ejemplo, para las reglas de Go, esto se ve de la siguiente manera:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "rules_go",
    urls = ["https://github.com/bazelbuild/rules_go/releases/download/0.18.5/rules_go-0.18.5.tar.gz"],
    sha256 = "a82a352bffae6bee4e95f68a8d80a70e87f42c4741e6a448bec11998fcc82329",
)
load("@rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains")
go_rules_dependencies()
go_register_toolchains()

Si tus reglas dependen de las reglas de otro repositorio, especifícala en la documentación de reglas (por ejemplo, consulta las reglas de Skydoc, que dependen de las reglas de Sass), y proporciona una macro WORKSPACE que descargará todas las dependencias (consulta rules_go más arriba).

Reglas

A menudo, tu repositorio proporcionará varias reglas. Crea un directorio nombrado por el lenguaje y proporciona un punto de entrada: el archivo defs.bzl que exporta todas las reglas (también incluye un archivo BUILD para que el directorio sea un paquete). Para rules_mockascript, eso significa que habrá un directorio llamado mockascript, un archivo BUILD y un archivo defs.bzl dentro de lo siguiente:

/
  mockascript/
    BUILD
    defs.bzl

Limitaciones

Si tu regla define reglas de la cadena de herramientas, es posible que debas definir elementos constraint_setting o constraint_value personalizados. Colócalos en un paquete //<LANG>/constraints. La estructura de tu directorio se verá de la siguiente manera:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

Consulta github.com/bazelbuild/platforms para conocer las prácticas recomendadas y ver qué restricciones ya existen, y considera contribuir con tus restricciones allí si son independientes del lenguaje. Ten en cuenta que debes agregar restricciones personalizadas, ya que todos los usuarios de tus reglas las usarán para realizar una lógica específica de la plataforma en sus archivos BUILD (por ejemplo, con selecciones). Con las restricciones personalizadas, defines el lenguaje que hablará todo el ecosistema de Bazel.

Biblioteca Runfiles

Si tu regla proporciona una biblioteca estándar para acceder a archivos de ejecución, debe tener el formato de un destino de biblioteca ubicado en //<LANG>/runfiles (abreviatura de //<LANG>/runfiles:runfiles). Por lo general, los objetivos de usuario que necesitan acceder a sus dependencias de datos agregarán este destino a su atributo deps.

Reglas del repositorio

Dependencias

Tus reglas pueden tener dependencias externas. Para simplificar las dependencias según tus reglas, proporciona una macro WORKSPACE que declare las dependencias de esas dependencias externas. No declares dependencias de pruebas allí, solo dependencias que las reglas requieren para funcionar. Coloca las dependencias de desarrollo en el archivo WORKSPACE.

Crea un archivo llamado <LANG>/repositories.bzl y proporciona una única macro de punto de entrada llamada rules_<LANG>_dependencies. Nuestro directorio se verá de la siguiente manera:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl
    repositories.bzl

Registra cadenas de herramientas

Tus reglas también pueden registrar cadenas de herramientas. Proporciona una macro WORKSPACE independiente que registre estas cadenas de herramientas. De esta manera, los usuarios pueden decidir omitir la macro anterior y controlar las dependencias de forma manual, sin dejar de registrar cadenas de herramientas.

Por lo tanto, agrega una macro WORKSPACE llamada rules_<LANG>_toolchains al archivo <LANG>/repositories.bzl.

Ten en cuenta que, para resolver las cadenas de herramientas en la fase de análisis, Bazel debe analizar todos los destinos de toolchain registrados. Bazel no necesitará analizar todos los destinos a los que hace referencia el atributo toolchain.toolchain. Si para registrar cadenas de herramientas necesitas realizar un procesamiento complejo en el repositorio, considera dividir el repositorio con destinos toolchain del repositorio con objetivos <LANG>_toolchain. El antiguo siempre se recuperará y el último solo se recuperará cuando el usuario realmente necesite compilar código <LANG>.

Fragmento de la versión

En el anuncio de lanzamiento, proporciona un fragmento que tus usuarios puedan copiar y pegar en su archivo WORKSPACE. En general, este fragmento se verá de la siguiente manera:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "rules_<LANG>",
    urls = ["<url_to_the_release.zip"],
    sha256 = "4242424242",
)
load("@rules_<LANG>//<LANG>:repositories.bzl", "rules_<LANG>_dependencies", "rules_<LANG>_toolchains")
rules_<LANG>_dependencies()
rules_<LANG>_toolchains()

Pruebas

Debería haber pruebas que verifiquen que las reglas funcionan según lo esperado. Puede estar en la ubicación estándar del idioma para el que están las reglas o en un directorio tests/ en el nivel superior.

Ejemplos (opcionales)

Resulta útil para los usuarios tener un directorio examples/ que les muestre algunas formas básicas en que se pueden usar las reglas.

IC/EC

Muchos conjuntos de reglas usan acciones de GitHub. Consulta la configuración usada en el repositorio rules-template, que se simplifica con un “flujo de trabajo reutilizable” alojado en la organización bazel-contribu. ci.yaml ejecuta pruebas en cada comit de main y PR, y release.yaml se ejecuta cada vez que envías una etiqueta al repositorio. Consulta los comentarios en el repositorio de plantillas de reglas para obtener más información.

Si tu repositorio está en la organización de bazelbuild, puedes pedirle que se agregue a ci.bazel.build.

Documentación

Consulta la documentación de Stardoc para obtener instrucciones sobre cómo comentar tus reglas y que la documentación se pueda generar automáticamente.

En rules-template docs/ folder, se muestra una forma sencilla de garantizar que el contenido de Markdown en la carpeta docs/ esté siempre actualizado a medida que se actualicen los archivos de Starlark.

Preguntas frecuentes

¿Por qué no podemos agregar nuestra regla al repositorio principal de GitHub de Bazel?

Queremos separar las reglas de las versiones de Bazel tanto como sea posible. Queda más claro quién posee las reglas individuales, lo que reduce la carga para los desarrolladores de Bazel. Para nuestros usuarios, la separación facilita la modificación, la actualización, el reemplazo de reglas y su actualización a una versión inferior. Contribuir a las reglas puede ser más liviano que contribuir a Bazel (según las reglas), incluido el acceso completo de envío al repositorio de GitHub correspondiente. Obtener acceso de envío a Bazel es un proceso mucho más complejo.

La desventaja es un proceso de instalación único más complicado para nuestros usuarios: deben copiar y pegar una regla en su archivo WORKSPACE, como se muestra en la sección README.md anterior.

Solíamos tener todas las reglas en el repositorio de Bazel (en //tools/build_rules o //tools/build_defs). Aún tenemos algunas reglas allí, pero estamos trabajando para mover las restantes.