Reglas
alias
alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)
La regla alias crea otro nombre al que se puede hacer referencia.
El uso de alias solo funciona para los destinos "normales". En particular, no se pueden crear alias para package_group ni test_suite.
La regla de alias tiene su propia declaración de visibilidad. En todos los demás aspectos, se comporta como la regla a la que hace referencia (p.ej., se ignora la prueba en el alias; en su lugar, se usa la prueba de la regla a la que se hace referencia) con algunas excepciones menores:
-
Las pruebas no se ejecutan si se menciona su alias en la línea de comandos. Para definir un alias que ejecute la prueba a la que se hace referencia, usa una regla
test_suitecon un solo objetivo en su atributotests. -
Cuando se definen grupos de entornos, no se admiten los alias de las reglas
environment. Tampoco se admiten en la opción de línea de comandos--target_environment.
Ejemplos
filegroup(
name = "data",
srcs = ["data.txt"],
)
alias(
name = "other",
actual = ":data",
)
Argumentos
| Atributos | |
|---|---|
name |
Un nombre único para este objetivo. |
actual
|
|
config_setting
config_setting(name, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)
Coincide con un estado de configuración esperado (expresado como marcas de compilación o restricciones de plataforma) con el fin de activar atributos configurables. Consulta select para obtener información sobre cómo consumir esta regla y Atributos configurables para obtener una descripción general de la función general.
Ejemplos
El siguiente comando coincide con cualquier compilación que establezca --compilation_mode=opt o -c opt (ya sea de forma explícita en la línea de comandos o implícitamente desde los archivos .bazelrc):
config_setting(
name = "simple",
values = {"compilation_mode": "opt"}
)
El siguiente comando coincide con cualquier compilación que se oriente a ARM y aplique la definición personalizada FOO=bar (por ejemplo, bazel build --cpu=arm --define FOO=bar ...):
config_setting(
name = "two_conditions",
values = {
"cpu": "arm",
"define": "FOO=bar"
}
)
El siguiente comando coincide con cualquier compilación que establezca la marca definida por el usuario
--//custom_flags:foo=1 (ya sea de forma explícita en la línea de comandos o de forma implícita desde los archivos .bazelrc):
config_setting(
name = "my_custom_flag_is_set",
flag_values = { "//custom_flags:foo": "1" },
)
La siguiente expresión coincide con cualquier compilación que se oriente a una plataforma con una arquitectura x86_64 y la versión 2.25 de glibc, siempre que exista un constraint_value con la etiqueta //example:glibc_2_25. Ten en cuenta que una plataforma seguirá coincidiendo si define valores de restricción adicionales más allá de estos dos.
config_setting(
name = "64bit_glibc_2_25",
constraint_values = [
"@platforms//cpu:x86_64",
"//example:glibc_2_25",
]
)
En todos estos casos, es posible que la configuración cambie dentro de la compilación, por ejemplo, si
se debe compilar un destino para una plataforma diferente a su dependencia. Esto significa que, incluso cuando un
config_setting no coincide con las marcas de línea de comandos de nivel superior, es posible que coincida con
algunos destinos de compilación.
Notas
- Consulta select para ver qué sucede cuando varios
config_settingcoinciden con el estado de configuración actual. - En el caso de las marcas que admiten formas abreviadas (p. ej.,
--compilation_modeen comparación con-c), las definiciones devaluesdeben usar la forma completa. Estas coinciden automáticamente con invocaciones con cualquiera de los formatos. -
Si una marca toma varios valores (como
--copt=-Da --copt=-Dbo una marca de Starlark de tipo lista),values = { "flag": "a" }coincide si"a"está presente en cualquier lugar de la lista real.values = { "myflag": "a,b" }funciona de la misma manera: coincide con--myflag=a --myflag=b,--myflag=a --myflag=b --myflag=c,--myflag=a,by--myflag=c,b,a. La semántica exacta varía entre las marcas. Por ejemplo,--coptno admite varios valores en la misma instancia:--copt=a,bproduce["a,b"], mientras que--copt=a --copt=bproduce["a", "b"](por lo quevalues = { "copt": "a,b" }coincide con el primero, pero no con el segundo). Sin embargo,--ios_multi_cpus(para las reglas de Apple) sí:-ios_multi_cpus=a,byios_multi_cpus=a --ios_multi_cpus=bproducen["a", "b"]. Verifica las definiciones de las marcas y prueba tus condiciones con cuidado para verificar las expectativas exactas. - Si necesitas definir condiciones que no están modeladas por marcas de compilación integradas, usa las
marcas definidas por Starlark. También puedes usar
--define, pero esta opción ofrece una compatibilidad más débil y no se recomienda. Consulta aquí para obtener más información. - Evita repetir definiciones de
config_settingidénticas en diferentes paquetes. En su lugar, haz referencia a unconfig_settingcomún que se definió en un paquete canónico. values,define_valuesyconstraint_valuesse pueden usar en cualquier combinación en el mismoconfig_setting, pero se debe configurar al menos uno para cualquierconfig_settingdeterminado.
Argumentos
| Atributos | |
|---|---|
name |
Un nombre único para este objetivo. |
constraint_values
|
constraint_values que la plataforma de destino debe especificar para coincidir con este config_setting. (No se considera la plataforma de ejecución). Se ignoran los valores de restricción adicionales que tenga la plataforma. Consulta
Atributos de compilación configurables para obtener más detalles.
En el caso de que dos |
define_values
|
values, pero específicamente para la marca --define.
Esto significa lo siguiente:
config_setting(
name = "a_and_b",
values = {
"define": "a=1",
"define": "b=2",
})
no funciona porque la misma clave (
config_setting(
name = "a_and_b",
define_values = {
"a": "1",
"b": "2",
})
coincide correctamente con
|
flag_values
|
values, pero para
indicadores de compilación definidos por el usuario.
Este es un atributo distinto porque se hace referencia a las marcas definidas por el usuario como etiquetas, mientras que a las marcas integradas se hace referencia como cadenas arbitrarias. |
values
|
Esta regla hereda la configuración del destino configurado que hace referencia a ella en una sentencia Para mayor comodidad, los valores de configuración se especifican como marcas de compilación (sin
el Si no se establece una marca de forma explícita en la línea de comandos, se usa su valor predeterminado.
Si una clave aparece varias veces en el diccionario, solo se usa la última instancia.
Si una clave hace referencia a una marca que se puede establecer varias veces en la línea de comandos (p.ej.,
|
filegroup
filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)
Usa filegroup para asignar un nombre conveniente a una colección de objetivos.
Luego, se puede hacer referencia a ellos desde otras reglas.
Se recomienda usar filegroup en lugar de hacer referencia a directorios directamente.
La última opción no es adecuada, ya que el sistema de compilación no tiene conocimiento completo de todos los archivos debajo del directorio, por lo que es posible que no se vuelva a compilar cuando cambien estos archivos. Cuando se combina con glob, filegroup puede garantizar que el sistema de compilación conozca todos los archivos de forma explícita.
Ejemplos
Para crear un filegroup que consta de dos archivos fuente, haz lo siguiente:
filegroup(
name = "mygroup",
srcs = [
"a_file.txt",
"some/subdirectory/another_file.txt",
],
)
O bien, usa un glob para explorar un directorio de datos de prueba:
filegroup(
name = "exported_testdata",
srcs = glob([
"testdata/*.dat",
"testdata/logs/**/*.log",
]),
)
Para usar estas definiciones, haz referencia a filegroup con una etiqueta de cualquier regla:
cc_library(
name = "my_library",
srcs = ["foo.cc"],
data = [
"//my_package:exported_testdata",
"//my_package:mygroup",
],
)
Argumentos
| Atributos | |
|---|---|
name |
Un nombre único para este objetivo. |
srcs
|
Es común usar el resultado de una expresión glob para el valor del atributo |
data
|
Los destinos nombrados en el atributo |
output_group
|
Un "grupo de salida" es una categoría de artefactos de salida de un destino, especificado en la implementación de esa regla. |
genquery
genquery(name, deps, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)
genquery() ejecuta una consulta especificada en el lenguaje de consulta Blaze y vuelca el resultado en un archivo.
Para mantener la coherencia de la compilación, la consulta solo puede visitar
la clausura transitiva de los destinos especificados en el atributo scope. Las consultas que infrinjan esta regla fallarán durante la ejecución si strict no se especifica o es verdadero (si strict es falso, los objetivos fuera del alcance simplemente se omitirán con una advertencia). La forma más fácil de asegurarse de que esto no suceda es mencionar las mismas etiquetas en el alcance que en la expresión de consulta.
La única diferencia entre las consultas permitidas aquí y en la línea de comandos es que aquí no se permiten las consultas que contienen especificaciones de destino de comodines (p.ej., //pkg:* o //pkg:all).
Los motivos son dobles: primero, porque genquery debe especificar un alcance para evitar que los destinos fuera del cierre transitivo de la consulta influyan en su resultado y, segundo, porque los archivos BUILD no admiten dependencias de comodín (p.ej., no se permite deps=["//a/..."]).
El resultado de genquery se ordena con --order_output=full para aplicar un resultado determinista.
El nombre del archivo de salida es el nombre de la regla.
Ejemplos
En este ejemplo, se escribe la lista de las etiquetas en el cierre transitivo del objetivo especificado en un archivo.
genquery(
name = "kiwi-deps",
expression = "deps(//kiwi:kiwi_lib)",
scope = ["//kiwi:kiwi_lib"],
)
Argumentos
| Atributos | |
|---|---|
name |
Un nombre único para este objetivo. |
expression
|
:b en este atributo del archivo a/BUILD hará referencia al objetivo //:b.
|
opts
|
bazel query. Aquí no se permiten algunas opciones de consulta: --keep_going, --query_file, --universe_scope, --order_results y --order_output. Las opciones que no se especifiquen aquí tendrán sus valores predeterminados, al igual que en la línea de comandos de bazel query.
|
scope
|
|
strict
|
|
genrule
genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, exec_tools, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)
Un genrule genera uno o más archivos con un comando Bash definido por el usuario.
Las genrules son reglas de compilación genéricas que puedes usar si no hay una regla específica para la tarea.
Por ejemplo, puedes ejecutar una línea de Bash. Sin embargo, si necesitas compilar archivos C++, sigue
las reglas de cc_* existentes, ya que se hizo todo el trabajo pesado
por ti.
No uses una genrule para ejecutar pruebas. Existen dispensaciones especiales para las pruebas y los resultados de las pruebas, incluidas las políticas de almacenamiento en caché y las variables de entorno. Por lo general, las pruebas deben ejecutarse después de que se complete la compilación y en la arquitectura de destino, mientras que las reglas de generación se ejecutan durante la compilación y en la arquitectura del host (las dos pueden ser diferentes). Si necesitas una regla de prueba para uso general, usa sh_test.
Consideraciones sobre la compilación cruzada
Consulta el manual del usuario para obtener más información sobre la compilación cruzada.
Si bien genrules se ejecuta durante una compilación, sus resultados suelen usarse después de la compilación, para la implementación o las pruebas. Considera el ejemplo de la compilación de código C para un microcontrolador: el compilador acepta archivos fuente C y genera código que se ejecuta en un microcontrolador. Obviamente, el código generado no se puede ejecutar en la CPU que se usó para compilarlo, pero el compilador C (si se compila desde la fuente) sí puede hacerlo.
El sistema de compilación usa la configuración del host para describir las máquinas en las que se ejecuta la compilación y la configuración de destino para describir las máquinas en las que se debe ejecutar el resultado de la compilación. Proporciona opciones para configurar cada uno de ellos y segrega los archivos correspondientes en directorios separados para evitar conflictos.
En el caso de genrules, el sistema de compilación se asegura de que las dependencias se compilen de forma adecuada: srcs se compila (si es necesario) para la configuración de target, tools se compila para la configuración de host y el resultado se considera para la configuración de target. También proporciona
variadas variables de "Make" que los comandos genrule pueden pasar a las herramientas correspondientes.
Es intencional que genrule no defina ningún atributo deps: otras reglas integradas usan metainformación dependiente del lenguaje que se pasa entre las reglas para determinar automáticamente cómo controlar las reglas dependientes, pero este nivel de automatización no es posible para genrules. Las reglas de generación funcionan únicamente a nivel de los archivos y los runfiles.
Casos especiales
Compilación host-host: En algunos casos, el sistema de compilación debe ejecutar genrules para que el resultado también se pueda ejecutar durante la compilación. Si, por ejemplo, un genrule compila un compilador personalizado que, posteriormente, usa otro genrule, el primero debe producir su resultado para la configuración del host, ya que allí es donde se ejecutará el compilador en el otro genrule. En este caso, el sistema de compilación hace lo correcto automáticamente: compila srcs y outs de la primera genrule para la configuración del host en lugar de la configuración de destino. Consulta el manual del usuario para obtener más información.
Herramientas de JDK y C++: Para usar una herramienta del JDK o del paquete de compiladores de C++, el sistema de compilación proporciona un conjunto de variables que se pueden usar. Consulta Variable"Make" para obtener más detalles.
Entorno de genrule
El comando genrule se ejecuta mediante una shell de Bash que está configurada para fallar cuando falla un comando
o una canalización, con set -e -o pipefail.
La herramienta de compilación ejecuta el comando Bash en un entorno de proceso limpio que solo define variables principales, como PATH, PWD, TMPDIR y algunas otras.
Para garantizar que las compilaciones se puedan reproducir, la mayoría de las variables definidas en el entorno de shell del usuario no se pasan al comando de genrule. Sin embargo, Bazel (pero no Blaze) pasa el valor de la variable de entorno PATH del usuario.
Cualquier cambio en el valor de PATH hará que Bazel vuelva a ejecutar el comando en la siguiente compilación.
Un comando genrule no debe acceder a la red, excepto para conectar procesos que sean secundarios del comando en sí, aunque esto no se aplica actualmente.
El sistema de compilación borra automáticamente los archivos de salida existentes, pero crea los directorios superiores necesarios antes de ejecutar una genrule. También quita los archivos de salida en caso de que se produzca una falla.
Consejo general
- Asegúrate de que las herramientas que ejecuta una genrule sean deterministas y herméticas. No deben escribir marcas de tiempo en su salida y deben usar un orden estable para los conjuntos y los mapas, así como escribir solo rutas de acceso de archivos relativas en el resultado, no rutas absolutas. Si no sigues esta regla, se producirá un comportamiento de compilación inesperado (Bazel no volverá a compilar una genrule que creías que lo haría) y se degradará el rendimiento de la caché.
- Usa
$(location)de forma extensa para los resultados, las herramientas y las fuentes. Debido a la segregación de archivos de salida para diferentes configuraciones, genrules no puede depender de rutas de acceso absolutas o hard-coded. - Escribe una macro Starlark común en caso de que se usen las mismas reglas de generación o reglas muy similares en varios lugares. Si la genrule es compleja, considera implementarla en una secuencia de comandos o como una regla de Starlark. Esto mejora la legibilidad y la capacidad de prueba.
- Asegúrate de que el código de salida indique correctamente el éxito o el error de genrule.
- No escribas mensajes informativos en stdout ni stderr. Si bien es útil para la depuración, esto puede convertirse fácilmente en ruido. Una genrule correcta debería ser silenciosa. Por otro lado, una genrule que falle debería emitir mensajes de error válidos.
$$evaluates to a$, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such asls $(dirname $x), one must escape it thus:ls $$(dirname $$x).- Evita crear symlinks y directorios. Bazel no copia la estructura de directorios o symlinks que crea genrules, y su verificación de dependencias de directorios no es sólida.
- Cuando hagas referencia a genrule en otras reglas, puedes usar la etiqueta de genrule o las etiquetas de los archivos de salida individuales. A veces, un enfoque es más legible, a veces el otro: hacer referencia a salidas por nombre en el
srcsde una regla de consumo evitará que se tomen otros resultados de genrule de forma no intencional, pero puede ser tedioso si genrule produce muchos resultados.
Ejemplos
En este ejemplo, se genera foo.h. No hay fuentes, ya que el comando no toma ninguna entrada. El "binario" que ejecuta el comando es una secuencia de comandos de Perl en el mismo paquete que genrule.
genrule(
name = "foo",
srcs = [],
outs = ["foo.h"],
cmd = "./$(location create_foo.pl) > \"$@\"",
tools = ["create_foo.pl"],
)
En el siguiente ejemplo, se muestra cómo usar un filegroup
y los resultados de otro genrule. Ten en cuenta que usar $(SRCS) en lugar de directivas $(location) explícitas también funcionaría. En este ejemplo, se usa lo último a modo de demostración.
genrule(
name = "concat_all_files",
srcs = [
"//some:files", # a filegroup with multiple files in it ==> $(locations)
"//other:gen", # a genrule with a single output ==> $(location)
],
outs = ["concatenated.txt"],
cmd = "cat $(locations //some:files) $(location //other:gen) > $@",
)
Argumentos
| Atributos | |
|---|---|
name |
Un nombre único para este objetivo. Puedes hacer referencia a esta regla por nombre en la sección srcs o deps de otras reglas BUILD. Si la regla genera archivos de origen, debes usar el atributo
srcs.
|
srcs
|
Este atributo no es adecuado para enumerar las herramientas que ejecuta
El sistema de compilación garantiza que estos requisitos previos se compilen antes de ejecutar el comando genrule. Se compilan con la misma configuración que la solicitud de compilación original. Los nombres de los archivos de estos requisitos previos están disponibles para el comando como una lista separada por espacios en |
outs
|
Los archivos de salida no deben cruzar los límites del paquete. Los nombres de los archivos de salida se interpretan como relativos al paquete.
Si se establece la marca
Se espera que el comando genrule cree cada archivo de salida en una ubicación predeterminada.
La ubicación está disponible en |
cmd
|
$(location)
y la variable “Make”.
cmd_bash, cmd_ps y cmd_bat,
si ninguno de ellos es aplicable.
Si la longitud de la línea de comandos supera el límite de la plataforma (64K en Linux/macOS, 8K en Windows), genrule escribirá el comando en una secuencia de comandos y la ejecutará para solucionar el problema. Esto se aplica a todos los atributos cmd ( |
cmd_bash
|
Este atributo tiene una prioridad más alta que |
cmd_bat
|
Este atributo tiene una prioridad más alta que
|
cmd_ps
|
Este atributo tiene una prioridad más alta que
Para que Powershell sea más fácil de usar y menos propenso a errores, ejecutamos los siguientes comandos para configurar el entorno antes de ejecutar el comando de Powershell en genrule.
|
exec_tools
|
tools, excepto que estas dependencias se configurarán para la plataforma de ejecución de la regla en lugar de la configuración del host.
Esto significa que las dependencias en exec_tools no están sujetas a las mismas limitaciones que las dependencias en tools. En particular, no es necesario que usen la configuración del host para sus propias dependencias transitivas. Consulta tools para obtener más detalles.
El equipo de Blaze migrará todos los usos de |
executable
|
Si configuras esta marca como "True", el resultado es un archivo ejecutable y se puede ejecutar con el comando No se admite la declaración de dependencias de datos para el ejecutable generado. |
local
|
Si se establece como "true", esta opción obliga a que
Esto equivale a proporcionar "local" como una etiqueta ( |
message
|
Es un mensaje de progreso que se imprimirá cuando se ejecute este paso de compilación. De forma predeterminada, el
mensaje es "Generating output" (o algo igualmente insulso), pero puedes proporcionar uno
más específico. Usa este atributo en lugar de |
output_licenses
|
common attributes
.
|
output_to_bindir
|
Si se establece en "True", esta opción hace que los archivos de salida se escriban en el directorio |
tools
|
El sistema de compilación se asegura de que estos requisitos previos se compilen antes de ejecutar el comando genrule. Se compilan con la configuración del host, ya que estas herramientas se ejecutan como parte de la compilación. La ruta de un
Cualquier |
test_suite
test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, tests, visibility)
Un test_suite define un conjunto de pruebas que se consideran "útiles" para los humanos. Esto permite que los proyectos definan conjuntos de pruebas, como "pruebas que debes ejecutar antes del registro", "pruebas de esfuerzo de nuestro proyecto" o "todas las pruebas pequeñas". El comando blaze test respeta este tipo de organización: para una invocación como blaze test //some/test:suite, Blaze primero enumera todos los destinos de prueba que incluye de forma transitiva el destino //some/test:suite (lo que llamamos "expansión de test_suite") y, luego, compila y prueba esos destinos.
Ejemplos
Un conjunto de pruebas para ejecutar todas las pruebas pequeñas del paquete actual.
test_suite(
name = "small_tests",
tags = ["small"],
)
Un paquete de pruebas que ejecuta un conjunto especificado de pruebas:
test_suite(
name = "smoke_tests",
tests = [
"system_unittest",
"public_api_unittest",
],
)
Un paquete de pruebas para ejecutar todas las pruebas del paquete actual que no sean inestables.
test_suite(
name = "non_flaky_test",
tags = ["-flaky"],
)
Argumentos
| Atributos | |
|---|---|
name |
Un nombre único para este objetivo. |
tags
|
Las etiquetas que comienzan con un carácter "-" se consideran negativas. El carácter "-" que precede no se considera parte de la etiqueta, por lo que una etiqueta de suite de "-small" coincide con el tamaño "small" de una prueba. Todas las demás etiquetas se consideran positivas. De manera opcional, para que las etiquetas positivas sean más explícitas, también pueden comenzar con el carácter "+", que no se evaluará como parte del texto de la etiqueta. Solo hace que la distinción entre positivo y negativo sea más fácil de leer. En el conjunto de pruebas, solo se incluirán las reglas de prueba que coincidan con todas las etiquetas positivas y ninguna de las etiquetas negativas. Ten en cuenta que esto no significa que se omita la verificación de errores para las dependencias en las pruebas que se filtran. Las dependencias en las pruebas omitidas aún deben ser legales (p. ej., no deben estar bloqueadas por restricciones de visibilidad).
La palabra clave de la etiqueta
Ten en cuenta que el
Si necesitas un |
tests
|
Aquí se acepta cualquier
Si el atributo |