En esta sección, se definen varios términos y conceptos que son comunes a muchas funciones o reglas de compilación.
Contenido
- Tokenización de Bourne shell
- Expansión de etiquetas
- Atributos típicos definidos por la mayoría de las reglas de compilación
- Atributos comunes a todas las reglas de compilación
- Atributos comunes a todas las reglas de prueba (*_test)
- Atributos comunes a todas las reglas binarias (*_binary)
- Atributos configurables
- Objetivos de salida implícitos
Tokenización de Bourne shell
Algunos atributos de cadena de ciertas reglas se dividen en varias palabras según las reglas de tokenización de Bourne Shell: los espacios sin comillas delimitan palabras separadas, y los caracteres de comillas simples y dobles, y las barras inversas se usan para evitar la tokenización.
Los atributos sujetos a esta tokenización se indican explícitamente como tales en sus definiciones en este documento.
Los atributos sujetos a la expansión de la variable "Make" y a la tokenización de Bourne shell se suelen usar para pasar opciones arbitrarias a compiladores y otras herramientas. cc_library.copts y java_library.javacopts son ejemplos de tales atributos.
En conjunto, estas sustituciones permiten que una sola variable de cadena se expanda en una lista de palabras de opciones específicas de la configuración.
Expansión de etiquetas
Algunos atributos de cadena de muy pocas reglas están sujetos a la expansión de etiquetas: si esas cadenas contienen una etiqueta válida como subcadena, como //mypkg:target, y esa etiqueta es un requisito previo declarado de la regla actual, se expande al nombre de ruta de acceso del archivo representado por el destino
//mypkg:target.
Algunos ejemplos de atributos son genrule.cmd y cc_binary.linkopts. Los detalles pueden variar significativamente en cada caso, en relación con temas como si se expanden las etiquetas relativas, cómo se tratan las etiquetas que se expanden a varios archivos, etcétera. Consulta la documentación del atributo de regla para obtener detalles específicos.
Atributos típicos definidos por la mayoría de las reglas de compilación
En esta sección, se describen los atributos que definen muchas reglas de compilación, pero no todas.
| Atributo | Descripción |
|---|---|
data |
Lista de etiquetas. El valor predeterminado es Son los archivos que necesita esta regla durante el tiempo de ejecución. Puede enumerar los destinos de archivos o reglas. Por lo general, permite cualquier objetivo.
Los runfiles y los resultados predeterminados de los destinos en el atributo
Las reglas nuevas deben definir un atributo |
deps |
Lista de etiquetas. El valor predeterminado es
Son las dependencias de este destino. En general, solo debe enumerar los destinos de las reglas. (Aunque algunas reglas permiten que los archivos se muestren directamente en Por lo general, las reglas específicas del idioma limitan los objetivos enumerados a aquellos con proveedores específicos.
La semántica precisa de lo que significa que un destino dependa de otro con
Por lo general, se usa una dependencia |
licenses |
Lista de cadenas; no configurable; el valor predeterminado es Es una lista de cadenas de tipo de licencia que se usarán para este objetivo en particular. Esta es parte de una API de licencias obsoleta que Bazel ya no usa. No uses esta opción. |
srcs |
Lista de etiquetas. El valor predeterminado es
Son los archivos que procesa o incluye esta regla. Por lo general, enumera los archivos directamente, pero puede enumerar los destinos de las reglas (como Las reglas específicas del idioma suelen requerir que los archivos enumerados tengan extensiones de archivo particulares. |
Atributos comunes a todas las reglas de compilación
En esta sección, se describen los atributos que se agregan de forma implícita a todas las reglas de compilación.
| Atributo | Descripción |
|---|---|
aspect_hints |
Lista de etiquetas. El valor predeterminado es Es una lista de etiquetas arbitrarias que se exponen a los aspectos (en particular, a los aspectos invocados por las dependencias inversas de esta regla), pero no se exponen a la implementación propia de esta regla. Consulta la documentación de los conjuntos de reglas específicos del idioma para obtener detalles sobre el efecto que tendría una sugerencia de aspecto en particular. Puedes considerar una sugerencia de aspecto como una alternativa más completa a una etiqueta: mientras que una etiqueta transmite solo un estado booleano (la etiqueta está presente o ausente en la lista de En la práctica, las sugerencias de aspecto se usan para la interoperabilidad entre diferentes conjuntos de reglas específicos del idioma. Por ejemplo, imagina que tienes un destino Para ver un ejemplo concreto, consulta Prácticas recomendadas:
|
compatible_with |
Lista de etiquetas; no configurable; el valor predeterminado es Lista de los entornos para los que se puede compilar este destino, además de los entornos compatibles predeterminados. Esto forma parte del sistema de restricciones de Bazel, que permite a los usuarios declarar qué destinos pueden depender entre sí y cuáles no. Por ejemplo, los archivos binarios que se pueden implementar de forma externa no deben depender de bibliotecas con código secreto de la empresa. Consulta ConstraintSemantics para obtener más detalles. |
deprecation |
Cadena; no configurable; el valor predeterminado es Es un mensaje de advertencia explicativo asociado a este objetivo. Por lo general, se usa para notificar a los usuarios que un destino quedó obsoleto, que otra regla lo reemplazó, que es privado para un paquete o que, tal vez, se considera dañino por algún motivo. Es una buena idea incluir alguna referencia (como una página web, un número de error o CL de migración de ejemplo) para que se pueda averiguar fácilmente qué cambios se requieren para evitar el mensaje. Si hay un nuevo objetivo que se puede usar como reemplazo directo, es una buena idea migrar a todos los usuarios del objetivo anterior.
Este atributo no afecta la forma en que se compilan los elementos, pero puede afectar el resultado de diagnóstico de una herramienta de compilación. La herramienta de compilación emite una advertencia cuando un destino en otro paquete depende de una regla con un atributo Las dependencias dentro del paquete están exentas de esta advertencia, por lo que, por ejemplo, la compilación de las pruebas de una regla obsoleta no genera una advertencia. Si un destino en desuso depende de otro destino en desuso, no se emite ningún mensaje de advertencia. Una vez que las personas dejen de usarlo, se podrá quitar el destino. |
exec_compatible_with |
Lista de etiquetas; no configurable; el valor predeterminado es
Es una lista de |
exec_group_compatible_with |
Diccionario de cadenas para listas de etiquetas; no configurable; el valor predeterminado es
Es un diccionario de nombres de grupos de ejecución y listas de |
exec_properties |
Diccionario de cadenas. El valor predeterminado es Es un diccionario de cadenas que se agregará al Si una clave está presente en las propiedades de la plataforma y del nivel del objetivo, se tomará el valor del objetivo. Las claves pueden tener como prefijo el nombre de un grupo de ejecución seguido de un |
features |
Lista de cadenas de características; el valor predeterminado es Una función es una etiqueta de cadena que se puede habilitar o inhabilitar en un destino. El significado de una función depende de la regla en sí. Este atributo |
package_metadata |
Lista de etiquetas; no se puede configurar; el valor predeterminado es el Es una lista de etiquetas que son metadatos asociados sobre este destino. Por lo general, las etiquetas son reglas simples que devuelven un proveedor de valores constantes. Las reglas y los aspectos pueden usar estas etiquetas para realizar un análisis adicional en el gráfico de compilación.
El caso de uso canónico es el de rules_license.
Para ese caso de uso, se usan |
restricted_to |
Lista de etiquetas; no configurable; el valor predeterminado es Lista de los entornos para los que se puede compilar este destino, en lugar de los entornos compatibles predeterminados.
Esto forma parte del sistema de restricciones de Bazel. Consulta |
tags |
Lista de cadenas; no configurable; el valor predeterminado es
Las etiquetas se pueden usar en cualquier regla. Las etiquetas en las reglas de prueba y
Bazel modifica el comportamiento de su código de zona de pruebas si encuentra las siguientes palabras clave en el atributo
Las etiquetas en las pruebas se suelen usar para anotar el rol de una prueba en el proceso de depuración y lanzamiento. Por lo general, las etiquetas son más útiles para las pruebas de C++ y Python, que no tienen ninguna capacidad de anotación en el tiempo de ejecución. El uso de etiquetas y elementos de tamaño brinda flexibilidad para ensamblar conjuntos de pruebas basados en la política de registro del código base.
Bazel modifica el comportamiento de ejecución de pruebas si encuentra las siguientes palabras clave en el atributo
|
target_compatible_with |
Lista de etiquetas. El valor predeterminado es
Es una lista de Los destinos que dependen de forma transitiva de destinos incompatibles también se consideran incompatibles. También se omiten para la compilación y las pruebas. Una lista vacía (que es el valor predeterminado) indica que el destino es compatible con todas las plataformas.
Todos los parámetros, excepto Workspace Rules, admiten este atributo.
En algunas reglas, este atributo no tiene efecto. Por ejemplo, no es útil especificar
Consulta la página Plataformas para obtener más información sobre el salto de objetivos incompatibles. |
testonly |
Booleano; no configurable; el valor predeterminado es
Si es
De manera equivalente, una regla que no es
Las pruebas (reglas El objetivo de este atributo es indicar que el destino no debe incluirse en los archivos binarios que se lanzan para producción. Dado que testonly se aplica en el momento de la compilación, no en el de la ejecución, y se propaga de forma viral a través del árbol de dependencias, se debe aplicar con prudencia. Por ejemplo, los stubs y los fakes que son útiles para las pruebas de unidades también pueden serlo para las pruebas de integración que involucran los mismos archivos binarios que se lanzarán en producción y, por lo tanto, probablemente no deberían marcarse como testonly. Por el contrario, las reglas que son peligrosas incluso para vincularse, tal vez porque anulan incondicionalmente el comportamiento normal, definitivamente deben marcarse como testonly. |
toolchains |
Lista de etiquetas; no configurable; el valor predeterminado es
Es el conjunto de destinos a los que este destino puede acceder a las variables de compilación. Estos destinos son instancias de reglas que proporcionan
Ten en cuenta que esto es distinto del concepto de resolución de cadenas de herramientas que utilizan las implementaciones de reglas para la configuración dependiente de la plataforma. No puedes usar este atributo para determinar qué |
visibility |
Lista de etiquetas; nonconfigurable; el valor predeterminado varía
El atributo
Para los destinos declarados directamente en un archivo BUILD o en macros heredadas llamadas desde un archivo BUILD, el valor predeterminado es el |
Atributos comunes a todas las reglas de prueba (*_test)
En esta sección, se describen los atributos que son comunes a todas las reglas de prueba.
| Atributo | Descripción | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
Lista de cadenas, sujeta a la sustitución de $(location) y "Make variable", y a la tokenización de Bourne shell; el valor predeterminado es Son los argumentos de línea de comandos que Bazel pasa al destino cuando se ejecuta con
Estos argumentos se pasan antes de cualquier valor de |
||||||||||||||||||||
env |
Diccionario de cadenas. Los valores están sujetos a la sustitución de $(location) y "Make variable". El valor predeterminado es
Especifica variables de entorno adicionales que se deben configurar cuando
Este atributo solo se aplica a las reglas nativas, como |
||||||||||||||||||||
env_inherit |
Lista de cadenas; el valor predeterminado es Especifica variables de entorno adicionales para heredar del entorno externo cuando
Este atributo solo se aplica a las reglas nativas, como |
||||||||||||||||||||
size |
Cadena Especifica la "carga" de un destino de prueba: cuánto tiempo o recursos necesita para ejecutarse. Las pruebas de unidades se consideran "pequeñas", las pruebas de integración "medianas" y las pruebas de extremo a extremo "grandes" o "enormes". Bazel usa el tamaño para determinar un tiempo de espera predeterminado, que se puede anular con el atributo Los tamaños de las pruebas corresponden a los siguientes tiempos de espera predeterminados y usos máximos supuestos de recursos locales:
La variable de entorno |
||||||||||||||||||||
timeout |
Cadena Es el tiempo que se espera que se ejecute la prueba antes de que se muestre el resultado.
Si bien el atributo de tamaño de una prueba controla la estimación de recursos, el tiempo de espera de una prueba se puede establecer de forma independiente. Si no se especifica de forma explícita, el tiempo de espera se basa en el tamaño de la prueba. El tiempo de espera de la prueba se puede anular con la marca
Para otros momentos, el tiempo de espera de la prueba se puede anular con la marca
La variable de entorno |
||||||||||||||||||||
flaky |
Booleano; no se puede configurar; el valor predeterminado es Marca la prueba como inestable. Si se configura, ejecuta la prueba hasta tres veces y la marca como fallida solo si falla cada vez. De forma predeterminada, este atributo se establece en False y la prueba se ejecuta solo una vez. Ten en cuenta que, en general, se desaconseja el uso de este atributo: las pruebas deben aprobarse de manera confiable cuando se mantienen sus aserciones. |
||||||||||||||||||||
shard_count |
Número entero no negativo menor o igual a 50; el valor predeterminado es Especifica la cantidad de fragmentos paralelos que se usarán para ejecutar la prueba. Si se configura, este valor anulará cualquier heurística que se use para determinar la cantidad de fragmentos paralelos con los que se ejecutará la prueba. Ten en cuenta que, para algunas reglas de prueba, este parámetro puede ser obligatorio para habilitar la fragmentación en primer lugar. Consulta también Si la división de pruebas está habilitada, la variable de entorno La fragmentación requiere que el ejecutor de pruebas admita el protocolo de fragmentación de pruebas. Si no es así, es muy probable que se ejecuten todas las pruebas en cada fragmento, lo que no es lo que deseas. Consulta Fragmentación de pruebas en la Enciclopedia de pruebas para obtener detalles sobre la fragmentación. |
||||||||||||||||||||
local |
Booleano; no se puede configurar; el valor predeterminado es Fuerza la ejecución de la prueba de forma local, sin aislamiento. Establecer este valor en verdadero equivale a proporcionar "local" como etiqueta ( |
Atributos comunes a todas las reglas binarias (*_binary)
En esta sección, se describen los atributos que son comunes a todas las reglas binarias.
| Atributo | Descripción |
|---|---|
args |
Lista de cadenas, sujeta a la sustitución de $(location) y "Make variable", y a la tokenización de Bourne shell; no configurable; el valor predeterminado es
Son los argumentos de la línea de comandos que Bazel pasará al destino cuando se ejecute con el comando
NOTA: Los argumentos no se pasan cuando ejecutas el destino fuera de Bazel (por ejemplo, cuando ejecutas manualmente el archivo binario en |
env |
Diccionario de cadenas. Los valores están sujetos a la sustitución de $(location) y "Make variable". El valor predeterminado es Especifica variables de entorno adicionales que se deben configurar cuando
Este atributo solo se aplica a las reglas nativas, como
NOTA: Las variables de entorno no se configuran cuando ejecutas el destino fuera de Bazel (por ejemplo, cuando ejecutas de forma manual el archivo binario en |
output_licenses |
Lista de cadenas; el valor predeterminado es Son las licencias de los archivos de salida que genera este archivo binario. Esta es parte de una API de licencias obsoleta que Bazel ya no usa. No uses esta opción. |
Atributos configurables
La mayoría de los atributos son "configurables", lo que significa que sus valores pueden cambiar cuando el destino se compila de diferentes maneras. Específicamente, los atributos configurables pueden variar según las marcas que se pasen a la línea de comandos de Bazel o la dependencia de nivel inferior que solicite el destino. Esto se puede usar, por ejemplo, para personalizar el destino para múltiples plataformas o modos de compilación.
En el siguiente ejemplo, se declaran diferentes fuentes para diferentes arquitecturas de destino. Ejecutar bazel build :multiplatform_lib --cpu x86 compilará el destino con x86_impl.cc, mientras que sustituir --cpu arm hará que se use arm_impl.cc.
cc_library(
name = "multiplatform_lib",
srcs = select({
":x86_mode": ["x86_impl.cc"],
":arm_mode": ["arm_impl.cc"]
})
)
config_setting(
name = "x86_mode",
values = { "cpu": "x86" }
)
config_setting(
name = "arm_mode",
values = { "cpu": "arm" }
)
La función select() elige entre diferentes valores alternativos para un atributo configurable según los criterios de config_setting o constraint_value que satisfaga la configuración del objetivo.
Bazel evalúa los atributos configurables después de procesar las macros y antes de procesar las reglas (técnicamente, entre las
fases de carga y análisis).
Cualquier procesamiento anterior a la evaluación de select() no sabe qué rama elige select(). Por ejemplo, las macros no pueden cambiar su comportamiento en función de la rama elegida, y bazel query solo puede hacer suposiciones conservadoras sobre las dependencias configurables de un destino. Consulta
estas Preguntas frecuentes para obtener más información sobre el uso de select() con reglas y macros.
Los atributos marcados como nonconfigurable en su documentación no pueden usar esta función. Por lo general, un atributo no se puede configurar porque Bazel necesita saber su valor de forma interna antes de poder determinar cómo resolver un select().
Consulta Configurable Build Attributes para obtener una descripción general detallada.
Objetivos de salida implícitos
Las salidas implícitas en C++ están obsoletas. Si es posible, evita usarlo en otros idiomas. Aún no tenemos una ruta de baja, pero también dejarán de estar disponibles.
Cuando defines una regla de compilación en un archivo BUILD, declaras de forma explícita un destino de regla nuevo con nombre en un paquete. Muchas funciones de reglas de compilación también implican implícitamente uno o más destinos de archivos de salida, cuyo contenido y significado son específicos de la regla.
Por ejemplo, cuando declaras explícitamente una regla java_binary(name='foo', ...), también declaras implícitamente un destino de archivo de salida foo_deploy.jar como miembro del mismo paquete.
(Este destino en particular es un archivo Java autónomo apto para la implementación).
Los destinos de salida implícitos son miembros de primer nivel del gráfico de destino global. Al igual que otros destinos, se compilan a pedido, ya sea cuando se especifican en el comando de compilación de nivel superior o cuando son requisitos previos necesarios para otros destinos de compilación. Se pueden hacer referencia a ellos como dependencias en los archivos BUILD y se pueden observar en el resultado de herramientas de análisis como bazel query.
Para cada tipo de regla de compilación, la documentación de la regla contiene una sección especial en la que se detallan los nombres y el contenido de los resultados implícitos que implica una declaración de ese tipo de regla.
Una distinción importante, pero algo sutil, entre los dos espacios de nombres que usa el sistema de compilación:
Las etiquetas identifican destinos, que pueden ser reglas o archivos, y los destinos de archivos se pueden dividir en destinos de archivos fuente (o de entrada) y destinos de archivos derivados (o de salida). Son los elementos que puedes mencionar en los archivos BUILD, compilar desde la línea de comandos o examinar con bazel query; este es el espacio de nombres del destino. Cada destino de archivo corresponde a un archivo real en el disco (el "espacio de nombres del sistema de archivos"); cada destino de regla puede corresponder a cero, uno o más archivos reales en el disco.
Es posible que haya archivos en el disco que no tengan un destino correspondiente. Por ejemplo, no se puede hacer referencia a los archivos objeto .o producidos durante la compilación de C++ desde los archivos BUILD ni desde la línea de comandos.
De esta manera, la herramienta de compilación puede ocultar ciertos detalles de implementación sobre cómo realiza su trabajo. Esto se explica con más detalle en la Referencia del concepto de BUILD.