En las secciones anteriores, se describieron los paquetes, los destinos y las etiquetas, y el gráfico de dependencias de compilación de forma 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 mediante Starlark, un lenguaje imperativo.
Se interpretan como una lista secuencial de instrucciones.
En general, el orden sí importa: por ejemplo, las variables deben definirse antes de que se usen. Sin embargo, la mayoría de los archivos BUILD solo consisten en declaraciones de reglas de compilación, y el orden relativo de estas instrucciones es irrelevante. Lo único que importa es qué reglas se declararon y con qué valores, cuando se completa 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 grafo. Más adelante, se puede hacer referencia a este objetivo con una etiqueta.
En archivos BUILD simples, las declaraciones de reglas se pueden reordenar libremente sin
cambiar el comportamiento.
Para fomentar una separación clara entre el código y los datos, los archivos BUILD no pueden contener definiciones de funciones, sentencias for ni sentencias if (pero se permiten las comprensiones de listas y las expresiones if). En su lugar, se pueden declarar funciones en archivos .bzl. Además, los argumentos *args y **kwargs no se permiten en los archivos BUILD. En su lugar, enumera todos los argumentos de forma explícita.
Es fundamental que los programas en Starlark no puedan realizar E/S arbitrarias. Esta invariante hace que la interpretación de los archivos BUILD sea hermética, es decir, depende solo de un conjunto de entradas conocido, lo cual es esencial para garantizar que las compilaciones sean reproducibles.
Para obtener más detalles, consulta Hermeticity.
Los archivos BUILD deben escribirse solo con caracteres ASCII, aunque, técnicamente, se interpretan con el conjunto de caracteres Latin-1.
Debido a que los archivos BUILD deben actualizarse cada vez que cambian las dependencias del código subyacente, por lo general, varias personas de un equipo los mantienen. Los autores de archivos BUILD deben hacer comentarios de forma generosa para documentar el rol de cada objetivo de compilación, ya sea que esté destinado o no para uso público, y para documentar el rol del paquete en sí.
Carga 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 cadena o una lista). Se pueden importar varios símbolos con argumentos adicionales a la llamada a load. Los argumentos deben ser cadenas literales (sin variables) y las sentencias 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 en relación con el paquete (no el directorio) que contiene el archivo bzl actual. Las etiquetas relativas en las declaraciones load deben usar una : inicial.
load también admite alias; por lo tanto, 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 sola sentencia load. Además, la lista de argumentos puede contener alias y nombres de símbolos normales. El siguiente ejemplo es perfectamente 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 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
lenguaje. 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 nombres, con un prefijo diferente, como java_* para Java. Algunas de estas funciones se documentan en la Enciclopedia de compilación, pero cualquier persona puede crear reglas nuevas.
Las reglas
*_binarycompilan programas ejecutables en un lenguaje determinado. Después de una compilación, el 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:programaparecerá en (por ejemplo)$(BINDIR)/my/program.En algunos lenguajes, esas reglas también crean un directorio de archivos de ejecución que contiene todos los archivos mencionados en un atributo
dataque pertenece a la regla o cualquier regla en el cierre transitivo de las dependencias. Este conjunto de archivos se reúne en un solo lugar para facilitar la implementación en producción.Las reglas
*_testson una especialización de una regla*_binaryque se usa para pruebas automáticas. Las pruebas son simplemente programas que muestran cero cuando se realizan correctamente.Al igual que los objetos binarios, las pruebas también tienen árboles de runfiles, y los archivos debajo de ellos son los únicos que una prueba puede abrir legítimamente durante el tiempo de ejecución. Por ejemplo, un programa
cc_test(name='x', data=['//foo:bar'])puede abrir y leer$TEST_SRCDIR/workspace/foo/bardurante 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 la variable de entorno directamente). Si no se observa la regla, la prueba fallará cuando se ejecute en un host de prueba remoto.Las reglas
*_libraryespecifican módulos compilados por separado en el 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 independiente.
| Etiquetas | Dependencias |