Reglas
alias
Ver fuente de la reglaalias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)
La regla alias
crea otro nombre al que se puede referir una regla.
El alias solo funciona para objetivos "comunes". En particular, package_group
y test_suite
no pueden tener alias.
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., solo se prueba en el alias; solo se usa la regla de prueba de la regla de 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_suite
con un solo objetivo en su atributotests
. -
Cuando se definen grupos de entorno, 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 esta orientación. |
actual
|
|
configuración_configuración
Ver fuente de la reglaconfig_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) a fin de activar los atributos configurables. Consulta Selecciona cómo utilizar esta regla y Atributos configurables para obtener una descripción general de la función general.
Ejemplos
Lo siguiente 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"} )
Lo siguiente coincide con cualquier compilación orientada a ARM y aplica 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" } )
Lo siguiente 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 implícitamente desde los archivos .bazelrc):
config_setting( name = "my_custom_flag_is_set", flag_values = { "//custom_flags:foo": "1" }, )
Lo siguiente coincide con cualquier compilación orientada a una plataforma con una arquitectura x86_64 y la versión 2.25 de glibc, suponiendo que existe un constraint_value
con la etiqueta //example:glibc_2_25
. Ten en cuenta que la plataforma igual coincidirá si define valores de restricción adicionales además 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 objetivo para una plataforma diferente a su dependencia. Esto significa que, incluso cuando un
config_setting
no coincida con las marcas de línea de comandos de nivel superior, puede coincidir con algunos objetivos de compilación.
Notas
- Consulta select para saber qué sucede cuando varios
config_setting
coinciden con el estado de configuración actual. - Para las marcas que admiten formas abreviadas (p. ej.,
--compilation_mode
frente a-c
), las definiciones devalues
deben usar el formulario completo. Estas hacen coincidir de forma automática las invocaciones mediante cualquiera de los dos formatos. -
Si una marca toma varios valores (como
--copt=-Da --copt=-Db
o 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,b
y--myflag=c,b,a
. La semántica exacta varía entre marcas. Por ejemplo,--copt
no admite varios valores en la misma instancia:--copt=a,b
produce["a,b"]
, mientras que--copt=a --copt=b
produce["a", "b"]
(por lo quevalues = { "copt": "a,b" }
coincide con el primero, pero no con el último). Sin embargo,--ios_multi_cpus
(para las reglas de Apple) sí:-ios_multi_cpus=a,b
yios_multi_cpus=a --ios_multi_cpus=b
producen["a", "b"]
. Revisa 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 mediante marcas de compilación integradas, usa las
marcas definidas por Starlark. También puedes usar
--define
, pero ofrece una asistencia más débil y no se recomienda. Consulta aquí para obtener más información. - Evita repetir las definiciones de
config_setting
idénticas en diferentes paquetes. En su lugar, haz referencia a unconfig_setting
común que se defina en un paquete canónico. values
,define_values
yconstraint_values
se pueden usar en cualquier combinación del mismoconfig_setting
, pero se debe configurar al menos uno para cualquierconfig_setting
dado.
Argumentos
Atributos | |
---|---|
name |
Un nombre único para esta orientación. |
constraint_values
|
constraint_values que la plataforma de destino debe especificar para que coincida con este config_setting . (La plataforma de ejecución no se considera aquí). Se ignorará cualquier valor de restricción adicional que la plataforma haya ignorado. Consulta
Atributos de compilación configurables para obtener más detalles.
En caso de que dos objetos |
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", }) esto 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
marcas de compilación definidas por el usuario.
Este es un atributo distinto, ya que las marcas definidas por el usuario se denominan etiquetas, mientras que las marcas integradas se denominan referencias arbitrarias. |
values
|
Esta regla hereda la configuración del destino configurado que hace referencia a ella en una instrucción Para mayor comodidad, los valores de configuración se especifican como marcas de compilación (sin el Si una marca no se configura explícitamente 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.,
|
grupo de archivos
Ver fuente de la reglafilegroup(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 destinos.
Luego, se puede hacer referencia a ellas desde otras reglas.
Se recomienda usar filegroup
en lugar de hacer referencia a directorios directamente.
Este último no parece sólido, ya que el sistema de compilación no tiene conocimiento total de todos los archivos debajo del directorio, por lo que es posible que no se vuelva a compilar cuando estos archivos cambien. 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
compuesto por dos archivos de origen, haz lo siguiente:
filegroup( name = "mygroup", srcs = [ "a_file.txt", "some/subdirectory/another_file.txt", ], )
O bien, usa un glob
para desarrollar un directorio de testdata:
filegroup( name = "exported_testdata", srcs = glob([ "testdata/*.dat", "testdata/logs/**/*.log", ]), )
Para usar estas definiciones, haz referencia al elemento 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 esta orientación. |
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 objetivo, especificada en la implementación de esa regla. |
genquery
Ver fuente de la reglagenquery(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.
A fin de mantener la compilación coherente, la consulta solo puede visitar el cierre transitivo 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 de alcance simplemente se omitirán con una advertencia). La manera más fácil de asegurarte 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 que se permiten aquí y en la línea de comandos es que no se permiten las consultas que contienen especificaciones de destino comodín (p.ej., //pkg:*
o //pkg:all
).
Esto se debe a dos motivos: primero, porque genquery
debe especificar un alcance para evitar que los destinos fuera del cierre transitivo de la consulta influyan en su resultado y, en segundo lugar, porque los archivos BUILD
no admiten dependencias comodín (p.ej., no se permite deps=["//a/..."]
).
El resultado de la consulta se ordena mediante --order_output=full
para aplicar el resultado determinista.
El nombre del archivo de salida es el nombre de la regla.
Ejemplos
En este ejemplo, se escribe la lista de etiquetas en el cierre transitivo del destino especificado en un archivo.
genquery( name = "kiwi-deps", expression = "deps(//kiwi:kiwi_lib)", scope = ["//kiwi:kiwi_lib"], )
Argumentos
Atributos | |
---|---|
name |
Un nombre único para esta orientación. |
expression
|
:b de este atributo en el archivo a/BUILD hará referencia al destino //:b .
|
opts
|
bazel query . Algunas opciones de consulta no están permitidas aquí: --keep_going , --query_file , --universe_scope , --order_results y --order_output . Las opciones que no se especifiquen aquí tendrán sus valores predeterminados, como en la línea de comandos de bazel query .
|
scope
|
|
strict
|
|
genrule
Ver fuente de la reglagenrule(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)
Una genrule
genera uno o más archivos mediante 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 un resumen de Bash. Sin embargo, si necesitas compilar archivos C++, continúa con las reglas cc_*
existentes, porque ya se hizo todo el trabajo pesado.
Ten en cuenta que genrule requiere una shell para interpretar el argumento del comando. También es fácil hacer referencia a los programas arbitrarios disponibles en PATH, sin embargo, esto hace que el comando no sea hermético y es posible que no se pueda reproducir. Si solo necesitas ejecutar una herramienta única, considera usar run_binary.
No uses una genrule para ejecutar pruebas. Existen distribuciones 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 genrules se ejecutan durante la compilación y en la arquitectura ejecutiva (pueden ser diferentes). Si necesitas una regla de prueba de uso general, usa sh_test
.
Consideraciones sobre la compilación cruzada
Consulta el manual de usuario para obtener más información sobre la compilación cruzada.
Si bien las genrules se ejecutan durante una compilación, sus resultados suelen usarse después de esta, para su implementación o prueba. Considera el ejemplo de compilación de código C para un microcontrolador: el compilador acepta archivos de origen 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 compiló desde la fuente) tiene que hacerlo.
El sistema de compilación usa la configuración de ejecución para describir las máquinas en las que se ejecuta la compilación y la configuración de destino a fin de describir las máquinas en las que se debe ejecutar el resultado de la compilación. Proporciona opciones para configurar cada una de ellas y segrega los archivos correspondientes en directorios independientes a fin de evitar conflictos.
Para las reglas de generación, el sistema de compilación garantiza que las dependencias se compilen de manera correcta: srcs
se compilan (si es necesario) para la configuración de destino, tools
se compilan para la configuración de exec y se considera que el resultado es para la configuración de objetivo. También proporciona las
variables de "marca" que los comandos de 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 manejar las reglas dependientes, pero este nivel de automatización no es posible para genrules. Las genrules funcionan puramente a nivel de archivo y runfiles.
Casos especiales
Compilación exec-exec: En algunos casos, el sistema de compilación necesita ejecutar genrules para que el resultado también se pueda ejecutar durante la compilación. Si, por ejemplo, una genrule compila algún compilador personalizado que luego otra genrule usa, el primero tiene que producir su resultado para la configuración de ejecución, ya que allí es donde el compilador se ejecutará en la otra genrule. En este caso, el sistema de compilación hace lo correcto automáticamente: compila el srcs
y el outs
de la primera genrule para la configuración ejecutiva 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 el conjunto de compiladores de C++, el sistema de compilación proporciona un conjunto de variables a usar. Consulta Variable"Make" para obtener detalles.
Entorno de Genrule
El comando genrule es ejecutado por un shell Bash que está configurado para fallar cuando un comando o una canalización falla, mediante set -e -o pipefail
.
La herramienta de compilación ejecuta el comando Bash en un entorno de proceso limpio que define solo las variables principales como PATH
, PWD
, TMPDIR
y algunas otras.
Para garantizar que las compilaciones sean reproducibles, 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 próxima compilación.
Un comando genrule no debe acceder a la red, excepto para conectar procesos que son secundarios del comando en sí, aunque esto no se aplica actualmente.
El sistema de compilación borra automáticamente cualquier archivo de salida existente, pero crea los directorios superiores necesarios antes de ejecutar una genrule. También quita cualquier archivo de salida en caso de una falla.
Consejos generales
- Asegúrate de que las herramientas que ejecute una genrule sean deterministas y herméticas. No deben escribir marcas de tiempo en los resultados y usar un orden estable para los conjuntos y mapas, además de escribir solo rutas de acceso de archivos relativas al resultado, sin rutas de acceso absolutas. Si no se sigue esta regla, se producirá un comportamiento de compilación inesperado (Bazel no volverá a compilar una genrule que creas que lo haría) y se degradará el rendimiento de la caché.
- Usa
$(location)
de manera exhaustiva para los resultados, las herramientas y las fuentes. Debido a la separación de los archivos de salida para diferentes opciones de configuración, las genrules no pueden depender de rutas de acceso codificadas o absolutas. - Escribe una macro de Starlark común en caso de que se usen las mismas reglas de generación de reglas o que sean 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úrese de que el código de salida indique correctamente el éxito o el fracaso de la genrule.
- No escribas mensajes informativos en stdout o stderr. Si bien es útil para la depuración, esto puede convertirse en ruido con facilidad, por lo que una genrule exitosa debe ser silenciosa. Por otro lado, una regla general que falla debe emitir mensajes de error buenos.
$$
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 symlink creada por las reglas de generación y su control de dependencias de los directorios no es adecuado.
- Cuando se hace referencia a la genrule en otras reglas, puede usar la etiqueta de genrule o las de archivos de salida individuales. A veces, el enfoque es más legible, mientras que el otro, si haces referencia a los resultados por el nombre en el
srcs
de una regla de consumo, evitarás obtener accidentalmente otros resultados de la genrule, pero puede ser tedioso si la genrule produce muchos resultados.
Ejemplos
En este ejemplo, se genera foo.h
. No hay fuentes porque el comando no toma ninguna entrada. El “binario” que ejecuta el comando es una secuencia de comandos perl en el mismo paquete que la 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 funciona; en este ejemplo, se usa el último para fines 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 esta orientación. Puedes hacer referencia a esta regla por nombre en la sección srcs o deps de otras reglas de BUILD . Si la regla genera archivos fuente, 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 archivos de salida se interpretan en relación con el paquete.
Si 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 variable"Make".
cmd_bash , cmd_ps y cmd_bat , si ninguno es aplicable.
Si la longitud de la línea de comandos supera el límite de la plataforma (64,000 en Linux/macOS, 8K en Windows), entonces 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 mayor prioridad que |
cmd_bat
|
Este atributo tiene mayor prioridad que
|
cmd_ps
|
Este atributo tiene mayor prioridad que
Para que PowerShell sea más fácil de usar y menos propenso a errores, ejecutamos los siguientes comandos a fin de configurar el entorno antes de ejecutar el comando de PowerShell en genrule.
|
exec_tools
|
tools .
Hubo un período en el que |
executable
|
Si estableces esta marca como verdadera, el resultado será un archivo ejecutable y se podrá ejecutar con el comando No se admite la declaración de dependencias de datos para el ejecutable generado. |
local
|
Si se configura como verdadera, esta opción fuerza la ejecución de esta
Esto equivale a proporcionar la etiqueta “local” ( |
message
|
Un mensaje de progreso que se imprimirá a medida que se ejecute este paso de compilación. De forma predeterminada, el mensaje es "Generando output" (o algo insatisfactorio), pero puedes proporcionar uno más específico. Usa este atributo en lugar de |
output_licenses
|
common attributes
.
|
output_to_bindir
|
Si se configura como verdadera, esta opción hace que los archivos de salida se escriban en el directorio |
tools
|
El sistema de compilación garantiza que estos requisitos previos se compilen antes de ejecutar el comando genrule, se compilan mediante la configuración exec, ya que estas herramientas se ejecutan como parte de la compilación. La ruta de acceso de un
Cualquier |
paquete_de_pruebas
Ver fuente de la reglatest_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 los humanos consideran "útiles". 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 incluidos de forma transitiva por el objetivo //some/test:suite
(que llamamos "expansión de test_suite"). Luego, Blaze compila y prueba esos destinos.
Ejemplos
Un conjunto de pruebas para ejecutar todas las pruebas pequeñas en el paquete actual.
test_suite( name = "small_tests", tags = ["small"], )
Un conjunto de pruebas que ejecuta un conjunto específico de pruebas:
test_suite( name = "smoke_tests", tests = [ "system_unittest", "public_api_unittest", ], )
Un conjunto 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 esta orientación. |
tags
|
Las etiquetas que comienzan con un carácter "-" se consideran etiquetas negativas. El carácter "-" anterior no se considera parte de la etiqueta, por lo que una etiqueta de conjunto de "-small" coincide con el tamaño "small" de una prueba. Todas las demás etiquetas se consideran positivas. De forma opcional, para que las etiquetas positivas sean más explícitas, las etiquetas también pueden comenzar con el carácter "+", que no se evaluará como parte del texto de la etiqueta. Solo facilita la lectura de las distinciones positivas y negativas. 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 comprobación de errores en busca de dependencias en las pruebas filtradas, sino que las dependencias en las pruebas omitidas deben ser legales (p.ej., no están bloqueadas por restricciones de visibilidad).
La palabra clave de la etiqueta
Ten en cuenta que el objeto
Si necesitas un |
tests
|
Se acepta cualquier
Si no se especifica el atributo |