Instructivo de reglas

Informar un problema Ver fuente Noche {/2/}}

Starlark es un lenguaje de configuración similar a Python desarrollado originalmente para su uso en Bazel y desde que lo adoptaron otras herramientas. Los archivos BUILD y .bzl de Bazel están escritos en un dialecto de Starlark, bien conocido como el "lenguaje de compilación", aunque a menudo se lo conoce como "Starlark", especialmente cuando se hace hincapié en que una función se expresa en el lenguaje de compilación en lugar de ser una parte integrada o "nativa" de Bazel. Bazel aumenta el lenguaje principal con varias funciones relacionadas con la compilación, como glob, genrule, java_binary y otras.

Consulta la documentación de Bazel y Starlark para obtener más detalles y la plantilla de SIG de reglas como punto de partida para los conjuntos de reglas nuevos.

La regla vacía

Para crear tu primera regla, crea el archivo foo.bzl:

def _foo_binary_impl(ctx):
    pass

foo_binary = rule(
    implementation = _foo_binary_impl,
)

Cuando llamas a la función rule, debes definir una función de devolución de llamada. La lógica irá allí, pero puedes dejar la función vacía por ahora. El argumento ctx proporciona información sobre el destino.

Puedes cargar la regla y usarla desde un archivo BUILD.

Crea un archivo BUILD en el mismo directorio:

load(":foo.bzl", "foo_binary")

foo_binary(name = "bin")

Ahora, se puede crear el destino:

$ bazel build bin
INFO: Analyzed target //:bin (2 packages loaded, 17 targets configured).
INFO: Found 1 target...
Target //:bin up-to-date (nothing to build)

Si bien la regla no hace nada, ya se comporta como otras reglas: tiene un nombre obligatorio y admite atributos comunes como visibility, testonly y tags.

Modelo de evaluación

Antes de continuar, es importante comprender cómo se evalúa el código.

Actualiza foo.bzl con algunas sentencias de impresión:

def _foo_binary_impl(ctx):
    print("analyzing", ctx.label)

foo_binary = rule(
    implementation = _foo_binary_impl,
)

print("bzl file evaluation")

y CREA:

load(":foo.bzl", "foo_binary")

print("BUILD file")
foo_binary(name = "bin1")
foo_binary(name = "bin2")

ctx.label corresponde a la etiqueta del objetivo que se analiza. El objeto ctx tiene muchos campos y métodos útiles. Puedes encontrar una lista completa en la referencia de la API.

Consulta el código:

$ bazel query :all
DEBUG: /usr/home/bazel-codelab/foo.bzl:8:1: bzl file evaluation
DEBUG: /usr/home/bazel-codelab/BUILD:2:1: BUILD file
//:bin2
//:bin1

Haz algunas observaciones:

  • Primero se imprimirá la “evaluación del archivo bzl”. Antes de evaluar el archivo BUILD, Bazel evalúa todos los archivos que carga. Si varios archivos BUILD cargan foo.bzl, solo verás un caso de “evaluación del archivo bzl” porque Bazel almacena en caché el resultado de la evaluación.
  • No se llama a la función de devolución de llamada _foo_binary_impl. La consulta de Bazel carga archivos BUILD, pero no analiza los destinos.

Para analizar los destinos, usa cquery ("consulta configurada") o el comando build:

$ bazel build :all
DEBUG: /usr/home/bazel-codelab/foo.bzl:8:1: bzl file evaluation
DEBUG: /usr/home/bazel-codelab/BUILD:2:1: BUILD file
DEBUG: /usr/home/bazel-codelab/foo.bzl:2:5: analyzing //:bin1
DEBUG: /usr/home/bazel-codelab/foo.bzl:2:5: analyzing //:bin2
INFO: Analyzed 2 targets (0 packages loaded, 0 targets configured).
INFO: Found 2 targets...

Como puedes ver, ahora se llama a _foo_binary_impl dos veces, una para cada destino.

Algunos lectores verán que "bzl file evaluate" se vuelve a imprimir, aunque la evaluación de foo.bzl se almacena en caché después de la llamada a bazel query. Bazel no reevalúa el código, solo vuelve a reproducir los eventos de impresión. Sin importar el estado de la caché, obtienes el mismo resultado.

Cómo crear un archivo

Para que tu regla sea más útil, actualízala para generar un archivo. Primero, decláralo y asígnale un nombre. En este ejemplo, crea un archivo con el mismo nombre que el destino:

ctx.actions.declare_file(ctx.label.name)

Si ejecutas bazel build :all ahora, verás un error:

The following files have no generating action:
bin2

Cada vez que declaras un archivo, debes indicarle a Bazel cómo generarlo creando una acción. Usa ctx.actions.write para crear un archivo con el contenido determinado.

def _foo_binary_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name)
    ctx.actions.write(
        output = out,
        content = "Hello\n",
    )

El código es válido, pero no hará nada:

$ bazel build bin1
Target //:bin1 up-to-date (nothing to build)

