En esta sección, se definen varios términos y conceptos comunes a muchas funciones o reglas de compilación.
Contenido
- Asignación de token de shell de Bourne
- 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 shell de Bourne
Ciertos atributos de string de algunas reglas se dividen en varias palabras de acuerdo con las reglas de asignación de tokens de la shell de Bourne: los espacios sin comillas delimitan las palabras separadas, y se usan caracteres de comillas simples y dobles, y barras inversas para evitar la asignación de token.
Aquellos atributos sujetos a esta asignación de token se indican explícitamente como tales en sus definiciones en este documento.
Los atributos sujetos a la expansión de variables "Make" y la tokenización de shell de Bourne suelen usarse para pasar opciones arbitrarias a compiladores y otras herramientas. cc_library.copts y java_library.javacopts son ejemplos de esos atributos.
En conjunto, estas sustituciones permiten que una sola variable de string se expanda en una lista de palabras de opción específica 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 en la ruta de acceso del archivo representado por el //mypkg:target objetivo.
Algunos ejemplos de atributos son genrule.cmd y cc_binary.linkopts. Los detalles pueden variar de forma significativa en cada caso, en función de cuestiones 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 de los atributos de reglas para obtener información específica.
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 |
Es una lista de etiquetas. El valor predeterminado es Archivos que necesita esta regla en el tiempo de ejecución. Puede enumerar objetivos de archivos o reglas. Por lo general, permite cualquier objetivo.
Las salidas y los archivos de ejecución predeterminados de los objetivos en el atributo
Las reglas nuevas deben definir un atributo |
deps |
Es una lista de etiquetas. El valor predeterminado es
Dependencias para este objetivo. Por lo general, solo debe enumerar los objetivos de la regla. (Aunque algunas reglas permiten que los archivos se enumeren directamente en Por lo general, las reglas específicas de un 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 mediante
Por lo general, se usa una dependencia |
licenses |
Es una lista de cadenas no configurable. El valor predeterminado es Una lista de cadenas de tipo de licencia que se usarán para este objetivo en particular. Esto forma parte de una API de licencias obsoleta que Bazel ya no usa. No la uses. |
srcs |
Es una lista de etiquetas. El valor predeterminado es
Archivos procesados o incluidos por esta regla. Por lo general, enumera los archivos de forma directa, pero puede enumerar los objetivos de las reglas (como Las reglas específicas de un lenguaje a menudo requieren que los archivos en la lista 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 |
|---|---|
compatible_with |
Es una lista de etiquetas no configurables. El valor predeterminado es Es la lista de entornos para los que se puede compilar este destino, además de los entornos compatibles de forma predeterminada. Esto es parte del sistema de restricciones de Bazel, que permite a los usuarios declarar qué destinos pueden depender unos de otros y cuáles no. Por ejemplo, los objetos binarios implementables de forma externa no deben depender de bibliotecas con código secreto de la empresa. Consulta ConstraintSemantics para obtener más detalles. |
deprecation |
String; no configurable; el valor predeterminado es Un mensaje de advertencia explicativo asociado a este destino. Por lo general, se usa para notificar a los usuarios que un destino se volvió obsoleto, que se reemplazó por otra regla, que es privado de un paquete o que 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 ejemplos de CL de migración) para que se pueda averiguar con facilidad qué cambios se requieren para evitar el mensaje. Si hay un objetivo nuevo que se puede usar como reemplazo directo, es una buena idea migrar a todos los usuarios del objetivo anterior.
Este atributo no tiene efecto en la forma en que se compilan, pero puede afectar el resultado de diagnóstico de una herramienta de compilación. La herramienta de compilación emite una advertencia cuando una regla con un atributo Las dependencias dentro del paquete están exentas de esta advertencia, por lo que, por ejemplo, cuando se compilan las pruebas de una regla obsoleta, no aparece una advertencia. Si un objetivo obsoleto depende de otro objetivo obsoleto, no se emite ningún mensaje de advertencia. Una vez que las personas dejen de usarlo, se puede quitar el objetivo. |
distribs |
Lista de cadenas; no configurable; el valor predeterminado es Es una lista de cadenas de métodos de distribución que se usarán para este objetivo en particular. Esto forma parte de una API de licencias obsoleta que Bazel ya no usa. No la uses. |
exec_compatible_with |
Es una lista de etiquetas no configurables. El valor predeterminado es
Una lista de |
exec_properties |
Diccionario de cadenas; el valor predeterminado es Un diccionario de cadenas que se agregará a Si una clave está presente en las propiedades de nivel de destino y de la plataforma, el valor se tomará del destino. |
features |
Es una lista de cadenas de feature. El valor predeterminado es Una función es una etiqueta de cadena que se puede habilitar o inhabilitar en un destino. El significado de un atributo depende de la regla misma. Este atributo |
restricted_to |
Es una lista de etiquetas no configurables. El valor predeterminado es Es la lista de entornos para los que se puede compilar este destino, en lugar de los entornos compatibles de forma predeterminada.
Esto forma parte del sistema de restricciones de Bazel. Consulta |
tags |
Es una lista de cadenas no configurable. El valor predeterminado es
Las etiquetas se pueden usar en cualquier regla. Las etiquetas en las pruebas y las reglas
Bazel modifica el comportamiento de su código de zona de pruebas si encuentra las siguientes palabras clave en el atributo
Por lo general, las etiquetas en las pruebas se usan 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 carecen de cualquier capacidad de anotación del entorno de ejecución. El uso de etiquetas y elementos de tamaño brinda flexibilidad para organizar conjuntos de pruebas en función de la política de registro de la base de código.
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 (predeterminada) significa que el destino es compatible con todas las plataformas.
Todas las reglas, excepto las reglas de Workspace, 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 la omisión de objetivos incompatibles. |
testonly |
Booleano, no configurable; la configuración predeterminada es
Si es
De manera equivalente, una regla que no sea
Las pruebas (reglas El propósito de este atributo es significar que el destino no debe estar contenido en objetos binarios que se lanzan para producción. Debido a que testonly se aplica en el tiempo de compilación, no en el tiempo de ejecución, y se propaga de forma viral a través del árbol de dependencia, debe aplicarse de manera juiciosa. Por ejemplo, los stubs y los objetos falsos que son útiles para las pruebas de unidades también pueden ser útiles para las pruebas de integración que involucran los mismos objetos binarios que se lanzarán a producción y, por lo tanto, es probable que no deban marcarse como testonly. Por el contrario, las reglas que son peligrosas incluso para vincular, quizás porque anulan de forma incondicional el comportamiento normal, deben marcarse como solo para pruebas. |
toolchains |
Es una lista de etiquetas no configurables. El valor predeterminado es
Es el conjunto de destinos a cuyas variables de Make puede acceder este destino. Estos destinos son instancias de reglas que proporcionan
Ten en cuenta que esto es distinto del concepto de resolución de cadena de herramientas que usan las implementaciones de reglas para la configuración dependiente de la plataforma. No puedes usar este atributo para determinar qué |
visibility |
Es una lista de etiquetas; no se puede configurar; el valor predeterminado es
El atributo |
Atributos comunes a todas las reglas de prueba (*_test)
En esta sección, se describen los atributos comunes a todas las reglas de prueba.
| Atributo | Descripción | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
Es una 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 las variables de entorno adicionales que se heredarán del entorno externo cuando
Este atributo solo se aplica a las reglas nativas, como |
||||||||||||||||||||
size |
String Especifica la “pesura” de un objetivo de prueba, es decir, 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 prueba corresponden a los siguientes tiempos de espera predeterminados y a los usos máximos de recursos locales considerados:
La variable de entorno |
||||||||||||||||||||
timeout |
String Es la cantidad de 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 puede establecerse 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
En otros momentos, el tiempo de espera de la prueba se puede anular con la
marca de Bazel La variable de entorno |
||||||||||||||||||||
flaky |
Booleano; no configurable; el valor predeterminado es Marca la prueba como inestable. Si se establece, 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, por lo general, no se recomienda el uso de este atributo. Las pruebas deben aprobarse de forma confiable cuando se confirman sus aserciones. |
||||||||||||||||||||
shard_count |
Número entero no negativo menor o igual que 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 usada para determinar la cantidad de fragmentos paralelos con los que se ejecutará la prueba. Ten en cuenta que, para algunas reglas de prueba, es posible que se requiera este parámetro para habilitar el fragmentación en primer lugar. Consulta también Si la fragmentació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 prueba. De lo contrario, es probable que ejecute todas las pruebas en cada fragmento, lo que no es lo que deseas. Consulta Fragmentación de pruebas en la enciclopedia de prueba para obtener detalles sobre la fragmentación. |
||||||||||||||||||||
local |
Booleano; no configurable; el valor predeterminado es Fuerza que la prueba se ejecute de forma local, sin zona de pruebas. Establecer este valor en "true" equivale a proporcionar "local" como etiqueta ( |
Atributos comunes a todas las reglas binarias (*_binary)
En esta sección, se describen los atributos comunes a todas las reglas binarias.
| Atributo | Descripción |
|---|---|
args |
Lista de cadenas; sujeta a la sustitución
$(location) y
"Make variable", y
la asignación de token de shell de Bourne;
no configurable;
el valor predeterminado es
Son los argumentos de 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, si ejecutas el objeto binario en
|
env |
Diccionario de cadenas; los valores están sujetos a la sustitución $(location) y "Make variable"; el valor predeterminado es Especifica las variables de entorno adicionales que se deben configurar cuando
Este atributo solo se aplica a reglas nativas, como
NOTA: Las variables de entorno no se configuran cuando ejecutas el destino
fuera de Bazel (por ejemplo, si ejecutas el objeto binario en
|
output_licenses |
Es una lista de cadenas. El valor predeterminado es Las licencias de los archivos de salida que genera este binario Esto forma parte de una API de licencias obsoleta que Bazel ya no usa. No la uses. |
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 pasan a la línea de comandos de Bazel o la dependencia descendente que solicita el destino. Esto se puede usar, por ejemplo, para personalizar el destino para varias plataformas o modos de compilación.
En el siguiente ejemplo, se declaran diferentes fuentes para distintas arquitecturas de destino. La ejecución de bazel build :multiplatform_lib --cpu x86 compilará el destino con x86_impl.cc, mientras que, si se sustituye --cpu arm, se usará 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 satisface 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 previo a la evaluación de select() no sabe qué rama elige la select(). Por ejemplo, las macros no pueden cambiar su comportamiento en función de la rama elegida, y bazel query solo puede hacer conjeturas conservadoras sobre las dependencias configurables de un objetivo. 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 conocer su valor de forma interna para poder determinar cómo resolver un
select().
Consulta Atributos de compilación configurables para obtener una descripción general detallada.
Objetivos de salida implícitos
Los resultados implícitos en C++ dejaron de estar disponibles. Evita usarlo en otros idiomas siempre que sea posible. Aún no tenemos una ruta de baja, pero con el tiempo también quedarán obsoletas.
Cuando defines una regla de compilación en un archivo BUILD, declaras de forma explícita
un nuevo destino de regla con nombre en un paquete. Muchas funciones de la regla de compilación también implícitamente implican uno o más destinos de archivo 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 de forma implícita un archivo de salida de destino foo_deploy.jar como miembro del mismo paquete.
(Este destino particular es un archivo Java autónomo adecuado para la implementación).
Los destinos de salida implícitos son miembros de primera clase 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 puede hacer referencia a ellos como dependencias en archivos BUILD y se pueden observar en el resultado de las 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 los objetivos, que pueden ser reglas o archivos, y los objetivos de archivo se pueden dividir en objetivos de archivo de origen (o entrada) y objetivos de archivo derivados (o salida). Estos 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 de 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 el destino correspondiente. Por ejemplo, no se puede hacer referencia a los archivos de objetos .o que se producen 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 relacionados con su trabajo. Esto se explica con más detalle en la Referencia de conceptos de BUILD.