Reglas
alias
alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)
La regla alias crea otro nombre con el que se puede hacer referencia a una regla.
La asignación de alias solo funciona para “normal” objetivos. En particular, package_group
y test_suite no pueden tener un 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., testonly en el alias se ignora; el testonly-ness de la regla a la que se hace referencia) con algunas excepciones menores:
-
Las pruebas no se ejecutan si su alias se menciona en la línea de comandos. Cómo definir un alias
que ejecute la prueba a la que se hace referencia, usa un
test_suite. regla con un único destino en sutests. -
Cuando se definen grupos de entornos, los alias de las reglas
environmentno son no es compatible. No se admiten en la línea de comandos de--target_environment. la opción de protección de datos.
Ejemplos
filegroup(
name = "data",
srcs = ["data.txt"],
)
alias(
name = "other",
actual = ":data",
)
Argumentos
| Atributos | |
|---|---|
name |
Un nombre único para este destino. |
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) para con el objetivo de activar atributos configurables. Consulta seleccionar para cómo consumir esta regla y Atributos configurables para obtener una descripción general de las funciones generales.
Ejemplos
La 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 archivos .bazelrc):
config_setting(
name = "simple",
values = {"compilation_mode": "opt"}
)
El siguiente 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"
}
)
La siguiente coincide con cualquier compilación que establezca
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
.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 arquitectura x86_64 y glibc
versión 2.25, suponiendo la existencia de un constraint_value con etiqueta
//example:glibc_2_25 Ten en cuenta que una plataforma coincide si define
restricciones más allá de estos dos.
config_setting(
name = "64bit_glibc_2_25",
constraint_values = [
"@platforms//cpu:x86_64",
"//example:glibc_2_25",
]
)
config_setting no coincide con las marcas de línea de comandos de nivel superior; aún puede coincidir
algunos objetivos de compilación.
Notas
- Consulta seleccionar para saber qué sucede cuando varias
config_settingcoincide con el estado de configuración actual. - Para marcas que admiten formas abreviadas (p. ej.,
--compilation_modefrente a-c), las definiciones devaluesdeben usar el formato completo. Estos se configuran automáticamente hacer coincidir las invocaciones con cualquiera de las dos formas. -
Si una marca toma múltiples valores (como
--copt=-Da --copt=-Dbo una etiqueta marca de Starlark),values = { "flag": "a" }coincide si"a"es presente en cualquier parte de la lista.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 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 tanto,values = { "copt": "a,b" }coincide con el primero, pero no con el último). Pero--ios_multi_cpus(para las reglas de Apple) hace:-ios_multi_cpus=a,byios_multi_cpus=a --ios_multi_cpus=bproducen["a", "b"]. Verifica las definiciones de las marcas y prueba condiciones con atención para verificar las expectativas exactas. - Si necesitas definir condiciones que no estén modeladas con marcas de compilación integradas, usa
Marcas definidas por Starlark. También puedes usar
--define, pero este ofrece un valor más débil. asistencia y no se recomienda. Consulta aquí para obtener más información. - Evita repetir definiciones idénticas de
config_settingen diferentes paquetes. En su lugar, haz referencia a unconfig_settingcomún que se definió en un paquete canónico. values:define_valuesyconstraint_valuespuede usarse en cualquier combinación en el mismoconfig_setting, pero al menos uno debe se puede establecer para cualquierconfig_setting.
Argumentos
| Atributos | |
|---|---|
name |
Un nombre único para este destino. |
constraint_values
|
constraint_values que debe especificar la plataforma de segmentación
para que coincidan con esta config_setting. (La plataforma de ejecución no es
considerado aquí). Se ignorará cualquier valor de restricción adicional que tenga la plataforma. Consulta
Atributos de compilación configurables para obtener más detalles.
En 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 tecla (
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 porque las marcas definidas por el usuario se referencian como etiquetas, mientras que se hace referencia a las marcas integradas como cadenas arbitrarias. |
values
|
Esta regla hereda la configuración del destino configurado que
hace referencia a él en una sentencia Para mayor comodidad, los valores de configuración se especifican como marcas de compilación (sin
el Si una marca no se establece 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 configurar varias veces en la línea de comandos (p.ej.,
|
grupo de archivos
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 destinos.
Luego, otras reglas pueden hacer referencia a ellas.
Se recomienda usar filegroup en lugar de hacer referencia a directorios directamente.
Esta última opción no tiene buen sonido, ya que el sistema de compilación no tiene conocimientos completos 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 todos los archivos se
que el sistema de compilación conoce explícitamente.
Ejemplos
Para crear un filegroup que conste de 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 agrupar un directorio testdata:
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 destino. |
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 ese implementación de la regla. |
consulta generativa
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 archivo
Usa el lenguaje de consulta Blaze y vuelca el resultado.
en un archivo.
Para mantener la coherencia de la compilación, solo se permite que la consulta visite
el cierre transitivo de los objetivos especificados en el 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 se omitirán con una advertencia). El
la forma más sencilla de asegurarse de que esto no suceda es mencionar las mismas etiquetas
en el alcance, como en la expresión de la consulta.
La única diferencia entre las consultas permitidas aquí y en el comando
es que las consultas que contienen especificaciones de destino comodín (p.ej.,
//pkg:* o //pkg:all) no se permiten aquí.
Esto se debe a dos aspectos: en primer lugar, porque genquery tiene
para especificar un alcance para evitar objetivos fuera del cierre transitivo del
para influir en su resultado; y, en segundo lugar, porque archivos BUILD
No admiten dependencias de comodín (p. ej., deps=["//a/..."]).
no se permite).
El resultado de la consulta general se ordena con --order_output=full en
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 etiquetas en el cierre transitivo de la un destino especificado a un archivo.
genquery(
name = "kiwi-deps",
expression = "deps(//kiwi:kiwi_lib)",
scope = ["//kiwi:kiwi_lib"],
)
Argumentos
| Atributos | |
|---|---|
name |
Un nombre único para este destino. |
expression
|
:b en este atributo en el archivo a/BUILD hará referencia al elemento
objetivo //:b.
|
opts
|
bazel query. Algunas opciones de consulta no están permitidas
aquí: --keep_going, --query_file, --universe_scope,
--order_results y --order_output. Opciones no especificadas aquí
tendrá 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)
Una 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 frase en Bash. Sin embargo, si necesitas compilar archivos C++,
a las reglas existentes de cc_* porque ya se hizo todo el trabajo pesado
por ti.
No uses una genrule para ejecutar pruebas. Existen dispensaciones especiales para pruebas
resultados, 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 completa la compilación y en la arquitectura de destino, mientras que las genrules se ejecutan durante
en la compilación y en la arquitectura del host (es posible que ambos sean diferentes). Si necesitas un perfil
regla de prueba, usa sh_test.
Consideraciones sobre la compilación cruzada
Consulta el manual del usuario para obtener más información sobre compilación cruzada.
Si bien las genrules se ejecutan durante una compilación, sus resultados suelen usarse después de la compilación, para la implementación o y pruebas. Considera el ejemplo de compilación de código C para un microcontrolador: el compilador acepta 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 compilarla, pero el compilador C (si se compiló desde el código fuente) debe 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 encuentra el resultado de la compilación que se suponía que debía ejecutarse. Proporciona opciones para configurar cada uno de ellos y segrega en directorios separados para evitar conflictos.
En el caso de las genrules, el sistema de compilación garantiza que las dependencias se compilen de forma correcta:
Se compilan srcs (si es necesario) para la configuración de destino.
Los tools se compilan para la configuración del host, y la salida se considera como
para la configuración de destino. También proporciona
"Marca" variables que los comandos de genrule pueden pasar a las herramientas correspondientes.
Genrule no define ningún atributo deps de forma intencional; se usan otras reglas integradas
metainformación dependiente del idioma que se pasa entre las reglas para determinar automáticamente cómo
manejan reglas dependientes, pero este nivel de automatización no es posible para las genrules. Funcionan las reglas generales
solo a nivel de archivo y runfiles.
Casos especiales
Compilación host-host: En algunos casos, el sistema de compilación debe ejecutar genrules para que
El resultado final también se puede ejecutar durante la compilación. Si, por ejemplo, una genrule compila algún compilador personalizado
que luego usa otra genrule, la primera debe producir su salida para el
de host, ya que allí es donde se ejecutará el compilador en la otra genrule. En este caso,
el sistema de compilación hace lo correcto automáticamente: compila el srcs y
outs de la primera genrule para la configuración del host en lugar del destino
configuración. Consulta el manual del usuario para obtener más información
información.
JDK y Herramientas de C++: Para usar una herramienta del JDK o el conjunto del compilador C++, el sistema de compilación proporciona un conjunto de variables para usar. Ver "Marca" variable para más detalles.
Entorno de Genrule
Una shell Bash configurada para fallar cuando se ejecuta un comando
o si falla una canalización, a través de set -e -o pipefail.
La herramienta de compilación ejecuta el comando Bash en un entorno de procesos depurado que
define solo variables principales, como PATH, PWD,
TMPDIR y algunos más.
Para garantizar que las compilaciones sean reproducibles, la mayoría de las variables definidas en la 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 se elementos secundarios del comando, aunque actualmente esto no se aplica de manera forzosa.
El sistema de compilación borra automáticamente los archivos de salida existentes, pero crea los archivos superiores necesarios directorios antes de que ejecute una genrule. También quita todos los archivos de salida en caso de falla.
Consejos generales
- Asegúrate de que las herramientas ejecutadas por una genrule sean deterministas y herméticas. No deben escribir marcas de tiempo en su salida, y deben usar un orden estable para conjuntos y mapas, así como solo escribe rutas de acceso de archivo relativas al resultado, no rutas absolutas. Si no sigues esta regla, genera un comportamiento de compilación inesperado (Bazel no vuelve a compilar una genrule que pensabas que podría tener) y degradar el rendimiento de la caché.
- Usa
$(location)ampliamente para resultados, herramientas y fuentes. Debido a la de archivos de salida para diferentes configuraciones, genrules no puede depender de un código y/o rutas absolutas. - Escribe una macro de Starlark común en caso de que se usen genrules iguales o muy similares en varios lugares. Si la genrule es compleja, considera implementarla en una secuencia de comandos o como Regla de Estelaria. Esto mejora la legibilidad y la capacidad de prueba.
- Asegúrate de que el código de salida indique correctamente el éxito o el fracaso de la genrule.
- No escribas mensajes informativos en stdout ni stderr. Aunque es útil para la depuración, esto puede convertirse fácilmente en ruido; para que una genrule sea exitosa debe ser silenciosa. Por otro lado, una genrule con fallas debería emitir buenos mensajes de error.
$$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 el directorio o symlink. La estructura creada por genrules y su verificación de dependencias de directorios no son sólidas.
- Cuando hagas referencia a la genrule en otras reglas, podrás usar su etiqueta
las etiquetas de los archivos de salida individuales. A veces, el único enfoque es más legible
Otro: hacer referencia a los resultados por nombre en el
srcsde una regla de consumo evitará Tomar involuntariamente otros resultados de la regla generativa, pero puede ser tedioso si esta produce muchas salidas.
Ejemplos
En este ejemplo, se genera foo.h. No hay fuentes, porque el comando no toma
cualquier 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 las salidas de otro genrule. Ten en cuenta que usar $(SRCS) en su lugar
de directivas $(location) explícitas también funcionaría; este ejemplo usa el último para
el solo fin de la 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 destino. Puedes hacer referencia a esta regla por su nombre en la Sección srcs o deps de otros BUILD
las reglas de firewall. Si la regla genera archivos de origen, debes usar el
atributo srcs.
|
srcs
|
Estos atributos no son adecuados para enumerar las herramientas que ejecuta
El sistema de compilación garantiza que se compilen estos requisitos previos antes de ejecutar la regla general
comando; se compilan con la misma configuración que la solicitud de compilación original. El
los nombres de los archivos de estos requisitos están disponibles para el comando como
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 configura 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 "Marca" de variables.
cmd_bash, cmd_ps y cmd_bat.
si no corresponde ninguna de ellas.
Si la longitud de la línea de comandos supera el límite de la plataforma (64 K en Linux/macOS, 8K en Windows),
Luego, genrule escribirá el comando en una secuencia de comandos y la ejecutará para solucionar el problema. Esta
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 el siguiente comando: para configurar el entorno antes de ejecutar el comando de PowerShell en genrule.
|
exec_tools
|
tools, excepto que estas dependencias
se configurará para la plataforma de ejecución de la regla en lugar de la configuración del host.
Esto significa que las dependencias de exec_tools no están sujetas a la misma
limitaciones como dependencias en tools. En particular, no están obligados a
usan la configuración del host para sus propias dependencias transitivas. Consulta
tools para obtener más detalles.
El equipo de Blaze está migrando todos los usos de |
executable
|
Si estableces esta marca como verdadera, el resultado es un archivo ejecutable y se podrá ejecutar mediante el
Comando No se admite la declaración de dependencias de datos para el ejecutable generado. |
local
|
Si se establece como verdadera, esta opción obliga a que este
Esto equivale a proporcionar valores "locales" como etiqueta ( |
message
|
Un mensaje de progreso que se imprimirá a medida que se ejecute este paso de compilación. De forma predeterminada, el
el mensaje es “Generando un resultado” (o algo igualmente insólito), pero puedes proporcionar una
una más específica. Usar este atributo en lugar de |
output_licenses
|
common attributes
.
|
output_to_bindir
|
Si se establece como verdadera, esta opción hace que los archivos de salida se escriban en |
tools
|
El sistema de compilación garantiza que estos requisitos se compilen antes de ejecutar el comando genrule.
se compilan mediante el host
configuración, ya que estas herramientas se ejecutan como parte de la compilación. La ruta de un
el objetivo individual de
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" a los humanos. Esta
permite que los proyectos definan conjuntos de pruebas, como “pruebas que debes ejecutar antes del registro”, “nuestro
pruebas de esfuerzo del proyecto" o "todas las pruebas pequeñas". El comando blaze test respeta este orden.
de la organización: para una invocación como blaze test //some/test:suite, Blaze primero
enumera todos los objetivos de prueba incluidos transitivamente en el objetivo //some/test:suite (se
denominada "expansión del paquete de prueba"), luego Blaze compila y prueba esos objetivos.
Ejemplos
Un conjunto de pruebas para ejecutar todas las pruebas de nivel inferior en el paquete actual.
test_suite(
name = "small_tests",
tags = ["small"],
)
Un paquete 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 que no sean inestables en el paquete actual.
test_suite(
name = "non_flaky_test",
tags = ["-flaky"],
)
Argumentos
| Atributos | |
|---|---|
name |
Un nombre único para este destino. |
tags
|
Etiquetas que comienzan con “-” se consideran etiquetas negativas. El "-" anterior carácter no se considera parte de la etiqueta, por lo que una etiqueta de paquete de “-small” coincide con el valor “pequeño” de una prueba de tamaño del ensamble. Todas las demás etiquetas se consideran con etiquetas positivas. De manera opcional, para que las etiquetas positivas sean más explícitas, las etiquetas también pueden comenzar con el "+" que no se evaluará como parte del texto de la etiqueta. Integra solo hace que la distinción entre positiva y negativa sea más fácil de leer. Probar solo las reglas que coincidan con todas las etiquetas positivas y ninguna de las negativas las etiquetas se incluirán en el paquete de pruebas. Ten en cuenta que esto no significa que la comprobación de errores en el caso de las dependencias de pruebas filtradas; las dependencias Las pruebas tambié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 no se especifica el atributo |