Archivos BUILD

En las secciones anteriores, se describieron los paquetes, los objetivos y las etiquetas, y el gráfico de dependencia de compilación de manera abstracta. En esta sección, se describe la sintaxis concreta que se usa para definir un paquete.

Por definición, cada paquete contiene un archivo BUILD, que es un programa corto. Los archivos BUILD se evalúan con un lenguaje imperativo, Starlark.

Se interpretan como una lista secuencial de sentencias.

En general, el orden sí importa: las variables deben definirse antes de usarse, por ejemplo. Sin embargo, la mayoría de los archivos BUILD consisten solo de declaraciones de reglas de compilación, y el orden relativo de estas declaraciones es inmaterial. Lo que importa es qué reglas se declararon y con qué valores cuando se complete la evaluación del paquete.

Cuando se ejecuta una función de regla de compilación, como cc_library, se crea un destino nuevo en el gráfico. Más adelante, se puede hacer referencia a este destino mediante una etiqueta.

En los archivos BUILD simples, las declaraciones de reglas se pueden volver a ordenar libremente sin cambiar el comportamiento.

Para fomentar una separación clara entre el código y los datos, los archivos BUILD no pueden incluir definiciones de funciones, declaraciones for ni if (pero se permiten comprensión de listas y expresiones if). En su lugar, se pueden declarar las funciones en archivos .bzl. Además, no se permiten los argumentos *args y **kwargs en los archivos BUILD. En su lugar, enumera todos los argumentos de forma explícita.

Cabe destacar que los programas en Starlark no pueden realizar operaciones de E/S arbitrarias. Esta invariante hace que la interpretación de los archivos BUILD sea hermética y depende solo de un conjunto conocido de entradas, lo que es esencial para garantizar que las compilaciones sean reproducibles. Para obtener más detalles, consulta Hermeticidad.

Los archivos BUILD deben escribirse solo con caracteres ASCII, aunque técnicamente se interpretan con el grupo de caracteres Latin-1.

Por lo general, los archivos BUILD deben actualizarse cada vez que cambian las dependencias del código subyacente, por lo general, varios miembros de un equipo los mantienen. Los autores de archivos BUILD deben hacer comentarios con total libertad para documentar la función de cada destino de compilación, sin importar si es para uso público o no, y para documentar la función del paquete en sí.

Cómo cargar una extensión

Las extensiones de Bazel son archivos que terminan en .bzl. Usa la sentencia load para importar un símbolo desde una extensión.

load("//foo/bar:file.bzl", "some_library")

Este código carga el archivo foo/bar/file.bzl y agrega el símbolo some_library al entorno. Se puede usar para cargar reglas, funciones o constantes nuevas (por ejemplo, una string o una lista). Se pueden importar varios símbolos usando argumentos adicionales a la llamada a load. Los argumentos deben ser literales de string (sin variable) y las declaraciones load deben aparecer en el nivel superior; no pueden estar en el cuerpo de una función.

El primer argumento de load es una etiqueta que identifica un archivo .bzl. Si es una etiqueta relativa, se resuelve con respecto al paquete (no al directorio) que contiene el archivo bzl actual. Las etiquetas relativas en las declaraciones load deben usar un : inicial.

load también admite alias, por lo que puedes asignar nombres diferentes a los símbolos importados.

load("//foo/bar:file.bzl", library_alias = "some_library")

Puedes definir varios alias dentro de una declaración load. Además, la lista de argumentos puede contener alias y nombres de símbolos regulares. El siguiente ejemplo es totalmente legal (ten en cuenta cuándo usar comillas).

load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")

En un archivo .bzl, los símbolos que comienzan con _ no se exportan y no se pueden cargar desde otro archivo.

Puedes usar la visibilidad de la carga para restringir quién puede cargar un archivo .bzl.

Tipos de reglas de compilación

La mayoría de las reglas de compilación vienen en familias, agrupadas por idioma. Por ejemplo, cc_binary, cc_library y cc_test son las reglas de compilación para objetos binarios, bibliotecas y pruebas de C++, respectivamente. Otros lenguajes usan el mismo esquema de nomenclatura, con un prefijo diferente, como java_* para Java. Algunas de estas funciones están documentadas en la Enciclopedia de compilación, pero cualquier persona puede crear reglas nuevas.

  • Las reglas *_binary compilan programas ejecutables en un lenguaje determinado. Después de una compilación, el archivo ejecutable residirá en el árbol de resultados binarios de la herramienta de compilación en el nombre correspondiente de la etiqueta de la regla, por lo que //my:program aparecerá en $(BINDIR)/my/program, por ejemplo.

    En algunos lenguajes, estas reglas también crean un directorio de runfiles que contiene todos los archivos mencionados en un atributo data que pertenece a la regla o cualquier regla en su cierre transitivo de dependencias. Este conjunto de archivos se reúne en un solo lugar para facilitar la implementación en producción.

  • Las reglas *_test son una especialización de una regla *_binary, que se usa para las pruebas automatizadas. Las pruebas son simplemente programas que no muestran ningún resultado con éxito.

    Al igual que los objetos binarios, las pruebas también tienen árboles de archivos de ejecución y los archivos debajo de ellos son los únicos que una prueba puede abrir legítimamente en el tiempo de ejecución. Por ejemplo, es posible que un programa cc_test(name='x', data=['//foo:bar']) se abra y lea $TEST_SRCDIR/workspace/foo/bar durante la ejecución. (Cada lenguaje de programación tiene su propia función de utilidad para acceder al valor de $TEST_SRCDIR, pero todos son equivalentes a usar directamente la variable de entorno). Si no se cumple la regla, la prueba fallará cuando se ejecute en un host de prueba remota.

  • Las reglas *_library especifican módulos compilados por separado en un lenguaje de programación determinado. Las bibliotecas pueden depender de otras bibliotecas, y los objetos binarios y las pruebas pueden depender de las bibliotecas, con el comportamiento esperado de compilación por separado.

Etiquetas Dependencias