Esta página está dirigida a los autores de reglas que planean poner sus reglas a disposición de otros usuarios.
Te recomendamos que comiences un nuevo conjunto de reglas desde el repositorio de plantillas: https://github.com/bazel-contrib/rules-template. Esta 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 la distribución de tu conjunto de reglas sea trivial.
Reglas de alojamiento y nomenclatura
Las reglas nuevas deben ir a su propio repositorio de GitHub en tu organización. Inicia un hilo en GitHub si crees que tus reglas pertenecen a la organización bazelbuild.
Los nombres de los repositorios para las reglas de Bazel se estandarizan con el siguiente formato: $ORGANIZATION/rules_$NAME.
Consulta los 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 y un título README.md descriptivos. 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 conocen Bazel al lugar correcto)
Las reglas se pueden agrupar por lenguaje (como Scala), plataforma 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 (ficticio) mockascript, 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
ESPACIO DE TRABAJO
En el WORKSPACE 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 un hilo en GitHub si crees que tus reglas deben seguir la convención de las reglas de la organización bazelbuild.
En las siguientes secciones, se supone 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á un http_archive que apunte a tu versión de GitHub y una llamada a una macro que descargue o configure las herramientas que necesite tu regla. Por ejemplo, para las reglas de Go, 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ícalo en la documentación de las reglas (por ejemplo, consulta las reglas de Skydoc, que dependen de las reglas de Sass) y proporciona una macro WORKSPACE que descargue todas las dependencias (consulta rules_go más arriba).
Reglas
A menudo, el 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).
En el caso de rules_mockascript, 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 toolchain, es posible que debas definir constraint_settings o constraint_values 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
Lee github.com/bazelbuild/platforms para conocer las prácticas recomendadas y ver qué restricciones ya están presentes, y considera aportar tus restricciones allí si son independientes del lenguaje.
Ten en cuenta que, si introduces restricciones personalizadas, todos los usuarios de tus reglas las usarán para realizar lógica específica de la plataforma en sus archivos BUILD (por ejemplo, con selects).
Con las restricciones personalizadas, defines un lenguaje que todo el ecosistema de Bazel utilizará.
Biblioteca de archivos ejecutables
Si tu regla proporciona una biblioteca estándar para acceder a los archivos ejecutables, debe tener la forma de un destino de biblioteca ubicado en //<LANG>/runfiles (una abreviatura de //<LANG>/runfiles:runfiles). Los destinos del 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. Para que sea más sencillo depender de tus reglas, proporciona una macro WORKSPACE que declare dependencias en esas dependencias externas. No declares dependencias de pruebas allí, solo las 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 sola 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
Cómo registrar 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, y, al mismo tiempo, se les permite 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 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 destinos toolchain del repositorio con destinos <LANG>_toolchain. El primero siempre se recuperará, y el segundo solo se recuperará cuando el usuario realmente necesite compilar código de <LANG>.
Fragmento de versión
En el anuncio de lanzamiento, proporciona un fragmento que los 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
Debe haber pruebas que verifiquen que las reglas funcionan según lo previsto. Puede estar en la ubicación estándar del idioma para el que son las reglas o en un directorio tests/ en el nivel superior.
Ejemplos (opcionales)
Es útil para los usuarios tener un directorio de examples/ que les muestre algunas formas básicas en 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 repo 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 confirmación de main, y release.yaml se ejecuta cada vez que envías una etiqueta al repositorio.
Consulta los comentarios en el repo de la plantilla de reglas 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 de modo que la documentación se pueda generar automáticamente.
La carpeta 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 de Starlark.
Preguntas frecuentes
¿Por qué no podemos agregar nuestra regla al repositorio principal de Bazel en GitHub?
Queremos desacoplar las reglas de las versiones de Bazel lo más posible. Es más claro quién posee 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 con reglas puede ser más sencillo que contribuir con Bazel (según las reglas), incluido el acceso completo para enviar cambios al repositorio de GitHub correspondiente. Obtener acceso para enviar cambios a Bazel es un proceso mucho más complejo.
La desventaja es que el proceso de instalación única es más complicado para nuestros usuarios, ya que deben copiar y pegar una regla en su archivo WORKSPACE, como se muestra en la sección README.md anterior.
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 reglas restantes.