Implementa reglas

Esta página está dirigida a los creadores de reglas que planean poner sus reglas a disposición de otras personas.

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 e 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 nombres y hosting

Las reglas nuevas deben 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 y un título README.md descriptivos del repositorio de GitHub, por ejemplo:

• Nombre del repositorio: bazelbuild/rules_go
• Descripción del repositorio: Reglas de Go para Bazel
• Etiquetas del 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 estén familiarizados con Bazel al lugar correcto)

Las reglas se pueden agrupar por lenguaje (como Scala), plataforma de tiempo 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 rápidamente las reglas nuevas.

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

/
  LICENSE
  README
  MODULE.bazel
  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

MODULE.bazel

En el MODULE.bazel del proyecto, debes definir el nombre que los usuarios usarán 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 nombrar tu repositorio <org>_rules_<lang> (como build_stack_rules_proto). Inicia una conversación en GitHub si crees que tus reglas deben seguir la convención de reglas de la organización bazelbuild.

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

module(name = "rules_mockascript")

README

En el nivel superior, debería haber un README que contenga una breve descripción de tu conjunto de reglas y lo que los usuarios de la API deberían esperar.

Reglas

A menudo, tu repositorio proporciona múltiples reglas. Crea un directorio nombrado por el lenguaje y proporciona un punto de entrada: un archivo defs.bzl que exporte 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, y un archivo BUILD y un archivo defs.bzl dentro:

/
  mockascript/
    BUILD
    defs.bzl

Limitaciones

Si tu regla define reglas de cadena de herramientas, es posible que debas definir constraint_setting o constraint_value personalizados. Colócalas 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 están presentes, y considera contribuir con tus restricciones allí si son independientes del lenguaje. Ten cuidado cuando introduzcas 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 selección). Con las restricciones personalizadas, defines un lenguaje que hablará todo el ecosistema de Bazel.

Biblioteca de Runfiles

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

Reglas del repositorio

Dependencias

Es posible que tus reglas tengan dependencias externas, que deberás especificar en tu archivo MODULE.bazel.

Registra las cadenas de herramientas

Tus reglas también pueden registrar cadenas de herramientas, que también puedes especificar en el archivo MODULE.bazel.

Ten en cuenta que, para resolver las cadenas de herramientas en la fase de análisis, Bazel debe analizar todos los destinos de toolchain que están 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 procesamientos complejos en el repositorio, considera dividirlo con destinos toolchain del repositorio con objetivos <LANG>_toolchain. El primero siempre se recuperará y el segundo solo se recuperará cuando el usuario realmente necesite compilar el código <LANG>.

Fragmento de lanzamiento

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

bazel_dep(name = "rules_<LANG>", version = "<VERSION>")

Pruebas

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

Ejemplos (opcionales)

Para los usuarios, es útil tener un directorio examples/ que les muestre algunas formas básicas de usar las reglas.

CI/CD

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-contrib. ci.yaml ejecuta pruebas en cada PR y confirmación de main, y release.yaml se ejecuta cada vez que envías una etiqueta al repositorio. Consulta los comentarios en el repositorio de reglas de plantillas para obtener más información.

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

Documentación

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

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

Preguntas frecuentes

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

Queremos desacoplar las reglas de las versiones de Bazel lo más posible. Está más claro quién es el propietario de las reglas individuales, lo que reduce la carga de los desarrolladores de Bazel. Para nuestros usuarios, la desvinculación facilita la modificación, actualización, baja y reemplazo de reglas. Contribuir a las reglas puede ser más ligero que contribuir a Bazel, según las reglas, lo que incluye el acceso de envío completo 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: tienen que agregar una dependencia en tu conjunto de reglas en su archivo MODULE.bazel.

Antes teníamos todas las reglas en el repositorio de Bazel (en //tools/build_rules o //tools/build_defs). Todavía tenemos algunas reglas allí, pero estamos trabajando para quitar las restantes.