Descripción general de la extensión

Denuncia un problema Ver fuente Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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 sentencia de carga para importar un símbolo de una extensión.

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

Macros y reglas

Una macro es una función que crea instancias de reglas. Las macros se presentan en dos versiones: macros simbólicas (nuevas en Bazel 8) y macros heredadas. Los dos tipos de macros se definen de manera diferente, pero se comportan de la misma manera desde el punto de vista de un usuario. Una macro es ú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 tu macro genera una genrule, Bazel se comportará casi como si hubieras declarado esa genrule en el archivo BUILD. (La única excepción es que los destinos declarados en una macro simbólica tienen semántica de visibilidad especial: una macro simbólica puede ocultar sus destinos internos del resto del paquete).

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

Si deseas volver a usar una lógica simple, comienza con una macro. Te recomendamos una macro simbólica, a menos que necesites admitir versiones anteriores de Bazel. Si una macro se vuelve demasiado compleja, a menudo es conveniente convertirla en 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 necesarios para la compilación. La ejecución de los archivos BUILD solo 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 crea una instancia de las acciones. Una acción describe cómo generar un conjunto de resultados a partir de un conjunto de entradas, como "ejecutar gcc en hello.c y obtener 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 grafo de acciones.

  • Fase de ejecución. Las acciones se ejecutan cuando se requiere al menos una de sus salidas. Si falta un archivo o si un comando no genera un resultado, la compilación falla. También se ejecutan pruebas durante esta fase.

Bazel usa el paralelismo para leer, analizar y evaluar los archivos .bzl y BUILD. Se lee un archivo 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 una sola vez una vez que se resuelven todas sus dependencias (sentencias load()). Por diseño, cargar un archivo .bzl no tiene efectos secundarios visibles, 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, no se ejecutarán.

Cómo crear extensiones

Los siguientes dos vínculos te serán muy útiles cuando escribas tus propias extensiones. Manténlos al alcance:

Más información

Además de las macros y las reglas, te recomendamos que escribas aspectos y reglas del repositorio.