La función ctx.actions.write registró una acción, lo que le enseñó a Bazel a generar el archivo. Sin embargo, Bazel no creará el archivo hasta que se solicite. Por lo tanto, lo último que debes hacer es indicarle a Bazel que el archivo es un resultado de la regla y no un archivo temporal que se usa en la implementación de la regla.

def _foo_binary_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name)
    ctx.actions.write(
        output = out,
        content = "Hello!\n",
    )
    return [DefaultInfo(files = depset([out]))]

Observa las funciones DefaultInfo y depset más adelante. Por ahora, supón que la última línea es la forma de elegir los resultados de una regla.

Ahora, ejecuta Bazel:

$ bazel build bin1
INFO: Found 1 target...
Target //:bin1 up-to-date:
  bazel-bin/bin1

$ cat bazel-bin/bin1
Hello!

Generaste un archivo correctamente.

Atributos

Para que la regla sea más útil, agrega atributos nuevos con el módulo attr y actualiza la definición de la regla.

Agrega un atributo de cadena llamado username:

foo_binary = rule(
    implementation = _foo_binary_impl,
    attrs = {
        "username": attr.string(),
    },
)

Luego, configúrala en el archivo BUILD:

foo_binary(
    name = "bin",
    username = "Alice",
)

Para acceder al valor de la función de devolución de llamada, usa ctx.attr.username. Por ejemplo:

def _foo_binary_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name)
    ctx.actions.write(
        output = out,
        content = "Hello {}!\n".format(ctx.attr.username),
    )
    return [DefaultInfo(files = depset([out]))]

Ten en cuenta que puedes hacer que el atributo sea obligatorio o establecer un valor predeterminado. Consulta la documentación de attr.string. También puedes usar otros tipos de atributos, como boolean o lista de números enteros.

Dependencias

Los atributos de dependencia, como attr.label y attr.label_list, declaran una dependencia del destino que posee el atributo al destino cuya etiqueta aparece en el valor del atributo. Este tipo de atributo constituye la base del gráfico de destino.

En el archivo BUILD, la etiqueta de destino aparece como un objeto de cadena, por ejemplo, //pkg:name. En la función de implementación, se podrá acceder al destino como un objeto Target. Por ejemplo, usa Target.files para ver los archivos que muestra el destino.

Varios archivos

De forma predeterminada, solo los destinos creados por reglas pueden aparecer como dependencias (como un objetivo foo_library()). Si deseas que el atributo acepte destinos que son archivos de entrada (como archivos de origen en el repositorio), puedes hacerlo con allow_files y especificar la lista de extensiones de archivo aceptadas (o True para permitir cualquier extensión de archivo):

"srcs": attr.label_list(allow_files = [".java"]),

Se puede acceder a la lista de archivos con ctx.files.<attribute name>. Por ejemplo, se puede acceder a la lista de archivos en el atributo srcs con

ctx.files.srcs

Archivo único

Si solo necesitas un archivo, usa allow_single_file:

"src": attr.label(allow_single_file = [".java"])

Luego, se puede acceder a este archivo en ctx.file.<attribute name>:

ctx.file.src

Crea un archivo con una plantilla

Puedes crear una regla que genere un archivo .cc basado en una plantilla. Además, puedes usar ctx.actions.write para generar una string construida en la función de implementación de reglas, pero esto tiene dos problemas. Primero, a medida que la plantilla se hace más grande, se vuelve más eficiente en cuanto a la memoria colocarla en un archivo separado y evitar construir cadenas grandes durante la fase de análisis. En segundo lugar, usar un archivo separado es más conveniente para el usuario. En su lugar, usa ctx.actions.expand_template, que realiza sustituciones en un archivo de plantilla.

Crea un atributo template para declarar una dependencia en el archivo de plantilla:

def _hello_world_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name + ".cc")
    ctx.actions.expand_template(
        output = out,
        template = ctx.file.template,
        substitutions = {"{NAME}": ctx.attr.username},
    )
    return [DefaultInfo(files = depset([out]))]

hello_world = rule(
    implementation = _hello_world_impl,
    attrs = {
        "username": attr.string(default = "unknown person"),
        "template": attr.label(
            allow_single_file = [".cc.tpl"],
            mandatory = True,
        ),
    },
)

Los usuarios pueden usar la regla de la siguiente manera:

hello_world(
    name = "hello",
    username = "Alice",
    template = "file.cc.tpl",
)

cc_binary(
    name = "hello_bin",
    srcs = [":hello"],
)

Si no quieres exponer la plantilla al usuario final y usar siempre la misma, puedes establecer un valor predeterminado y hacer que el atributo sea privado:

    "_template": attr.label(
        allow_single_file = True,
        default = "file.cc.tpl",
    ),

Los atributos que comienzan con un guion bajo son privados y no se pueden configurar en un archivo BUILD. Ahora la plantilla es una dependencia implícita: cada destino hello_world tiene una dependencia en este archivo. No olvides que este archivo sea visible para otros paquetes mediante la actualización del archivo BUILD y el uso de exports_files:

exports_files(["file.cc.tpl"])

Un paso más allá