Esta página está destinada a los escritores de reglas que planean poner sus reglas a disposición de otros.
Reglas de hosting y denominación
Las reglas nuevas deben ir a su propio repositorio de GitHub en tu organización. Comunícate con la lista de distribución de bazel-dev si crees que tus reglas pertenecen a la organización bazelbuild.
Los nombres de repositorio 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
de repositorio de GitHub 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 estén familiarizados con Bazel al lugar correcto)
Las reglas se pueden agrupar por lenguaje (como Scala) o por plataforma (como Android).
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 escribas reglas nuevas para el lenguaje mockascript (ficticio), 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 asignarle a tu repositorio el nombre <org>_rules_<lang> (como build_stack_rules_proto). Comunícate con la lista de distribución de bazel-dev si crees que tus reglas deben seguir la convención para las reglas en la organización bazelbuild.
En las siguientes secciones, supongamos 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 apunta a tu versión de GitHub y una llamada a macro que descarga y configura las herramientas que necesita tu regla. Por ejemplo, para las reglas de Go, se verá 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, 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, significa que habrá un directorio llamado mockascript, y un archivo BUILD y un archivo defs.bzl en su interior:
/
mockascript/
BUILD
defs.bzl
Limitaciones
Si tu regla define reglas de la
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 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. Para simplificar la dependencia 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 macro de punto de entrada única llamada rules_<LANG>_dependencies. Nuestro directorio se verá de la siguiente manera:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
repositories.bzl
Registra las cadenas de herramientas
Es posible que tus reglas también registren 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 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 se recuperará siempre y el segundo solo se recuperará cuando el usuario 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 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 funcionen 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)
Para los usuarios, es útil tener un directorio examples/ que les muestre algunas formas básicas de usar las reglas.
Prueba
Configura Travis como se describe en sus documentos de introducción. Luego, agrega un archivo .travis.yml a tu repositorio con el siguiente contenido:
dist: xenial # Ubuntu 16.04
# On trusty (or later) images, the Bazel apt repository can be used.
addons:
apt:
sources:
- sourceline: 'deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8'
key_url: 'https://bazel.build/bazel-release.pub.gpg'
packages:
- bazel
script:
- bazel build //...
- bazel test //...
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 se pueda generar la documentación automáticamente.
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. 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: 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 un par de reglas
allí, pero estamos trabajando para quitar las reglas restantes.