Implementa reglas

Informar un problema Ver fuente . Por la noche · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Esta página está destinada a los escritores de normas que planean poner sus normas a disposición. a otras personas.

Reglas de hosting y denominación

Las reglas nuevas deben ingresarse en su propio repositorio de GitHub dentro de tu organización. Comunícate con la lista de distribución de bazel-dev 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) o la plataforma (como Android).

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

workspace(name = "rules_mockascript")

README

En el nivel superior, debe haber un README que contenga (al menos) qué. los usuarios deberán copiar y pegar en su archivo WORKSPACE para usar su regla. En general, será un http_archive que apunta a tu versión de GitHub y una llamada de macro que descarga o configura las herramientas que necesita la regla. Por ejemplo: para la interfaz Go de la aplicación, se ve así:

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 el documentación de reglas (por ejemplo, consulta el Reglas de Skydoc que dependen de las reglas de Sass) y proporcionan un WORKSPACE que descargará 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 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

Es posible que tus reglas tengan dependencias externas. Para tomar según tus reglas más simple, 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 WORKSPACE.

Crea un archivo llamado <LANG>/repositories.bzl y proporciona un solo punto de entrada. macro 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 otro WORKSPACE. que registra estas cadenas de herramientas. De esta manera, los usuarios pueden decidir omitir macro anterior y controlar las dependencias de forma manual, mientras que se le permite registrar cadenas de herramientas.

Por lo tanto, agrega una macro WORKSPACE llamada rules_<LANG>_toolchains en 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 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 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. 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.

Prueba

Configura Travis como se describe en la sección de introducción. documentación. Luego, agrega .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 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.

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 copiar y pegar una regla en su archivo WORKSPACE, como se muestra en el README.md en la sección anterior.

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.