Reglas generales

Reglas

• alias
• config_setting
• filegroup
• genquery
• genrule
• starlark_doc_extract
• 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 en una regla.

El alias solo funciona para los destinos "normales". En particular, package_group y test_suite no pueden tener alias.

Los alias pueden ser útiles en repositorios grandes en los que cambiar el nombre de un destino requeriría realizar cambios en muchos archivos. También puedes usar la regla de alias para almacenar una llamada a la función select si deseas reutilizar esa lógica para varios destinos.

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 testonly en el alias; en su lugar, se usa el atributo testonly 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_suite con un solo destino en su atributo tests.
• Cuando se definen grupos de entornos, no se admiten los alias para las reglas de 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 propósito de activar atributos configurables. Consulta select para obtener información sobre cómo consumir esta regla y Configurable attributes para obtener una descripción general de la función general.

Ejemplos

La siguiente coincidencia se aplica a cualquier compilación que establezca --compilation_mode=opt o -c opt (ya sea de forma explícita en la línea de comandos o de forma implícita desde los archivos .bazelrc):

  config_setting(
      name = "simple",
      values = {"compilation_mode": "opt"}
  )
  

La siguiente coincidencia se aplica a cualquier compilación que tenga como objetivo 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 coincidencia se aplica a 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 coincidencia se aplica a cualquier compilación que tenga como objetivo una plataforma con una arquitectura x86_64 y la versión 2.25 de glibc, suponiendo la existencia de un constraint_value con la etiqueta //example:glibc_2_25. Ten en cuenta que una plataforma sigue 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",
      ]
  )
  

Notas

• Consulta select para saber qué sucede cuando varios config_setting coinciden con el estado de configuración actual.
• En el caso de las marcas que admiten formas abreviadas (p. ej., --compilation_mode en lugar de -c), las definiciones de values deben usar la forma completa. Estas invocaciones coinciden automáticamente con cualquiera de las dos formas.
• Si una marca toma varios valores (como --copt=-Da --copt=-Db o una marca de Starlark con tipo de 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 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 segundo). Pero --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"]. Verifica las definiciones de las marcas y prueba tus condiciones con cuidado para verificar las expectativas exactas.

• Si necesitas definir condiciones que no se modelan con marcas de compilación integradas, usa marcas definidas por Starlark. También puedes usar --define, pero ofrece una compatibilidad más débil y no se recomienda. Consulta aquí para obtener más información.
• Evita repetir definiciones de config_setting idénticas en diferentes paquetes. En su lugar, haz referencia a un config_setting común definido 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 establecer al menos uno para cualquier config_setting determinado.

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",
                })
          

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

Se recomienda usar filegroup en lugar de hacer referencia a directorios directamente. Esta última opción no es confiable, ya que el sistema de compilación no tiene conocimiento completo de todos los archivos que se encuentran debajo del directorio, por lo que es posible que no vuelva a compilar cuando cambien estos archivos. Cuando se combina con glob, filegroup puede garantizar que el sistema de compilación conozca explícitamente todos los archivos.

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 glob para analizar 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

genquery

