Reglas generales

Reglas

• alias
• config_setting
• grupo de archivos
• genquery
• genrule
• test_suite

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 a la regla.

La asignación de alias solo funciona para objetivos “normales”. En particular, package_group y test_suite no pueden tener un alias.

La regla de alias tiene su propia declaración de visibilidad. En cualquier otro aspecto, se comporta como la regla a la que hace referencia (p.ej., se ignora solo prueba en el alias y en su lugar se usa solo prueba de la regla a la que 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_suite con un solo objetivo en su atributo tests.
• 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

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 Seleccionar para conocer cómo consumir esta regla y Atributos configurables para obtener una descripción general de la función general.

Ejemplos

La siguiente compilación 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 código coincide con cualquier compilación que se oriente 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"
      }
  )
  

La siguiente compilación 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 archivos .bazelrc):

  config_setting(
      name = "my_custom_flag_is_set",
      flag_values = { "//custom_flags:foo": "1" },
  )
  

Lo siguiente coincide con cualquier compilación que se oriente 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 una plataforma igual coincide si define valores de restricción adicionales aparte de estos dos.

  config_setting(
      name = "64bit_glibc_2_25",
      constraint_values = [
          "@platforms//cpu:x86_64",
          "//example:glibc_2_25",
      ]
  )
  

Notas

• Consulta seleccionar para ver 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 de values deben usar la forma completa. Estos coinciden automáticamente con las invocaciones con cualquiera de los 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 parte 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 las 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 que values = { "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 y ios_multi_cpus=a --ios_multi_cpus=b producen ["a", "b"]. Revisa las definiciones de las marcas y prueba las condiciones con atención para verificar expectativas exactas.

• Si necesitas definir condiciones que no se modelan con marcas de compilación integradas, usa las marcas definidas por Starlark. También puedes usar --define, pero esta opción ofrece una compatibilidad menor y no se recomienda. Consulta este vínculo para obtener más información.
• Evita repetir definiciones de config_setting idénticas en paquetes diferentes. En su lugar, haz referencia a un elemento config_setting común que se definió en un paquete canónico.
• values, define_values y constraint_values se pueden usar en cualquier combinación en el mismo config_setting, pero se debe configurar al menos uno para cualquier config_setting.

Argumentos

            config_setting(
                name = "a_and_b",
                values = {
                    "define": "a=1",
                    "define": "b=2",
                })
          

            config_setting(
                name = "a_and_b",
                define_values = {
                    "a": "1",
                    "b": "2",
                })
          

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 un conjunto de destinos. Luego, se puede hacer referencia a ellos desde otras reglas.

Se recomienda usar filegroup en lugar de hacer referencia a directorios directamente. Este último no es válido, ya que el sistema de compilación no tiene conocimiento absoluto 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 de forma explícita todos los archivos.

Ejemplos

Para crear un filegroup que contenga dos archivos fuente, haz lo siguiente:

filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "some/subdirectory/another_file.txt",
    ],
)

También puedes usar un glob para generar 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

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 lenguaje de consulta de Blaze y vuelca el resultado en un archivo.

Para mantener la coherencia de la compilación, 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 no se especifica strict o si es verdadero (si strict es falso, los objetivos fuera del alcance solo 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 y en la expresión de la consulta.

La única diferencia entre las consultas que se permiten aquí y en la línea de comandos 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 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, debido a que los archivos BUILD no admiten dependencias de comodín (p.ej., no se permite deps=["//a/..."]).

El resultado de la genquery se ordena usando --order_output=full para aplicar la salida 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 destino especificado en un archivo.

genquery(
    name = "kiwi-deps",
    expression = "deps(//kiwi:kiwi_lib)",
    scope = ["//kiwi:kiwi_lib"],
)

Argumentos

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 elemento genrule genera uno o más archivos con un comando Bash definido por el usuario.

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 una sola línea de Bash. Sin embargo, si necesitas compilar archivos C++, cumple con las reglas cc_* existentes, ya que todo el trabajo pesado ya se realizó por ti.

No uses una genrule para ejecutar pruebas. Hay 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 una vez que se completa la compilación y en la arquitectura de destino, mientras que las genrules se ejecutan durante la compilación y en la arquitectura host (es posible que ambas sean diferentes). Si necesitas una regla de prueba de 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 las genrules se ejecutan durante una compilación, sus resultados suelen usarse después de la compilación para la implementación o pruebas. Considera el ejemplo de 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) 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 supone 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 separados para evitar conflictos.

