Esta página está destinada a los escritores de normas que planean poner sus normas a disposición. a 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 de tu conjunto de reglas sea trivial.
Reglas de hosting y denominación
Las reglas nuevas deben ingresarse en su propio repositorio de GitHub dentro de tu organización. Inicia una conversación en GitHub. si crees que tus reglas pertenecen a bazelbuild organización.
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 descriptiva del repositorio de GitHub y 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 - 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 con Bazel al lugar correcto)
Las reglas se pueden agrupar por lenguaje (como Scala), plataforma de entorno de ejecución (como Android) o un framework (como Spring).
Contenido del repositorio
Cada repositorio de reglas debe tener un diseño determinado para que los usuarios entender nuevas reglas.
Por ejemplo, cuando escribas reglas nuevas para el (de los)
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 usarán los usuarios.
para consultar las reglas. Si tus reglas pertenecen al
bazelbuild, debes usar
rules_<lang> (como rules_mockascript). De lo contrario, debes asignarle un
el repositorio <org>_rules_<lang> (como build_stack_rules_proto). Por favor,
inicia una conversación en GitHub
Si cree que sus reglas deberían seguir la convención de reglas en la
organización bazelbuild.
En las siguientes secciones, supongamos que el repositorio pertenece al bazelbuild.
module(name = "rules_mockascript")
README
En el nivel superior, debe haber un README que contenga una breve descripción.
del conjunto de reglas y la API que deben esperar los usuarios.
Reglas
A menudo, tu repositorio proporciona múltiples reglas. Crea un
directorio nombrado por el lenguaje y proporcionan un punto de entrada: archivo defs.bzl
exportar todas las reglas (también incluir un archivo BUILD para que el directorio sea un paquete)
Para rules_mockascript, significa que habrá un directorio llamado
mockascript, un archivo BUILD y un archivo defs.bzl en su interior:
/
mockascript/
BUILD
defs.bzl
Limitaciones
Si tu regla define
toolchain,
es posible que debas definir constraint_setting personalizados.
constraint_value Colócalos en un paquete //<LANG>/constraints. Tu
de directorios se verá de la siguiente manera:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
Lee atentamente.
github.com/bazelbuild/platforms
prácticas recomendadas y para ver qué restricciones ya están presentes
considera contribuir con tus restricciones allí si son independientes del lenguaje.
Ten en cuenta que debes implementar restricciones personalizadas, ya que todos los usuarios de tus reglas
los usan para realizar lógicas específicas de plataformas en sus archivos BUILD (por ejemplo,
con selects).
Con restricciones personalizadas, defines un lenguaje en el que todo el ecosistema de Bazel
hablará.
Biblioteca Runfiles
Si tu regla proporciona una biblioteca estándar para acceder a archivos de ejecución, debería ser
como un destino de biblioteca ubicado en //<LANG>/runfiles (una abreviatura
de //<LANG>/runfiles:runfiles). Destinos del usuario que necesitan acceder a sus datos
por lo general, las dependencias agregan este destino a su atributo deps.
Reglas del repositorio
Dependencias
Puede que tus reglas tengan dependencias externas, que deberás especificar tu archivo MODULE.bazel.
Registra las cadenas de herramientas
Es posible que tus reglas también registren cadenas de herramientas, lo cual también puedes especificar en el MODULE.bazel.
Ten en cuenta que, para resolver las cadenas de herramientas en la fase de análisis, Bazel debe
analizar todos los objetivos de toolchain que están registrados. Bazel no necesitará
Analiza todos los destinos a los que hace referencia el atributo toolchain.toolchain. Si está en orden
Para registrar cadenas de herramientas, debes realizar cómputos complejos en la
repositorio, considera dividir el repositorio con destinos toolchain de
con <LANG>_toolchain objetivos. El anterior siempre se recuperará
Esta última solo se recuperará cuando el usuario necesite compilar código <LANG>.
Fragmento de lanzamiento
En el anuncio de lanzamiento, incluye 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 funcionan según lo previsto. Esta
puede estar en la ubicación estándar del idioma de las reglas o en un
tests/ en el nivel superior.
Ejemplos (opcionales)
Es útil para los usuarios tener un directorio examples/ que les muestre algunas
de las formas básicas en que se pueden 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” en bazel-contrib
.org. ci.yaml ejecuta pruebas en cada PR y main comit, y release.yaml se ejecuta cada vez que envías una etiqueta al repositorio.
Consulta los comentarios en el repositorio rules-template para obtener más información.
Si tu repositorio está en la organización bazelbuild, puedes pedir 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 se pueda generar documentación automáticamente.
La carpeta rules-template docs/
muestra una forma sencilla de garantizar que el contenido de Markdown en 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 GitHub de Bazel?
Queremos separar las reglas de los lanzamientos de Bazel tanto como sea posible. Es más claro que posee las reglas individuales, lo que reduce la carga en los desarrolladores de Bazel. Para nuestros usuarios, la separación facilita la modificación, la actualización, el cambio a una versión inferior y el reemplazo de reglas. Contribuir a las reglas puede ser más sencillo que contribuir a Bazel: según las reglas, incluido el acceso completo de envío a las Repositorio de GitHub. Obtener acceso de envío a Bazel es mucho más complejo el proceso de administración de recursos.
La desventaja es un proceso de instalación único más complicado para nuestros usuarios:
debe agregar una dependencia al conjunto de reglas en su archivo MODULE.bazel.
Teníamos todas las reglas en el repositorio de Bazel (en
//tools/build_rules o //tools/build_defs). Aún tenemos algunas reglas
pero estamos trabajando para quitar las reglas restantes.