Acción
Un comando para ejecutar durante la compilación, por ejemplo, una llamada a un compilador que toma artefactos como entradas y produce otros artefactos como salidas. Incluye metadatos, como los argumentos de línea de comandos, la clave de acción, las variables de entorno y los artefactos de entrada y salida declarados.
Consulta también: Documentación de las reglas
Caché de acciones
Es una caché en el disco que almacena una asignación de las acciones ejecutadas a los resultados que crearon. La clave de caché se conoce como clave de acción. Un componente principal del modelo de incrementalidad de Bazel. La caché se almacena en el directorio base de salida y, por lo tanto, sobrevive a los reinicios del servidor de Bazel.
Gráfico de acciones
Un gráfico en memoria de las acciones y los artefactos que estas acciones leen y generan. El gráfico puede incluir artefactos que existen como archivos fuente (por ejemplo, en el sistema de archivos), así como artefactos intermedios o finales generados que no se mencionan en los archivos BUILD. Se producen durante la fase de análisis y se usan durante la fase de ejecución.
Búsqueda de gráfico de acciones (aquery)
Es una herramienta de consulta que puede consultar las acciones de compilación. Esto permite analizar cómo las reglas de compilación se traducen en las compilaciones de trabajo reales.
Tecla de acción
Es la clave de caché de una acción. Se calcula en función de los metadatos de la acción, que pueden incluir el comando que se ejecutará en la acción, las marcas del compilador, las ubicaciones de la biblioteca o los encabezados del sistema, según la acción. Permite que Bazel almacenen en caché o invaliden acciones individuales de forma determinista.
Fase de análisis
La segunda fase de una compilación. Procesa el gráfico de destino especificado en los archivos BUILD para producir un gráfico de acciones en memoria que determina el orden de las acciones que se ejecutarán durante la fase de ejecución. Esta es la fase en la que se evalúan las implementaciones de reglas.
Artefacto
Un archivo de origen o un archivo generado. También puede ser un directorio de archivos, conocido como artefactos de árbol.
Un artefacto puede ser una entrada para varias acciones, pero solo debe generarse con una acción como máximo.
Un artefacto que corresponde a un objetivo de archivo se puede abordar con una etiqueta.
Aspecto
Es un mecanismo para que las reglas creen acciones adicionales en sus dependencias. Por ejemplo, si el objetivo A depende de B, se puede aplicar un aspecto en A que recorra hacia arriba un borde de dependencia a B y ejecute acciones adicionales en B para generar y recopilar archivos de salida adicionales. Estas acciones adicionales se almacenan en caché y se vuelven a usar entre los objetivos que requieren el mismo aspecto. Se crea con la función aspect() de la API de Starlark Build. Se puede usar, por ejemplo, para generar
metadatos para IDEs y crear acciones para linting.
Ver también: Documentación de aspectos
Aspecto sobre aspecto
Un mecanismo de composición mediante el cual se pueden aplicar aspectos a los resultados de otros aspectos. Por ejemplo, se puede aplicar un aspecto que genera información para que la usen los IDEs sobre un aspecto que genera archivos .java a partir de un proto.
Para que un aspecto A se aplique sobre el aspecto B, los proveedores que B anuncia en su atributo provides deben coincidir con lo que A declara que quiere en su atributo required_aspect_providers.
Atributo
Es un parámetro de una regla que se usa para expresar información de compilación por destino.
Algunos ejemplos son srcs, deps y copts, que declaran, respectivamente, los archivos de origen, las dependencias y las opciones del compilador personalizadas de un destino. Los atributos particulares disponibles para un objetivo determinado dependen de su tipo de regla.
.bazelrc
El archivo de configuración de Bazel se usaba para cambiar los valores predeterminados de las marcas de inicio y las marcas de comando, y para definir grupos comunes de opciones que luego se pueden configurar en la línea de comandos de Bazel con una marca --config. Bazel puede combinar la configuración de varios archivos bazelrc
(en todo el sistema, por espacio de trabajo, por usuario o desde una ubicación personalizada), y un
archivo bazelrc también puede importar la configuración de otros archivos bazelrc.
Blaze
La versión interna de Bazel de Google. El sistema de compilación principal de Google para su monorepositorio.
Archivo BUILD
Un archivo BUILD es el archivo de configuración principal que le indica a Bazel qué resultados de software compilar, cuáles son sus dependencias y cómo compilarlas. Bazel
toma un archivo BUILD como entrada y lo usa para crear un gráfico de dependencias
y derivar las acciones que se deben completar para compilar resultados de software intermedias y finales. Un archivo BUILD marca un directorio y cualquier subdirectorio que no contenga un archivo BUILD como un paquete y puede contener objetivos creados por reglas. El archivo también puede llamarse BUILD.bazel.
Archivo BUILD.bazel
Consulta Archivo BUILD. Tiene prioridad sobre un archivo BUILD en el mismo directorio.
Archivo .bzl
Es un archivo que define reglas, macros y constantes escritas en Starlark. Luego, se pueden importar a archivos BUILD con la función load().
Cómo compilar un gráfico
Es el gráfico de dependencias que Bazel construye y recorre para realizar una compilación. Incluye nodos como objetivos, objetivos configurados, acciones y artefactos. Una compilación se considera completa cuando se verifica que todos los artefactos de los que depende un conjunto de objetivos solicitados están actualizados.
Configuración de compilación
Es un elemento de configuración definido por Starlark. Las transiciones pueden establecer la configuración de compilación para cambiar la configuración de un subgrafo. Si se expone al usuario como una marca de línea de comandos, también conocida como marca de compilación.
Compilación limpia
Una compilación que no usa los resultados de compilaciones anteriores. Por lo general, es más lento que una compilación incremental, pero se considera más correcta. Bazel garantiza que las compilaciones limpias y las incrementales siempre sean correctas.
Modelo cliente-servidor
El cliente de línea de comandos bazel inicia automáticamente un servidor en segundo plano en la
máquina local para ejecutar los comandos de Bazel. El servidor persiste en todos los comandos, pero se detiene automáticamente después de un período de inactividad (o de forma explícita a través del apagado de bazel). Dividir Bazel en un servidor y un cliente ayuda a amortizar el tiempo de inicio de JVM y admite compilaciones incrementales más rápidas, ya que el grafo de acciones permanece en la memoria en todos los comandos.
Comando
Se usa en la línea de comandos para invocar diferentes funciones de Bazel, como bazel
build, bazel test, bazel run y bazel query.
Marcas de comando
Es un conjunto de marcas específicas de un comando. Las marcas de comando se especifican después del comando (bazel build <command flags>). Las marcas se pueden aplicar a uno o más comandos. Por ejemplo, --configure es una marca exclusiva para el comando bazel sync, pero --keep_going se aplica a sync, build, test y mucho más. Las marcas suelen usarse con fines de configuración, por lo que los cambios en sus valores pueden hacer que Bazel invalide los gráficos en memoria y reinicie la fase de análisis.
Configuración
Es la información fuera de las definiciones de reglas que afecta la forma en que las reglas generan acciones. Cada compilación tiene, al menos, una configuración que especifica la plataforma de destino, las variables de entorno de acción y las marcas de compilación de la línea de comandos. Las transiciones pueden crear parámetros de configuración adicionales, como para herramientas de host o compilación cruzada.
Consulta también: Parámetros de configuración
Recorte de configuración
El proceso de incluir solo los elementos de configuración que realmente necesita un objetivo. Por ejemplo, si compilas el objeto binario //:j de Java con la dependencia //:c de C++, es un desperdicio incluir el valor de --javacopt en la configuración de //:c, ya que cambiar --javacopt interrumpe innecesariamente la capacidad de almacenamiento en caché de la compilación de C++.
Consulta configurada (cquery)
Es una herramienta de consulta que consulta los objetivos configurados (después de que se completa la fase de análisis). Esto significa que select() y las marcas de compilación (como --platforms) se reflejan con precisión en los resultados.
Consulta también: Documentación de cquery
Objetivo configurado
Es el resultado de evaluar un objetivo con una configuración. La fase de análisis lo hace combinando las opciones de la compilación con los destinos que se deben compilar.
Por ejemplo, si //:foo compila para dos arquitecturas diferentes en la misma compilación, tiene dos destinos configurados: <//:foo, x86> y <//:foo, arm>.
Precisión
Una compilación es correcta cuando su resultado refleja fielmente el estado de sus entradas transiticas. Para lograr compilaciones correctas, Bazel se esfuerza por ser hermético, reproducible y hacer que el análisis de la compilación y la ejecución de acciones sean deterministas.
Dependencia
Un borde dirigido entre dos objetivos. Un //:foo objetivo tiene una dependencia de destino en el //:bar objetivo si los valores de atributo de //:foo contienen una referencia a //:bar. //:foo tiene una dependencia de acción en //:bar si una acción en //:foo depende de un artefacto de entrada creado por una acción en //:bar.
Depset
Es una estructura de datos para recopilar datos sobre dependencias transitivas. Se optimizaron para que la combinación de conjuntos de dependencias sea eficiente en términos de tiempo y espacio, ya que es común tener conjuntos de dependencias muy grandes (cientos de miles de archivos). Se implementó para hacer referencia de forma recursiva a otros conjuntos de dependencias por motivos de eficiencia espacial. Las implementaciones de reglas no deben "aplanar" los conjuntos de dependencias convirtiéndolos en listas, a menos que la regla esté en el nivel superior del gráfico de compilación. Aplanar conjuntos de dependencias grandes genera un consumo de memoria enorme. También se conocen como conjuntos anidados en la implementación interna de Bazel.
Ver también: Documentación de Depset
Caché del disco
Es un almacén de objetos BLOB en el disco local para la función de almacenamiento en caché remoto. Se puede usar junto con un almacén de blobs remoto real.
Distdir
Es un directorio de solo lectura que contiene archivos que Bazel recuperaría de Internet con las reglas del repositorio. Permite que las compilaciones se ejecuten completamente sin conexión.
Ejecución dinámica
Una estrategia de ejecución que selecciona entre la ejecución local y la remota en función de varias heurísticas y usa los resultados de la ejecución del método más rápido que se realiza correctamente. Algunas acciones se ejecutan más rápido de forma local (por ejemplo, la vinculación) y otras más rápido de forma remota (por ejemplo, la compilación altamente paralelizable). Una estrategia de ejecución dinámica puede proporcionar los mejores tiempos de compilación incrementales y limpios posibles.
Fase de ejecución
Es la tercera fase de una compilación. Ejecuta las acciones en el grafo de acciones creado durante la fase de análisis. Estas acciones invocan ejecutables (compiladores, secuencias de comandos) para leer y escribir artefactos. Las estrategias de creación controlan cómo se ejecutan estas acciones: de forma local, remota, dinámica, en zona de pruebas, en Docker, etcétera.
Raíz de ejecución
Es un directorio en el directorio de base de salida del espacio de trabajo en el que se ejecutan las acciones locales en compilaciones que no están en zona de pruebas. El contenido del directorio son principalmente symlinks de artefactos de entrada del espacio de trabajo. La raíz de ejecución también contiene symlinks a repositorios externos como otras entradas y el directorio bazel-out para almacenar resultados. Se prepara durante la fase de carga mediante la creación de un bosque de vínculos simbólicos de los directorios que representan el cierre transitivo de los paquetes de los que depende una compilación. Se puede acceder a él con bazel info
execution_root en la línea de comandos.
Archivo
Consulta Artefacto.
Hermeticity
Una compilación es hermética si no hay influencias externas en sus operaciones de compilación y prueba, lo que ayuda a garantizar que los resultados sean deterministas y correctos. Por ejemplo, las compilaciones herméticas suelen no permitir el acceso de red a las acciones, restringir el acceso a las entradas declaradas, usar marcas de tiempo y zonas horarias fijas, restringir el acceso a las variables de entorno y usar valores iniciales fijos para los generadores de números aleatorios.
Compilación incremental
Una compilación incremental reutiliza los resultados de compilaciones anteriores para reducir el tiempo de compilación y el uso de recursos. El objetivo de la verificación de dependencias y el almacenamiento en caché es producir resultados correctos para este tipo de compilación. Una compilación incremental es lo opuesto a una compilación limpia.
Etiqueta
Es un identificador para un objetivo. Una etiqueta completamente calificada, como //path/to/package:target, consta de // para marcar el directorio raíz del espacio de trabajo, path/to/package como el directorio que contiene el archivo BUILD que declara el destino y :target como el nombre del destino declarado en el archivo BUILD antes mencionado. También puede tener el prefijo @my_repository//<..> para indicar que el destino se declara en un repositorio externo llamado my_repository.
Fase de carga
Es la primera fase de una compilación en la que Bazel analiza los archivos WORKSPACE, BUILD y .bzl para crear paquetes. En esta fase, se evalúan las macros y ciertas funciones, como glob(). Se intercala con la segunda fase de la compilación, la fase de análisis, para crear un grafo objetivo.
Macro
Un mecanismo para componer varias declaraciones de destino de rule en una sola función Starlark. Permite la reutilización de patrones de declaración de reglas comunes en archivos BUILD. Se expandió a las declaraciones de destino de la regla subyacente durante la fase de carga.
Consulta también: Documentación de macros
Mnemónico
Es una cadena breve y legible por humanos que selecciona el autor de una regla para comprender rápidamente lo que hace una acción en la regla. Los mnemónicos se pueden usar como identificadores para las selecciones de estrategia de creación. Algunos ejemplos de mnemónicos de acción son Javac de las reglas de Java, CppCompile de las reglas de C++ y AndroidManifestMerger de las reglas de Android.
Reglas nativas
Reglas integradas en Bazel y que se implementan en Java. Esas reglas
aparecen en los archivos .bzl como funciones en el módulo nativo (por
ejemplo, native.cc_library o native.java_library). Las reglas definidas por el usuario
(no nativas) se crean con Starlark.
Base de salida
Un directorio específico de Workspace para almacenar archivos de salida de Bazel. Se usa para separar los resultados del árbol de origen del espacio de trabajo. Se encuentra en el usuario raíz de salida.
Grupos de salida
Es un grupo de archivos que se espera que se compilen cuando Bazel termine de compilar un objetivo. Las reglas colocan sus resultados habituales en el "grupo de salida predeterminado" (p. ej., el archivo .jar de un java_library, .a y .so para los objetivos cc_library). El grupo de salida predeterminado es el grupo de salida cuyos artefactos se compilan cuando se solicita un destino en la línea de comandos.
Las reglas pueden definir más grupos de resultados nombrados que se pueden especificar de forma explícita en los archivos BUILD (regla filegroup) o en la línea de comandos (marca --output_groups).
Salida del usuario raíz
Es un directorio específico del usuario para almacenar los resultados de Bazel. El nombre del directorio se deriva del nombre de usuario del sistema del usuario. Evita las colisiones de archivos de salida si varios usuarios compilan el mismo proyecto en el sistema al mismo tiempo. Contiene subdirectorios correspondientes a los resultados de compilación de espacios de trabajo individuales, también conocidos como bases de resultados.
Paquete
Es el conjunto de objetivos definidos por un archivo BUILD. El nombre de un paquete es la ruta de acceso del archivo BUILD en relación con la raíz del espacio de trabajo. Un paquete puede contener subpaquetes o subdirectorios que contienen archivos BUILD, lo que forma una jerarquía de paquetes.
Grupo de paquetes
Un objetivo que representa un conjunto de paquetes. Se suele usar en los valores del atributo visibility.
Plataforma
Un "tipo de máquina" involucrado en una compilación. Esto incluye la máquina en la que se ejecuta Bazel (la plataforma “host”), las máquinas en las que se ejecutan las herramientas de compilación ("plataformas de ejecución") y las máquinas para las que se compilan los destinos ("plataformas de destino").
Proveedor
Un esquema que describe una unidad de información para pasar entre objetivos de reglas a lo largo de las relaciones de dependencia. Por lo general, contiene información como opciones del compilador, archivos de origen o salida transitivos, y metadatos de compilación. Se usa con frecuencia junto con depsets para almacenar de manera eficiente los datos transitivos acumulados. Un ejemplo de un proveedor integrado es DefaultInfo.
Ver también: Documentación del proveedor
Búsqueda (concepto)
Es el proceso de analizar un gráfico de compilación para comprender las propiedades objetivo y las estructuras de dependencias. Bazel admite tres variantes de consulta: query, cquery y aquery.
consulta (comando)
Es una herramienta de consulta que opera en el grafo de destino después de la fase de carga de la compilación. Esto es relativamente rápido,
pero no puede analizar los efectos de select(), las marcas de compilación, los artefactos ni las acciones de compilación.
Consulta también: Instructivo para consultas, Referencia de consultas
Caché del repositorio
Es una caché compartida con direccionamiento de contenido de los archivos que Bazel descarga para las compilaciones, que se puede compartir entre lugares de trabajo. Habilita compilaciones sin conexión después de la descarga inicial. Se usa con frecuencia para almacenar en caché archivos descargados a través de reglas de repositorio como http_archive y APIs de reglas de repositorio como repository_ctx.download. Los archivos se almacenan en caché solo si se especifican sus sumas de comprobación SHA-256 para la descarga.
Reproducibilidad
La propiedad de una compilación o prueba que indica que un conjunto de entradas a la compilación o prueba siempre producirá el mismo conjunto de resultados cada vez, independientemente del tiempo, el método o el entorno. Ten en cuenta que esto no implica necesariamente que los resultados sean correctos o los deseados.
Regla
Un esquema para definir los destinos de las reglas en un archivo BUILD, como cc_library. Desde la perspectiva de un autor de archivos BUILD, una regla consta de un conjunto de atributos y lógica de caja negra. La lógica le indica al objetivo de la regla cómo producir artefactos de salida y pasar información a otros objetivos de reglas. Desde la perspectiva de los autores de .bzl, las reglas son la forma principal de extender Bazel para admitir nuevos lenguajes y entornos de programación.
Se crean instancias de las reglas para producir objetivos de reglas en la fase de carga. En la fase de análisis, los objetivos de reglas comunican información a sus dependencias descendentes en forma de proveedores y registran acciones que describen cómo generar sus artefactos de salida. Estas acciones se ejecutan en la fase de ejecución.
Consulta también: Documentación de las reglas
Objetivo de la regla
Un objetivo que es una instancia de una regla. Contrasta con los destinos de archivos y los grupos de paquetes. No debe confundirse con regla.
Archivos de ejecución
Las dependencias del entorno de ejecución de un destino ejecutable Por lo general, el archivo ejecutable es el resultado ejecutable de una regla de prueba, y los archivos de ejecución son dependencias de datos del entorno de ejecución de la prueba. Antes de la invocación del ejecutable (durante la prueba de Bazel), Bazel prepara el árbol de archivos de ejecución junto con el ejecutable de prueba según su estructura de directorio de origen.
Ver también: Documentación de Runfiles
Zona de pruebas
Es una técnica para aislar una acción en ejecución dentro de una raíz de ejecución restringida y temporal, lo que ayuda a garantizar que no lea entradas no declaradas ni escriba salidas no declaradas. El entorno de pruebas mejora mucho la hermeticidad, pero suele tener un costo de rendimiento y requiere compatibilidad con el sistema operativo. El costo de rendimiento depende de la plataforma. En Linux, no es significativo, pero en macOS puede hacer que la zona de pruebas sea inutilizable.
Skyframe
Skyframe es el framework de evaluación incremental, funcional y en paralelo de Bazel.
Estampado
Es una función para incorporar información adicional en los artefactos compilados con Bazel. Por ejemplo, se puede usar para el control de código fuente, el tiempo de compilación y otra información relacionada con el entorno o el espacio de trabajo para las compilaciones de lanzamiento.
Habilita la marca --workspace_status_command y las reglas que admiten el atributo de sello.
Starlark
Es el lenguaje de extensión para escribir reglas y macros. Un subconjunto restringido de Python (sintáctica y gramaticalmente) destinado a la configuración y a un mejor rendimiento. Usa la extensión de archivo .bzl. Los archivos BUILD usan una versión aún más restringida de Starlark (como no tener definiciones de funciones def), que antes se conocía como Skylark.
Ver también: Documentación del lenguaje Starlark
Marcas de inicio
El conjunto de marcas especificadas entre bazel y el comando, por ejemplo, la compilación de bazel --host_jvm_debug. Estas marcas modifican la configuración del servidor de Bazel, por lo que cualquier modificación de las marcas de inicio hace que se reinicie el servidor. Las marcas de inicio no son específicas de ningún comando.
Objetivo
Es un objeto que se define en un archivo BUILD y se identifica con una etiqueta. Los destinos representan las unidades compilables de un lugar de trabajo desde la perspectiva del usuario final.
Un objetivo que se declara creando una instancia de una regla se denomina objetivo de regla. Según la regla, pueden ser ejecutables (como cc_binary) o comprobables (como cc_test). Los destinos de las reglas suelen depender de otros destinos a través de sus atributos (como deps). Estas dependencias forman la base del gráfico de destino.
Además de los destinos de reglas, también hay destinos de archivos y de grupo de paquetes. Los destinos de archivos corresponden a los artefactos a los que se hace referencia en un archivo BUILD. Como caso especial, el archivo BUILD de cualquier paquete siempre se considera un destino de archivo de origen en ese paquete.
Los destinos se descubren durante la fase de carga. Durante la fase de análisis, los destinos se asocian con parámetros de configuración de compilaciones para formar destinos configurados.
Gráfico de objetivos
Un gráfico en memoria de los objetivos y sus dependencias. Se produce durante la fase de carga y se usa como entrada para la fase de análisis.
Patrón de objetivo
Es una forma de especificar un grupo de objetivos en la línea de comandos. Los patrones que se usan con mayor frecuencia son :all (todos los destinos de la regla), :* (todos los destinos de la regla y del archivo) y ... (el paquete actual y todos los subpaquetes de forma recursiva). Se pueden usar en combinación. Por ejemplo, //...:* significa todos los destinos de reglas y archivos en todos los paquetes de forma recursiva desde la raíz del espacio de trabajo.
Pruebas
Los objetivos de las reglas se crean a partir de reglas de prueba y, por lo tanto, contienen un ejecutable de prueba. Un código devuelto de cero al final del ejecutable indica que la prueba se realizó correctamente. El contrato exacto entre Bazel y las pruebas (como las variables de entorno de prueba, los métodos de recopilación de resultados de prueba) se especifica en la Enciclopedia de pruebas.
Cadena de herramientas
Un conjunto de herramientas para compilar resultados para un lenguaje. Por lo general, una cadena de herramientas incluye compiladores, vinculadores, intérpretes o linters. Una cadena de herramientas también puede variar según la plataforma, es decir, los componentes de una cadena de herramientas de compilador de Unix pueden diferir para la variante de Windows, aunque la cadena de herramientas sea para el mismo lenguaje. La selección de la cadena de herramientas adecuada para la plataforma se conoce como resolución de cadena de herramientas.
Objetivo de nivel superior
Un destino de compilación es de nivel superior si se solicita en la línea de comandos de Bazel. Por ejemplo, si //:foo depende de //:bar y se llama a bazel build //:foo, para esta compilación, //:foo es de nivel superior y //:bar no lo es, aunque se deberán compilar ambos destinos. Una diferencia importante entre los destinos de nivel superior y los que no son de nivel superior es que las marcas de comando establecidas en la línea de comandos de Bazel (o a través de .bazelrc) establecerán la configuración para los destinos de nivel superior, pero pueden modificarse con una transición para los destinos que no son de nivel superior.
Transición
Es una asignación del estado de configuración de un valor a otro. Permite que los destinos en el gráfico de compilación tengan configuraciones diferentes, incluso si se crearon instancias a partir de la misma regla. Un uso común de las transiciones es con las transiciones divididas, en las que ciertas partes del grafo objetivo se bifurcan con configuraciones distintas para cada bifurcación. Por ejemplo, se puede compilar un APK para Android con objetos binarios nativos compilados para ARM y x86 con transiciones divididas en una sola compilación.
Consulta también: Transiciones definidas por el usuario
Artefacto de árbol
Un artefacto que representa una colección de archivos. Dado que estos archivos no son artefactos, una acción que opere en ellos debe registrar el artefacto del árbol como su entrada o salida.
Visibilidad
Es uno de los dos mecanismos para evitar dependencias no deseadas en el sistema de compilación: visibilidad del destino para controlar si otros destinos pueden depender de un destino, y visibilidad de carga para controlar si un archivo BUILD o .bzl puede cargar un archivo .bzl determinado. Sin contexto, por lo general,
"visibilidad" se refiere a la visibilidad del objetivo.
Ver también: Documentación de visibilidad
Workspace
Un directorio que contiene un archivo WORKSPACE y el código fuente del software que quieres compilar. Las etiquetas que comienzan con // son relativas al directorio del espacio de trabajo.
Archivo WORKSPACE
Define un directorio como un espacio de trabajo. El archivo puede estar vacío, aunque suele contener declaraciones de repositorios externos para recuperar dependencias adicionales de la red o el sistema de archivos local.