En el caso de las genrules, el sistema de compilación garantiza que las dependencias se compilen de manera adecuada: srcs se compilan (si es necesario) para la configuración de target, tools se compilan para la configuración del host, y el resultado se considera para la configuración del destino. También proporciona las variables "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 manejar las reglas dependientes, pero este nivel de automatización no es posible para las genrules. Las genrules funcionan únicamente a nivel de archivo y runfiles.

Casos especiales

Compilación de host y host: En algunos casos, el sistema de compilación necesita ejecutar genrules de modo que el resultado también se pueda ejecutar durante la compilación. Por ejemplo, si una genrule compila un compilador personalizado que otra genrule luego usará, el primero deberá producir su resultado para la configuración del 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 la 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 el conjunto de compiladores de C++, el sistema de compilación proporciona un conjunto de variables para usar. Consulta la variable"Make" para obtener más detalles.

Entorno de Genrule

El comando genrule se ejecuta mediante una shell Bash configurada para fallar cuando falla un comando o una canalización mediante 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 algunas más. 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 siguiente compilación.

Un comando genrule no debería acceder a la red, excepto para conectar procesos que sean secundarios del comando, 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 cualquier archivo de salida en caso de falla.

Consejos generales

• Asegúrate de que las herramientas ejecutadas por una regla general sean deterministas y herméticas. No deben escribir marcas de tiempo en el resultado y deben usar un orden estable para conjuntos y mapas, además de escribir solo rutas de acceso relativas a archivos en el resultado, sin rutas absolutas. Si no se sigue esta regla, se generará un comportamiento de compilación inesperado (Bazel no volverá a compilar una regla de gen. que pensabas que lo haría) y degradará el rendimiento de la caché.
• Usa $(location) de manera extensiva para resultados, herramientas y fuentes. Debido a la segregación de los archivos de salida para diferentes configuraciones, las genrules no pueden depender de rutas codificadas o absolutas.
• Escribe una macro de Starlark común en caso de que se usen las mismas genrules o 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 la falla de la genrule.
• No escribas mensajes informativos en stdout ni stderr. Si bien es útil para la depuración, puede convertirse fácilmente en ruido; una genrule exitosa debe ser silenciosa. Por otro lado, una genrule que falla debe emitir mensajes de error correctos.
• $$ evaluates to a $, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such as ls $(dirname $x), one must escape it thus: ls $$(dirname $$x).
• Evita crear enlaces simbólicos y directorios. Bazel no copia la estructura de directorio/symlink creada por genrules y su verificación de dependencias de directorios no es válida.
• Cuando haces referencia a genrule en otras reglas, puedes usar la etiqueta de genrule o las etiquetas de archivos de salida individuales. A veces, un enfoque es más legible, a veces el otro: hacer referencia a las salidas por nombre en el srcs de una regla de consumo evitará seleccionar otras salidas de la genrule de manera involuntaria, 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 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 el uso de $(SRCS) en lugar de directivas $(location) explícitas también funcionaría. En este ejemplo, se usan estas últimas 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

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 de registrar”, “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 en el objetivo //some/test:suite (lo llamamos "expansión de test_suite") y, luego, Blaze compila y prueba esos objetivos.

Ejemplos

Un paquete de pruebas para ejecutar todas las pruebas pequeñas 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 paquete de pruebas para ejecutar todas las pruebas del paquete actual que no son inestables.

test_suite(
    name = "non_flaky_test",
    tags = ["-flaky"],
)

Argumentos