En esta página, se describe cómo extender el lenguaje de COMPILACIÓN 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 de una extensión.
Antes de aprender los conceptos más avanzados, haz lo siguiente:
Obtén información sobre el lenguaje Starlark, que se usa en los archivos
BUILD
y.bzl
.Obtén información sobre cómo compartir variables entre dos archivos
BUILD
.
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 algún código. La función se evalúa en cuanto se lee el archivo BUILD
. Después de
evaluar el archivo BUILD
, Bazel tiene poca información sobre las macros:
si la macro genera una genrule
, Bazel se comportará como si escribieras la
genrule
. Como resultado, bazel query
solo mostrará las genrule
generadas.
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 reutilizar la lógica simple, comienza con una macro. Si una macro se vuelve compleja, suele ser una buena idea establecerla como una regla. La compatibilidad con un idioma nuevo suele realizarse 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 y llamarán a las reglas existentes.
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
que se necesitan para la compilación. La ejecución de los archivosBUILD
simplemente crea una instancia de reglas (cada vez que se llama a una regla, esta se agrega a un grafo). 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 las acciones. Una acción describe cómo generar un conjunto de resultados a partir de un conjunto de entradas, como "run gcc on hello.c and get hello.o". Debes enumerar de forma explícita qué archivos se generarán antes de ejecutar los comandos reales. En otras palabras, la fase de análisis toma el grafo generado por la fase de carga y genera un gráfico de acciones.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 falla. 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, la carga de 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 deben ejecutarse. Por ejemplo, si una regla genera acciones que no necesitas para la compilación actual, no se ejecutarán.
Cómo crear extensiones
Crea tu primera macro para reutilizar parte del código. Luego, obtén más información sobre las macros y cómo usarlas para crear "verbos personalizados".
Sigue el instructivo de reglas para comenzar a usar reglas. A continuación, puedes leer más sobre los conceptos de reglas.
Los dos vínculos que aparecen a continuación te resultará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.
Usa Buildifier de manera coherente para formatear y analizar tu código con lint.
Sigue la guía de estilo de
.bzl
.Prueba el código.
Genera documentación para ayudar a los usuarios.
Optimiza el rendimiento de tu código.
Implementa tus extensiones para otras personas.