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 la shell 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 resultado implícitos
Asignación de token de shell Bourne
Ciertos atributos de string de algunas reglas se dividen en varias palabras de acuerdo con las reglas de asignación de token de la shell Bourne: los espacios sin comillas delimitan palabras separadas, y se usan comillas simples y dobles y barras inversas para evitar la asignación de token.
Los atributos que están sujetos a esta asignación de token se indican de manera explícita como tales en sus definiciones de este documento.
Por lo general, los atributos sujetos a la expansión de variable "Make" y la asignación de token de shell Bourne se usan para pasar opciones arbitrarias a compiladores y otras herramientas. Algunos ejemplos de estos atributos son cc_library.copts y java_library.javacopts.
En conjunto, estas sustituciones permiten que una sola variable de string se expanda a una lista de palabras opciones específicas de la configuración.
Expansión de etiquetas
Algunos atributos de string de muy pocas reglas están sujetos a la expansión de etiquetas. Si esas strings contienen una etiqueta válida como substring, como //mypkg:target, y esa etiqueta es un requisito previo declarado de la regla actual, se expande al nombre de la ruta de acceso del archivo representado por el //mypkg:target de destino.
Los atributos de ejemplo incluyen genrule.cmd y cc_binary.linkopts. Los detalles pueden variar de manera significativa en cada caso, por ejemplo, si se expanden las etiquetas relativas, cómo se tratan las etiquetas que se expanden a varios archivos, etc. Consulta la documentación de 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 definidos por muchas reglas de compilación, pero no por todas.
| Atributo | Descripción |
|---|---|
data |
Archivos que necesita esta regla en el tiempo de ejecución. Puede enumerar objetivos de archivos o reglas. Generalmente, permite cualquier destino.
Los resultados y los archivos de ejecución predeterminados de los objetivos del atributo
Las reglas nuevas deben definir un atributo |
deps |
Dependencias de este destino. 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 para un idioma limitan los objetivos enumerados a aquellos con proveedores específicos.
La semántica precisa de lo que significa que un objetivo dependa de otro mediante
En la mayoría de los casos, se usa una dependencia |
licenses |
Una lista de cadenas de tipo de licencia que se usarán para este destino en particular. Esto forma parte de una API de licencias obsoleta que Bazel ya no usa. No la uses. |
srcs |
Archivos procesados o incluidos por esta regla. Por lo general, enumera los archivos directamente, pero
puede enumerar los objetivos de la regla (como Las reglas específicas para cada lenguaje a menudo requieren que los archivos de 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 manera implícita a todas las reglas de compilación.
| Atributo | Descripción |
|---|---|
compatible_with |
La lista de entornos para los que se puede compilar este destino, además de los entornos compatibles de forma predeterminada. Esto forma parte del sistema de restricciones de Bazel, que permite a los usuarios declarar qué destinos pueden y no pueden depender unos de otros. Por ejemplo, los objetos binarios que se pueden implementar de forma externa no deberían depender de bibliotecas con código secreto de la empresa. Consulta ConstraintSemantics para obtener más información. |
deprecation |
Un mensaje de advertencia explicativo asociado con este destino. Por lo general, se usa para notificar a los usuarios que un objetivo se volvió obsoleto, o que fue sustituido por otra regla, que es privado de un paquete o que tal vez se considera perjudicial 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 puedas descubrir con facilidad qué cambios se requieren para evitar el mensaje. Si hay un destino nuevo que se puede usar como reemplazo gradual, se recomienda migrar a todos los usuarios del destino anterior.
Este atributo no influye en la forma en que se compilan los elementos, pero puede afectar el resultado del 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, de modo que, por ejemplo, compilar las pruebas de una regla obsoleta no encuentra una advertencia. Si un destino obsoleto depende de otro, no se emite ningún mensaje de advertencia. Una vez que los usuarios dejen de usarlo, el objetivo se puede quitar. |
distribs |
Una lista de strings de métodos de distribución que se usarán para este destino 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 |
exec_properties |
Un diccionario de strings que se agregará al Si una clave está presente en las propiedades a nivel de la plataforma y del objetivo, el valor se tomará del destino. |
features |
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 en sí. Este atributo |
restricted_to |
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 |
Las etiquetas se pueden usar en cualquier regla. Las etiquetas de 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
En las pruebas, las etiquetas se suelen usar para anotar la función de una prueba en tu 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 capacidad de anotación en tiempo de ejecución. El uso de etiquetas y elementos de tamaño brinda flexibilidad para ensamblar conjuntos de pruebas basadas en la política de registro de la base de código.
Bazel modifica el comportamiento de ejecución de la prueba si encuentra las siguientes palabras clave en el atributo
|
target_compatible_with |
Es una lista de los Los destinos que dependen de manera transitiva de destinos incompatibles se consideran incompatibles en sí. 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 que no sean reglas de lugar de trabajo 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 destinos incompatibles. |
testonly |
Si es verdadero, solo los objetivos de solo prueba (como las pruebas) pueden depender de este objetivo.
De forma equivalente, una regla que no sea
Las pruebas (reglas Con este atributo, se pretende significar que el destino no debe contener objetos binarios que se lancen para producción. Debido a que testonly se aplica durante el tiempo de compilación y no en el de ejecución, y se propaga por el árbol de dependencias, se debe aplicar con criterio. Por ejemplo, los stubs y las falsificaciones 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 se marquen como solo de prueba. Por el contrario, las reglas que son peligrosas incluso para vincularse, tal vez porque anulan incondicionalmente el comportamiento normal, definitivamente deben marcarse como solo de prueba. |
toolchains |
Es el conjunto de objetivos a cuyas variables Make puede acceder este objetivo. Estos destinos son instancias de reglas que proporcionan
Ten en cuenta que esto es diferente del concepto de resolución de la cadena de herramientas que usan las implementaciones de reglas para la configuración que depende de la plataforma. No puedes usar este atributo para determinar qué |
visibility |
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 |
Argumentos de la línea de comandos que Bazel pasa al destino cuando se
ejecuta con
Estos argumentos se pasan antes que cualquier valor de |
||||||||||||||||||||
env |
Especifica variables de entorno adicionales para establecer cuando
Este atributo solo se aplica a reglas nativas, como |
||||||||||||||||||||
env_inherit |
Especifica variables de entorno adicionales que se heredarán del entorno externo cuando
Este atributo solo se aplica a reglas nativas, como |
||||||||||||||||||||
size |
Especifica la "pesidad" de un objetivo de prueba, es decir, la cantidad de tiempo o recursos que necesita para ejecutarse. Las pruebas de unidades se consideran “pequeñas”, las pruebas de integración “medianas” y las pruebas de extremo a extremo son “grandes” o “enorme”. 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 al supuesto de uso máximo de recursos locales:
La variable de entorno |
||||||||||||||||||||
timeout |
Tiempo que se espera que se ejecute la prueba antes de que se muestre.
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 horarios diferentes a los anteriores, el tiempo de espera de la prueba se puede anular con la
marca de Bazel La variable de entorno |
||||||||||||||||||||
flaky |
Marca la prueba como inestable. Si se configura, ejecuta la prueba hasta tres veces y marca la prueba como con errores solo si falla cada vez. Según la configuración predeterminada, este atributo se establece como 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 pasar de manera confiable cuando se mantienen sus aserciones. |
||||||||||||||||||||
shard_count |
Especifica la cantidad de fragmentos paralelos que se usarán para ejecutar la prueba. Este valor anulará cualquier heurística utilizada para determinar la cantidad de fragmentos paralelos con los que se ejecutará la prueba. Ten en cuenta que, en algunas reglas de prueba, es posible que este parámetro sea necesario para habilitar la 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 sea compatible con el protocolo de fragmentación de pruebas. Si no es así, es probable que se ejecuten todas las pruebas en cada fragmento, que no es lo que deseas. Consulta Fragmentación de pruebas en la enciclopedia de pruebas para obtener detalles sobre la fragmentación. |
||||||||||||||||||||
local |
Hace que la prueba se ejecute de manera local, sin zona de pruebas. Configurarlo como verdadero equivale a proporcionar "local" como una 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 |
Argumentos de la línea de comandos que Bazel pasará al destino cuando se ejecute
mediante el comando
NOTA: Los argumentos no se pasan cuando ejecutas el destino
fuera de Bazel (por ejemplo, si ejecutas de forma manual el objeto binario en
|
env |
Especifica variables de entorno adicionales para establecer 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 de forma manual el objeto binario en
|
output_licenses |
Las licencias de los archivos de salida que genera este objeto 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 objetivo se compila de diferentes maneras. Específicamente, los atributos configurables pueden variar según las marcas pasadas a la línea de comandos de Bazel o la dependencia descendente que solicite el destino. Esto se puede usar, por ejemplo, a fin de personalizar el destino para varias plataformas o modos de compilación.
En el siguiente ejemplo, se declaran fuentes diferentes para arquitecturas de destino distintas. Ejecutar bazel build :multiplatform_lib --cpu x86 compilará el destino con x86_impl.cc, mientras que sustituir --cpu arm hará que 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 config_setting o constraint_value que cumple la configuración del destino.
Bazel evalúa los atributos configurables después de procesar las macros y antes de
las reglas de procesamiento (técnicamente, entre las
fases de carga y análisis).
Cualquier procesamiento anterior 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 realizar suposiciones 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 una
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. Te recomendamos que evites usarlo en otros idiomas cuando sea posible. Aún no tenemos una ruta de baja, pero con el tiempo también se darán de baja.
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 las reglas de compilación también implican de forma implícita uno o más objetivos de archivo de salida, cuyos contenidos y significados son específicos de las reglas.
Por ejemplo, cuando declaras explícitamente una regla java_binary(name='foo', ...), también declaras de forma implícita un destino de archivo de salida foo_deploy.jar como miembro del mismo paquete.
(Este destino en particular es un archivo Java autónomo adecuado para la implementación).
Los objetivos de salida implícitos son los miembros destacados del gráfico objetivo 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 ellas como dependencias en los 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 incluye una sección especial en la que se detallan los nombres y el contenido de cualquier salida implícita que involucre una declaración de ese tipo de regla.
Una distinción importante, pero sutil, entre los dos espacios de nombres que usa el sistema de compilación: las etiquetas identifican objetivos, que pueden ser reglas o archivos, y los objetivos de los archivos se pueden dividir en objetivos de archivo de origen (o de entrada) y objetivos de archivo derivado (o de 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 objetivo 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 de objetos .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 relacionados con su funcionamiento. Esto se explica con más detalle en la referencia de conceptos de COMPILACIÓN.