Archivos BUILD

En las secciones anteriores, se describieron paquetes, objetivos y etiquetas, y las compilar el gráfico de dependencias 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 . Los archivos BUILD se evalúan usando un lenguaje imperativo. Starlark.

Se interpretan como una lista secuencial de declaraciones.

En general, el orden sí importa: las variables se deben definir antes de usarse, por ejemplo. Sin embargo, la mayoría de los archivos BUILD consisten solo en declaraciones de reglas de construcción y el orden relativo de estas instrucciones es inmaterial; todas que importa es qué reglas declaradas, y con qué valores, de tiempo de ejecución de la evaluación del paquete.

Cuando se ejecuta una función de regla de compilación, como cc_library, crea un nuevo objetivo en el gráfico. Más adelante, se puede hacer referencia a este destino 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 contienen definiciones de funciones, sentencias for o if (pero las se permiten la comprensión y las expresiones if). Las funciones se pueden declarar en .bzl en su lugar. Además, los argumentos *args y **kwargs no permitido 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 operaciones de E/S arbitrarias. Este invariante hace que la interpretación de los archivos BUILD sea hermética, es decir, depende solo de un archivo conjunto de entradas, 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 grupo de caracteres Latin-1.

Debido a que los archivos BUILD deben actualizarse siempre que las dependencias de la cambio de código subyacente, por lo general, son mantenidas por varias personas en un equipo. Los autores de archivos BUILD deben comentar libremente para documentar el rol. de cada objetivo de compilación, sin importar si está destinado o no para el uso público, y documentar el rol del paquete.

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 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 con el medioambiente. Se puede usar para cargar nuevas reglas, funciones o constantes (por ejemplo, una cadena o una lista). Se pueden importar varios símbolos argumentos adicionales a la llamada a load. Los argumentos deben ser literales de cadena (sin variable) y las sentencias load deben aparecer en el nivel superior; no pueden en el cuerpo de una función.

El primer argumento de load es una etiqueta que identifica una .bzl. Si es una etiqueta relativa, se resuelve con respecto a la Paquete (no directorio) que contiene el archivo bzl actual. Etiquetas relativas en Las sentencias load deben usar una : inicial.

load también admite alias; por lo tanto, puedes asignar nombres diferentes al símbolos importados.

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

Puedes definir varios alias dentro de una sentencia load. Además, el puede contener tanto alias como nombres de símbolos regulares. Lo siguiente ejemplo es perfectamente legal (ten en cuenta cuándo utilizar 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 cargado desde otro archivo.

Puedes usar la visibilidad de la carga para restringir que 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 los objetos binarios de C++, bibliotecas y pruebas, respectivamente. En otros idiomas se usa lo mismo. esquema de nombres, con un prefijo diferente, como java_* para Java Algunas de estas funciones se documentan en el Compilar Enciclopedia, pero es posible para que cualquiera cree reglas nuevas.

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

  En algunos lenguajes, esas reglas también crean un directorio de archivos runfiles. que contenga todos los archivos mencionados en un data atributo que pertenece a la regla, o cualquier regla en su el cierre de dependencias; este conjunto de archivos se junta en 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 y pruebas. Las pruebas son simplemente programas que no devuelven resultados en caso de éxito.

  Al igual que los objetos binarios, las pruebas también tienen árboles de archivos runfiles, y los archivos debajo están los únicos archivos que una prueba puede abrir legítimamente durante el tiempo de ejecución. Por ejemplo, un programa cc_test(name='x', data=['//foo:bar']) podría 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 accediendo al valor de $TEST_SRCDIR, pero todas equivale a usar directamente la variable de entorno) Si no se cumple la regla, la prueba fallará cuando sea se ejecuta en un host de prueba remoto.

• Las reglas *_library especifican módulos compilados por separado en la de programación centrado en los datos. Las bibliotecas pueden depender de otras bibliotecas, y los objetos binarios y las pruebas pueden depender de bibliotecas, con la capacidad de compilación separada.