Implementa reglas

Nightly · 9.1 · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 8.1

Esta página es para los escritores de reglas que planean poner sus reglas a disposición de otros usuarios.

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 bazel-dev si crees que tus reglas pertenecen a la organización bazelbuild.

Los nombres de los repositorios para 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 título README.md. Por ejemplo:

  • Nombre del repositorio: bazelbuild/rules_go
  • Descripción del repositorio: Reglas de Go para Bazel
  • Etiquetas del repositorio: golang, bazel
  • README.md encabezado: 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) o plataforma (como Android).

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 mockascript (ficticio), el repositorio de reglas tendría 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

PAGADO

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). Comunícate con la lista de distribución bazel-dev 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.

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 de 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 WORKSPACE macro que descargue todas las dependencias (consulta rules_go más arriba).

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 en el interior:

/
  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, ver qué restricciones ya están presentes y considerar aportar tus restricciones allí si son independientes del idioma. Ten cuidado al introducir 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 archivos de ejecución

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. Para que la dependencia de tus reglas sea más sencilla, proporciona una macro WORKSPACE que declare dependencias de esas dependencias externas. No declares dependencias de pruebas allí, solo las dependencias que requieren las reglas 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

Registro de 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 poder 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 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 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 como se espera. Esto puede estar en la ubicación estándar para el idioma de las reglas o en un directorio tests/ 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.

Prueba

Configura Travis como se describe en su documentación 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 la documentación se pueda generar automáticamente.

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. La contribución a las reglas puede ser más liviana que la contribución a Bazel, según las reglas, incluido el acceso completo al envío al repositorio de GitHub correspondiente. Obtener acceso al 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.