genquery(name, deps, data, compatible_with, compressed_output, 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 consultas 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 búsquedas que incumplan 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 sencilla de asegurarse de que esto no suceda es mencionar las mismas etiquetas en el alcance que en la expresión de búsqueda.

La única diferencia entre las consultas permitidas aquí y en la línea de comandos es que no se permiten las consultas que contienen especificaciones de destino con comodines (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, segundo, porque los archivos BUILD no admiten dependencias de comodín (p.ej., deps=["//a/..."] no está permitido).

El resultado de genquery se ordena lexicográficamente para aplicar un resultado determinístico, excepto en el caso de --output=graph|minrank|maxrank o cuando somepath se usa como la función de nivel superior.

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

genrule

genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, 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 de 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, podrías ejecutar un comando de Bash de una sola línea. Sin embargo, si necesitas compilar archivos C++, usa las reglas cc_* existentes, ya que todo el trabajo pesado ya se hizo por ti.

Ten en cuenta que genrule requiere un shell para interpretar el argumento de comando. También es fácil hacer referencia a programas arbitrarios disponibles en PATH, pero esto hace que el comando no sea hermético y es posible que no se pueda reproducir. Si solo necesitas ejecutar una sola herramienta, considera usar run_binary en su lugar.

No uses 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 de ejecución (las dos pueden ser diferentes). Si necesitas una regla de prueba de propósito 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 a menudo se usan después de la compilación, para la implementación o las pruebas. Considera el ejemplo de compilar 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 de C (si se compiló desde la fuente) sí debe 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 para describir las máquinas en las que se supone que se ejecutará el resultado de la compilación. Proporciona opciones para configurar cada uno de estos elementos 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 forma adecuada: Los srcs se compilan (si es necesario) para la configuración de destino. Los tools se compilan para la configuración de ejecución, y la salida se considera para la configuración de destino. También proporciona variables de "Make" 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 controlar las reglas dependientes, pero este nivel de automatización no es posible para las genrules. Las reglas de generación funcionan puramente a nivel de archivos y runfiles.

Casos especiales

Compilación de ejecutable a ejecutable: En algunos casos, el sistema de compilación necesita ejecutar genrules de modo que la salida también se pueda ejecutar durante la compilación. Si, por ejemplo, una regla genrule compila algún compilador personalizado que luego usa otra regla genrule, la primera debe generar su resultado para la configuración de ejecución, ya que ahí es donde se ejecutará el compilador en la otra regla genrule. En este caso, el sistema de compilación hace lo correcto automáticamente: compila srcs y outs de la primera regla genrule para la configuración de ejecución en lugar de la configuración de destino. Consulta el manual del usuario para obtener más información.

JDK y herramientas de C++: Para usar una herramienta del JDK o del 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 con un shell de Bash configurado para fallar cuando falla un comando o una canalización, con set -e -o pipefail.

La herramienta de compilación ejecuta el comando de Bash en un entorno de proceso saneado que define solo 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 de 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 principales necesarios antes de ejecutar una genrule. También quita los archivos de salida en caso de falla.

Asesoramiento general

• Asegúrate de que las herramientas que ejecuta una regla genrule sean determinísticas 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 relativas a los archivos en la salida, no rutas de acceso absolutas. No seguir esta regla generará un comportamiento inesperado de la compilación (Bazel no recompilará una regla genrule que creías que recompilaría) y degradará el rendimiento de la caché.
• Usa $(location) de forma extensiva para las salidas, las herramientas y las fuentes. Debido a la segregación de los archivos de salida para diferentes configuraciones, las reglas de generación no pueden depender de rutas de acceso codificadas o absolutas.
• Escribe una macro de Starlark común en caso de que se usen genrules iguales o muy similares en varios lugares. Si la regla 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 si la regla genrule se ejecutó correctamente o no.
• No escribas mensajes informativos en stdout o stderr. Si bien es útil para la depuración, esto puede convertirse fácilmente en ruido. Una genrule exitosa debería ser silenciosa. Por otro lado, una genrule que falla debe emitir buenos mensajes de error.
• $$ 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 vínculos simbólicos y directorios. Bazel no copia la estructura de directorios o vínculos simbólicos que crean las genrules, y su verificación de dependencias de directorios no es confiable.
• Cuando hagas referencia a la regla genrule en otras reglas, puedes usar la etiqueta de la regla 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 las salidas por nombre en el srcs de una regla de consumo evitará la selección no intencional de otras salidas de la regla genrule, pero puede ser tedioso si la regla genrule produce muchas salidas.

Ejemplos

En este ejemplo, se genera foo.h. No hay fuentes, ya que el comando no toma ninguna entrada. El "ejecutable" 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 también funcionaría usar $(SRCS) en lugar de directivas $(location) explícitas. En este ejemplo, se usa la última opción 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

starlark_doc_extract

starlark_doc_extract(name, deps, src, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility)

starlark_doc_extract() extrae la documentación de las reglas, las funciones (incluidas las macros), los aspectos y los proveedores definidos o reexportados en un archivo .bzl o .scl determinado. El resultado de esta regla es un archivo ModuleInfo binario .proto, como se define en stardoc_output.proto en el árbol de origen de Bazel.

Objetivos de salida implícitos

• name.binaryproto (la salida predeterminada): Un prototipo binario de ModuleInfo.
• name.textproto (solo se compila si se solicita de forma explícita): Es la versión en formato .proto de name.binaryproto.

Advertencia: No se garantiza que el formato de salida de esta regla sea estable. Está diseñado principalmente para el uso interno de Stardoc.

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 registrarte", "pruebas de estrés 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 destino //some/test:suite (a esto lo llamamos "expansión de test_suite"), luego Blaze compila y prueba esos destinos.

Ejemplos

Es 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",
    ],
)

Es 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