Esta página es para los escritores de reglas que planean poner sus reglas a disposición de otros usuarios.
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, incluye la generación de documentación de la API y configura una canalización de CI/CD para que sea trivial distribuir tu conjunto de reglas.
Reglas de hosting y denominación
Las reglas nuevas deben ir a su propio repositorio de GitHub en tu organización. Inicia un debate en GitHub si crees que tus reglas pertenecen a la organización bazelbuild.
Los nombres de los repositorios de las reglas de Bazel se estandarizan 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 descriptiva del repositorio de GitHub y un README.md
título. Por ejemplo:
- Nombre del repositorio:
bazelbuild/rules_go - Descripción del repositorio: Reglas de Go para Bazel
- Etiquetas del repositorio:
golang,bazel README.mdencabezado: Reglas de Go para Bazel (observa 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 idioma (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 se escriben reglas nuevas para el lenguaje (ficticio)
mockascript, el repositorio de reglas tendría 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). Por favor,
inicia un debate en GitHub
si crees que tus reglas deben seguir la convención para las reglas de la
organización bazelbuild.
En las siguientes secciones, se supone que el repositorio pertenece a la organización bazelbuild.
module(name = "rules_mockascript")
README
En el nivel superior, debe haber un README que contenga una breve descripción
de tu conjunto de reglas y la API que los usuarios deben esperar.
Reglas
A menudo, tu repositorio proporcionará varias reglas. Crea un
directorio con el nombre del idioma y proporciona un punto de entrada: 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, 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_settings o
constraint_values personalizadas. Colócalas en un paquete //<LANG>/constraints. La estructura de tu
directorio se verá de la siguiente manera:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
Lee
github.com/bazelbuild/platforms
para conocer las prácticas recomendadas y ver qué restricciones ya están presentes.
Considera aportar tus restricciones allí si son independientes del idioma.
Ten en cuenta la introducción de restricciones personalizadas. 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 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 estar
en la forma de un destino de biblioteca ubicado en //<LANG>/runfiles (una abreviatura
de //<LANG>/runfiles:runfiles). Los destinos de usuario que necesiten acceder a sus dependencias de datos
suelen agregar 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.
Registro de 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 cadenas de herramientas en la fase de análisis, Bazel debe
analizar todos los destinos 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 cálculos complejos en el
repositorio, considera dividir el repositorio con toolchain destinos del
repositorio con <LANG>_toolchain destinos. El primero siempre se recuperará, y
el segundo solo se recuperará cuando el usuario realmente necesite compilar código <LANG>.
Fragmento de lanzamiento
En el anuncio de 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 previsto. Esto
puede estar en la ubicación estándar del idioma para el que son las reglas o en un
tests/ directorio en el nivel superior.
Ejemplos (opcionales)
Es útil para los usuarios tener un directorio examples/ que les muestre un par
de formas básicas en las que se pueden usar las reglas.
CI/CD
Muchos conjuntos de reglas usan acciones de GitHub. Consulta la configuración que se usa en el repositorio de rules-template, que se simplifica con un "flujo de trabajo reutilizable" alojado en la organización bazel-contrib. ci.yaml ejecuta pruebas en cada solicitud de extracción y en cada confirmación main, y release.yaml se ejecuta cada vez que envías una etiqueta al repositorio.
Consulta los comentarios en el repositorio de rules-template 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 pueda generar automáticamente.
La carpeta rules-template docs/
de rules-template muestra una forma sencilla de garantizar que el contenido de Markdown de la carpeta docs/ esté siempre 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. Es 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, el desacoplamiento facilita la modificación, la actualización, el cambio a una versión anterior y el reemplazo de reglas. Contribuir a las reglas puede ser más liviano que contribuir a Bazel (según las reglas), incluido el acceso completo para enviar al repositorio de GitHub correspondiente. Obtener acceso para enviar a Bazel es un proceso mucho más complejo.
La desventaja es un proceso de instalación única más complicado para nuestros usuarios:
deben 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 un par de reglas
allí, pero estamos trabajando para quitar las reglas restantes.