Descripción general de la extensión

Informar un problema Ver fuente

En esta página, se describe cómo extender el lenguaje BUILD con macros y reglas.

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

Antes de aprender los conceptos más avanzados, haz lo siguiente:

Macros y reglas

Una macro es una función que crea una instancia de reglas. Resulta útil cuando un archivo BUILD se vuelve demasiado repetitivo o complejo, ya que te permite reutilizar parte del código. La función se evalúa en cuanto se lee el archivo BUILD. Después de la evaluación del archivo BUILD, Bazel tiene poca información sobre las macros: si la macro genera un genrule, Bazel se comportará como si escribieras la genrule. Como resultado, bazel query solo mostrará los genrule generados.

Una regla es más potente que una macro. Puede acceder a los componentes internos de Bazel y tener control total sobre lo que sucede. Por ejemplo, puede pasar información a otras reglas.

Si quieres volver a usar una lógica simple, comienza con una macro. Si una macro se vuelve compleja, suele ser una buena idea convertirla en una regla. La compatibilidad con un idioma nuevo por lo general, se realiza con una regla. Las reglas son para usuarios avanzados, y la mayoría de los usuarios nunca tendrán que escribir una; solo cargarán las reglas existentes y llamarán a ellas.

Modelo de evaluación

Una compilación consta de tres fases.

  • Fase de carga: Primero, carga y evalúa todas las extensiones y todos los archivos BUILD necesarios para la compilación. La ejecución de los archivos BUILD simplemente crea instancias de reglas (cada vez que se llama a una regla, se agrega a un gráfico). Aquí es donde se evalúan las macros.

  • Fase de análisis. Se ejecuta el código de las reglas (su función implementation) y se crean instancias de acciones. Una acción describe cómo generar un conjunto de resultados a partir de un conjunto de entradas, por ejemplo, “ejecutar gcc en hello.c y obtener hello.o”. Debes indicar explícitamente qué archivos se generarán antes de ejecutar los comandos reales. En otras palabras, la fase de análisis toma el gráfico generado por la fase de carga y genera un gráfico de acción.

  • Fase de ejecución: Las acciones se ejecutan cuando se requiere al menos uno de sus resultados. Si falta un archivo o si un comando no puede generar un resultado, la compilación fallará. Las pruebas también se ejecutan durante esta fase.

Bazel usa el paralelismo para leer, analizar y evaluar los archivos .bzl y BUILD. Un archivo se lee, como máximo, una vez por compilación, y el resultado de la evaluación se almacena en caché y se vuelve a usar. Un archivo se evalúa solo una vez que se resuelven todas sus dependencias (sentencias load()). Por diseño, cargar un archivo .bzl no tiene un efecto secundario visible, solo define valores y funciones.

Bazel intenta ser inteligente: usa el análisis de dependencias para saber qué archivos se deben cargar, qué reglas se deben analizar y qué acciones se deben ejecutar. Por ejemplo, si una regla genera acciones que no necesitas para la compilación actual, estas no se ejecutarán.

Cómo crear extensiones

Los dos vínculos que aparecen a continuación te serán muy útiles cuando escribas tus propias extensiones. Mantenlos a tu alcance:

Un paso más allá

Además de macros y reglas, te recomendamos escribir aspectos y reglas de repositorio.