En las secciones anteriores, se describían paquetes, destinos y etiquetas, y el gráfico de dependencia 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 un lenguaje imperativo, Starlark.
Se interpretan como una lista secuencial de declaraciones.
En general, el orden sí importa: las variables deben definirse antes de usarse, por ejemplo. Sin embargo, la mayoría de los archivos BUILD
solo consisten en declaraciones de reglas de compilación, y el orden relativo de estas declaraciones es inmaterial. Lo único que importa es cuáles son las reglas declaradas 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. Este destino se puede referir más tarde con una etiqueta.
En archivos BUILD
simples, las declaraciones de reglas se pueden reordenar libremente sin cambiar el comportamiento.
Para fomentar una separación limpia entre el código y los datos, los archivos BUILD
no pueden contener definiciones de funciones, declaraciones for
ni sentencias if
(pero se permiten las listas y las expresiones if
). En su lugar, se pueden declarar funciones en archivos .bzl
. Además, no se permiten los argumentos *args
ni **kwargs
en los archivos BUILD
. En su lugar, enumera todos los argumentos de forma explícita.
Cabe destacar que los programas de Starlark no pueden realizar E/S arbitrarias. Esta variante hace que la interpretación de los archivos BUILD
sea hermética, ya que 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
se deben escribir solo con caracteres ASCII, aunque técnicamente se interpretan con el grupo de caracteres Latin-1.
Debido a que los archivos BUILD
deben actualizarse siempre que cambien las dependencias del código subyacente, varias personas de un equipo las mantienen. Los autores de archivos BUILD
deben comentar con libertad para documentar la función de cada destino de compilación, sin importar si está destinado al uso público, y documentar la función del paquete.
Cargando una extensión
Las extensiones de Bazel son archivos que terminan en .bzl
. Usa la sentencia load
para importar un símbolo de 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. Esto se puede usar para cargar reglas, funciones o constantes nuevas (por ejemplo, una string o una lista). Se pueden importar varios símbolos mediante argumentos adicionales a la llamada a load
. Los argumentos deben ser literales de string (sin variables) 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 diferentes nombres a los símbolos importados.
load("//foo/bar:file.bzl", library_alias = "some_library")
Puedes definir varios alias dentro de una instrucción load
. Además, la lista de argumentos puede contener alias y nombres de símbolos regulares. El siguiente ejemplo es completamente 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 familia, 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 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 ejecutable residirá en el árbol de resultados binarios de la herramienta de compilación en el nombre correspondiente para la etiqueta de la regla, por lo que//my:program
aparecerá en (por ejemplo)$(BINDIR)/my/program
.En algunos lenguajes, esas reglas también crean un directorio de archivos runrun 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 recopila 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 pruebas automatizadas. Las pruebas son simplemente programas que no muestran ningún resultado exitoso.Al igual que los objetos binarios, las pruebas también tienen árboles de archivos de ejecución, y los únicos archivos que una prueba puede abrir de forma legítima 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/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 todas equivalen a usar la variable de entorno directamente). Si no respetas la regla, la prueba fallará cuando se ejecute en un host de prueba remota.Las reglas
*_library
especifican módulos compilados por separado en el lenguaje de programación determinado. Las bibliotecas pueden depender de otras, y los objetos binarios y las pruebas pueden depender de bibliotecas, con el comportamiento esperado de compilación separada.
Etiquetas | Dependencias |