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
- Destinos de salida implícitos
Asignación de token de shell de Bourne
Ciertos atributos de cadena de algunas reglas se dividen en varios de acuerdo con las reglas de asignación de token del shell de Bourne: los espacios sin comillas delimitan las palabras separadas, y las palabras se usan comillas dobles y barras inversas para evitar la asignación de token.
Aquellos atributos sujetos a esta asignación de token son se indica explícitamente como tal en sus definiciones en este documento.
Atributos sujetos a "Marca" expansión variable y shell de Bourne
la asignación de token se usan normalmente para pasar opciones arbitrarias
compiladores y otras herramientas. Algunos ejemplos de estos atributos son
cc_library.copts y java_library.javacopts.
Juntas, estas sustituciones permiten un
una sola variable de cadena para expandirse a una lista específica de la configuración
de palabras de opciones.
Expansión de etiquetas
Algunos atributos de cadena de unas pocas reglas están sujetos a etiquetas.
expansión: si esas cadenas contienen una etiqueta válida como
como //mypkg:target, y esa etiqueta es una
declarado como requisito previo de la regla actual, se expande al
nombre de ruta del archivo representado por el
objetivo
//mypkg:target
Algunos ejemplos de atributos incluyen genrule.cmd y
cc_binary.linkopts Los detalles pueden variar significativamente en
en cada caso, sobre temas como si las etiquetas relativas
expandido; cómo se expanden las etiquetas que se expanden a varios archivos
se tratan, etc. Consulta la documentación de atributos de reglas para
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 del todo.
| Atributo | Descripción |
|---|---|
data |
Archivos que necesita esta regla en el tiempo de ejecución. Puede enumerar destinos de archivos o de reglas. Generales 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 |
Dependencias del destino. Por lo general, solo debe enumerar los objetivos de la regla. (Sin embargo,
algunas reglas permiten que los archivos se enumeren directamente en Por lo general, las reglas específicas de un idioma limitan los destinos enumerados a aquellos con proveedores específicos.
La semántica precisa de lo que significa que un objetivo dependa de otro mediante
Las
Por lo general, se usa una dependencia |
licenses |
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. Lo que no debes hacer usan esto. |
srcs |
Archivos procesados o incluidos por esta regla. Por lo general, enumera los archivos de forma directa, pero
puede mostrar los objetivos de la regla (como Las reglas específicas del lenguaje a menudo requieren que los archivos de la lista tengan extensiones de archivo. |
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 compilaciones las reglas de firewall.
| Atributo | Descripción |
|---|---|
compatible_with |
La lista de entornos para los que se puede crear este destino, además de compatibles de forma predeterminada. Esto es parte del sistema de restricciones de Bazel, que permite a los usuarios declarar qué estos pueden o no pueden depender unos de otros. Por ejemplo, implementable de forma externa. Los objetos binarios no deben depender de bibliotecas con código secreto de la empresa. Consulta ConstraintSemantics para obtener más detalles. |
deprecation |
Un mensaje de advertencia explicativo asociado a este destino. Por lo general, se usa para notificar a los usuarios que un destino dejó de estar disponible o fue sustituida por otra regla, es privada de un paquete o considerado perjudicial por alguna razón. Es una buena idea incluir alguna referencia (como una página web, un número de error o ejemplos de CL de migración), que uno pueda averiguar fácilmente qué cambios se requieren para evitar el mensaje. Si hay un objetivo nuevo que se pueda usar como una disminución en el reemplazo, se trata de un es buena idea migrar todos los usuarios del destino anterior.
Este atributo no tiene efecto en la forma en que se crean los elementos, pero
puede afectar el resultado de diagnóstico de una herramienta de compilación. La herramienta de compilación emite un
una advertencia cuando se establece una regla con un atributo Las dependencias dentro del paquete están exentas de esta advertencia. Por lo tanto, por ejemplo, crear las pruebas de una regla obsoleta verán una advertencia. Si un objetivo obsoleto depende de otro objetivo obsoleto, no se muestran advertencias si se envía un mensaje de error. Una vez que las personas dejen de usarlo, se podrá quitar el objetivo. |
distribs |
Una lista de cadenas de método 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. Lo que no debes hacer usan esto. |
exec_compatible_with |
Una lista de
|
exec_properties |
Un diccionario de cadenas que se agregará a Si una clave está presente en las propiedades de nivel de plataforma y de destino, 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 el significado de un atributo depende de la regla misma. Este atributo |
restricted_to |
Es la lista de entornos para los que se puede compilar este destino, en lugar de 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 prueba y
Las reglas
Bazel modifica el comportamiento de su código de zona de pruebas si encuentra lo siguiente:
palabras clave en el atributo
Por lo general, las etiquetas de las pruebas se usan para anotar el rol de una prueba en tu el proceso de depuración y lanzamiento. Por lo general, las etiquetas son más útiles para C++ y Python. que carecen de la capacidad de anotación de tiempo de ejecución. El uso de etiquetas y tamaños ofrece flexibilidad para organizar conjuntos de pruebas basadas en la base de código de entrada.
Bazel modifica el comportamiento de ejecución de la prueba si encuentra las siguientes palabras clave en el
Atributo
|
target_compatible_with |
Una lista de
Los objetivos que dependen transitivamente de objetivos incompatibles son ellos mismos considerada incompatible. 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 Workspace admiten esto.
.
En algunas reglas, este atributo no tiene efecto. Por ejemplo, si especificas
Consulta la Plataformas para obtener más información sobre la omisión de objetivos incompatibles. |
testonly |
Si se establece en verdadero, solo los objetivos de solo prueba (como las pruebas) pueden depender de este objetivo.
De forma equivalente, una regla que no sea
Pruebas ( Con este atributo se pretende indicar que el destino no debe contenidos en objetos binarios que se lanzan a producción. Debido a que testonly se aplica en el tiempo de compilación, no en el de ejecución, y se propaga viralmente a través del árbol de dependencia, debería aplicarse con cuidado. Para ejemplo, stubs y falsificaciones que son útiles para las pruebas de unidades y las de integración que incluyan los mismos objetos binarios que se lanzarán en producción. por lo que no debería marcarse solo de prueba. Por el contrario, las reglas que son peligrosos, incluso, porque anular el comportamiento normal, definitivamente se debe marcar como solo de prueba. |
toolchains |
Es el conjunto de destinos cuyas variables de Make son este destino:
tienen permitido el acceso. Estos objetivos 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 dependiente de la plataforma. No puedes usar esto
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 |
Son los argumentos de línea de comandos que Bazel pasa al destino cuando es
se ejecuta con
Estos argumentos se pasan antes que cualquier valor |
||||||||||||||||||||
env |
Especifica las variables de entorno adicionales que se deben configurar cuando se ejecuta la prueba.
Este atributo solo se aplica a las reglas nativas, como |
||||||||||||||||||||
env_inherit |
Especifica las variables de entorno adicionales que se heredarán del
Un entorno externo cuando
Este atributo solo se aplica a las reglas nativas, como |
||||||||||||||||||||
size |
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 de integración "medias" y las de extremo a extremo "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 las pruebas corresponden a los siguientes tiempos de espera predeterminados y a los recursos locales máximos supuestos usos:
La variable de entorno |
||||||||||||||||||||
timeout |
El tiempo que se espera que se ejecute la prueba antes de devolverse.
Si bien el atributo de tamaño de una prueba controla la estimación de recursos,
el tiempo de espera se puede establecer de forma independiente. Si no se especifica de forma explícita, el
de espera se basa en el tamaño de la prueba. La prueba
El tiempo de espera se puede anular con la marca
En los casos que no sean los mencionados anteriormente, el tiempo de espera de la prueba se puede anular con
Marca de Bazel de La variable de entorno |
||||||||||||||||||||
flaky |
Marca la prueba como inestable. Si está configurada, ejecuta la prueba hasta tres veces y la marca como errónea solo si falla cada vez. De forma predeterminada, este atributo se establece en falso, y la prueba se ejecutado solo una vez. Ten en cuenta que, en general, no se recomienda usar este atributo. las pruebas deben pasar de manera confiable cuando se mantienen sus aserciones. |
||||||||||||||||||||
shard_count |
Especifica la cantidad de fragmentos paralelos usar 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, para algunas pruebas,
reglas, es posible que se requiera este parámetro 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 admita el protocolo de fragmentación de pruebas. De lo contrario, lo más probable es que ejecute todas las pruebas en cada fragmento, no es lo que quieres. Consulta Fragmentación de pruebas en la Enciclopedia de pruebas para obtener detalles sobre la fragmentación. |
||||||||||||||||||||
local |
Fuerza la ejecución de la prueba de manera local, sin zona de pruebas. Si estableces esta política como verdadera, equivale a proporcionar una configuración “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 |
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, ejecutando manualmente el objeto binario en
|
env |
Especifica las variables de entorno adicionales que se deben configurar cuando el destino
ejecutado por
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, ejecutando manualmente el objeto binario en
|
output_licenses |
Son 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. Lo que no debes hacer usan esto. |
Atributos configurables
La mayoría de los atributos son “configurables”, lo que significa que sus valores pueden cambiar cuando el objetivo se construye de diferentes maneras. Específicamente, atributos configurables puede variar según las marcas que se pasen a la línea de comandos de Bazel una dependencia descendente solicita el destino. Esto se puede usar para para personalizar el destino para varias plataformas o modos de compilación.
En el siguiente ejemplo, se declaran diferentes fuentes para distintos destinos
arquitecturas. Ejecutando bazel build :multiplatform_lib --cpu x86
compilará el destino con x86_impl.cc y sustituirá al
En su lugar, --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 basado
en cuál config_setting
o constraint_value
con los criterios que satisface la configuración del destino.
Bazel evalúa los atributos configurables después de procesar las macros y antes
de procesamiento de lenguaje natural (técnicamente, entre
fases de carga y análisis).
Cualquier procesamiento previo a la evaluación de select() no sabe qué
que elija select(). Las macros, por ejemplo, no pueden cambiar
su comportamiento en función de la rama elegida, y bazel query puede
solo hacer conjeturas conservadoras sobre las dependencias configurables de un objetivo. Consulta
esta sección de Preguntas frecuentes
para obtener más información sobre el uso de select() con reglas y macros.
Los atributos marcados con nonconfigurable en su documentación no pueden
usan esta función. Por lo general, un atributo no es configurable porque Bazel
necesita conocer internamente su valor antes de poder determinar cómo resolver un
select()
Consulta Atributos de compilación configurables para obtener una descripción general detallada.
Destinos de salida implícitos
Las salidas implícitas en C++ dejaron de estar disponibles. No lo uses en otros idiomas cuando sea posible. Aún no tenemos una ruta de baja pero, con el tiempo, también dejarán de estar disponibles.
Cuando se define una regla de compilación en un archivo de COMPILACIÓN, se generan
declarar un nuevo destino de la regla con nombre en un paquete. Regla de compilación muchas
también implican de forma implícita uno o más archivos de salida
objetivos, cuyo contenido y significado son específicos de la regla.
Por ejemplo, cuando declaras explícitamente un
java_binary(name='foo', ...), también
La declaración implícita de un archivo de salida
se orienta a 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 miembros de primera clase de la red
gráfico de destino. Al igual que otros objetivos, se crean 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. Pueden ser
se denominan 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 un una sección especial que detalla los nombres y contenidos de cualquier resultados que incluye una declaración de ese tipo de regla.
Una distinción importante, pero un poco 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 pueden dividirse en
los destinos del archivo de origen (o de entrada) y el archivo derivado (o de salida)
objetivos. 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
en un archivo real en el disco (el “espacio de nombres del sistema de archivos”) cada regla
el destino puede corresponder
a cero, a uno o más archivos en el disco.
Es posible que haya archivos en el disco que no tengan un destino correspondiente. para
Ejemplo: archivos de objeto .o producidos durante la compilación de C++
no se puede hacer referencia 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 de
cómo hace su trabajo. Esto se explica con más detalle en
la Referencia de conceptos de COMPILACIÓN