Ya comenzó el registro para BazelCon 2024

Se usó la API de Cloud Translation para traducir esta página.

Reglas generales

7.3 · 7.2 · 7.1 · 7.0 · 6.5

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.

El uso de alias solo funciona para los destinos "normales". En particular, no se pueden crear alias para package_group ni test_suite.

La asignación de alias puede ser útil 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 volver a usar esa lógica para varios objetivos.

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 ignora en el alias de prueba; en su lugar se usa el carácter de solo 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_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

Atributos

Atributos
`name`	Name; obligatorio Un nombre único para este destino.
`actual`	Label; obligatorio El objetivo al que hace referencia este alias. No es necesario que sea una regla, también puede ser un archivo de entrada.

name

Name; obligatorio

Un nombre único para este destino.

actual

Label; obligatorio

El objetivo al que hace referencia este alias. No es necesario que sea una regla, también puede ser un archivo de entrada.

config_setting

Ver la fuente de la regla

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 activar atributos configurables. Consulta la selección para saber cómo consumir esta regla y la sección Atributos configurables para obtener una descripción general de la función general.

Ejemplos

La siguiente coincide con cualquier compilación que configure --compilation_mode=opt o -c opt (ya sea de manera explícita en la línea de comandos o implícitamente desde 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"
      }
  )

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

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_setting coinciden con el estado de configuración actual.
En el caso de las marcas que admiten formas abreviadas (p. ej., --compilation_mode en comparación con -c), las definiciones de values deben 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=-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 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). 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"]. 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_setting idénticas en diferentes paquetes. En su lugar, haz referencia a un 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 determinado.

Argumentos

Atributos
`name`	Nombre: Obligatorio Un nombre único para este destino.
`constraint_values`	Lista de etiquetas; no configurable; el valor predeterminado es `[]` Es el conjunto mínimo de `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. Si dos `config_setting` coinciden en el mismo `select` y uno tiene las mismas marcas y `constraint_setting` que el otro, además de otras adicionales, se elige el que tiene más parámetros de configuración. Esto se conoce como "especialización". Por ejemplo, un `config_setting` que coincide con `x86` y `Linux` especializa un `config_setting` que coincide con `x86`. Si dos `config_setting` coinciden y ambos tienen `constraint_value` que no están presentes en el otro, esto es un error.
`define_values`	Diccionario: Cadena -> Cadena; no configurable; el valor predeterminado es `{}` Es igual que `values`, pero específicamente para la marca `--define`. `--define` es especial porque su sintaxis (`--define KEY=VAL`) significa que `KEY=VAL` es un valor desde la perspectiva de la marca de Bazel. Esto significa lo siguiente: config_setting( name = "a_and_b", values = { "define": "a=1", "define": "b=2", }) no funciona porque la misma clave (`define`) aparece dos veces en el diccionario. Este atributo resuelve ese problema: config_setting( name = "a_and_b", define_values = { "a": "1", "b": "2", }) coincide correctamente con `bazel build //foo --define a=1 --define b=2`. `--define` aún puede aparecer en `values` con la sintaxis de marca normal y se puede combinar libremente con este atributo, siempre que las claves del diccionario permanezcan distintas.
`flag_values`	Diccionario: etiqueta -> String; no configurable; el valor predeterminado es `{}` Igual que `values`, pero para marcas de compilación definidas 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 a ellas como cadenas arbitrarias.
`values`	Diccionario: String -> String; no configurable; el valor predeterminado es `{}` El conjunto de valores de configuración que coinciden con esta regla (expresados como marcas de compilación) Esta regla hereda la configuración del destino configurado que hace referencia a ella en una sentencia `select`. Se considera que "coincide" con una invocación de Bazel si, para cada entrada del diccionario, su configuración coincide con el valor esperado de la entrada. Por ejemplo, `values = {"compilation_mode": "opt"}` coincide con las invocaciones `bazel build --compilation_mode=opt ...` y `bazel build -c opt ...` en las reglas configuradas para el destino. Para mayor comodidad, los valores de configuración se especifican como marcas de compilación (sin el `"--"` anterior), pero ten en cuenta que no son iguales. Esto se debe a que los destinos se pueden compilar en varias configuraciones dentro de la misma compilación. Por ejemplo, el valor “cpu” de una configuración de ejecución coincide con el valor de `--host_cpu`, no con `--cpu`. Por lo tanto, diferentes instancias del mismo `config_setting` pueden coincidir de manera diferente con la misma invocación según la configuración de la regla que las usa. 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., `bazel build --copt=foo --copt=bar --copt=baz ...`), se produce una coincidencia si alguno de esos parámetros de configuración coincide.

filegroup

Ver el origen de la regla

filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)

Usa filegroup para recopilar los resultados de un conjunto de objetivos en una sola etiqueta.

filegroup no reemplaza la enumeración de objetivos en la línea de comandos ni en un atributo de otra regla, ya que los objetivos tienen muchas propiedades además de sus resultados, que no se recopilan de la misma manera. Sin embargo, sigue siendo útil en algunos casos, por ejemplo, en el atributo srcs de una genrule o en el atributo data de una regla *_binary.

Se recomienda usar filegroup en lugar de hacer referencia a directorios directamente. No se recomienda hacer referencia directa a directorios, 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 se vuelva a compilar cuando estos archivos cambien. Cuando se combina con glob, filegroup puede garantizar que todos los archivos sean conocidos de forma explícita por el sistema de compilación.

Ejemplos

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

filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "//a/library:target",
        "//a/binary:target",
    ],
)

O bien, usa un glob para rastrear por completo 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`	Nombre: Obligatorio Un nombre único para este destino.
`srcs`	Es una lista de etiquetas. El valor predeterminado es `[]`. Es la lista de destinos que son miembros del grupo de archivos. Es común usar el resultado de una expresión glob para el valor del atributo `srcs`.
`data`	Es una lista de etiquetas. El valor predeterminado es `[]`. Es la lista de archivos que necesita esta regla durante el tiempo de ejecución. Los destinos nombrados en el atributo `data` se agregarán al `runfiles` de esta regla `filegroup`. Cuando se hace referencia a `filegroup` en el atributo `data` de otra regla, su `runfiles` se agregará a la `runfiles` de la regla dependiente. Consulta la sección Dependencias de datos y la documentación general de `data` para obtener más información sobre cómo depender de archivos de datos y usarlos.
`output_group`	Cadena; el valor predeterminado es `""` El grupo de salida a partir del cual se recopilan los artefactos de las fuentes. Si se especifica este atributo, se exportarán los artefactos del grupo de salida especificado de las dependencias en lugar del grupo de salida predeterminado. Un "grupo de salida" es una categoría de artefactos de salida de un destino, especificado en la implementación de esa regla.

genquery

Ver la fuente de la regla

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 consulta de Bazel 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 las consultas que contienen especificaciones de destino comodín (p.ej., //pkg:* o //pkg:all) no se permiten aquí. 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 la consulta de generación de demanda está ordenado de manera lexicográfica para aplicar un resultado determinista, a excepción de --output=graph|minrank|maxrank, o cuando se usa somepath como 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 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`	Nombre: Obligatorio Un nombre único para este objetivo.
`compressed_output`	Booleano; el valor predeterminado es `False` Si es `True`, el resultado de la consulta se escribe en formato de archivo GZIP. Este parámetro de configuración se puede usar para evitar aumentos repentinos en el uso de memoria de Bazel cuando se espera que el resultado de la consulta sea grande. Bazel ya comprime internamente los resultados de las consultas superiores a 2²⁰ bytes, independientemente del valor de este parámetro de configuración, por lo que establecerlo en `True` puede no reducir el montón retenido. Sin embargo, permite que Bazel omita la descompresión cuando escribe el archivo de salida, lo que puede requerir mucho uso de memoria.
`expression`	Cadena; obligatorio Es la consulta que se ejecutará. A diferencia de la línea de comandos y otros lugares en los archivos BUILD, las etiquetas aquí se resuelven en relación con el directorio raíz del espacio de trabajo. Por ejemplo, la etiqueta `:b` en este atributo del archivo `a/BUILD` hará referencia al objetivo `//:b`.
`opts`	Es una lista de cadenas. El valor predeterminado es `[]`. Son las opciones que se pasan al motor de consultas. Estas corresponden a las opciones de línea de comandos que se pueden pasar a `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`	Es una lista de etiquetas obligatoria. Es el alcance de la consulta. La consulta no puede tocar objetivos fuera del cierre transitivo de estos objetivos.
`strict`	Booleano; el valor predeterminado es `True` Si es verdadero, no se compilarán los destinos cuyas consultas escapen de la clausura transitiva de sus alcances. Si es falso, Bazel imprimirá una advertencia y omitirá cualquier ruta de consulta que lo haya llevado fuera del alcance, mientras completa el resto de la consulta.

genrule

Ver el origen de la regla

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 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.

Ten en cuenta que genrule requiere un shell para interpretar el argumento del comando. También es fácil hacer referencia a programas arbitrarios disponibles en la RUTA DE ACCESO. Sin embargo, esto hace que el comando no sea hermético y pueda no ser reproducible. Si solo necesitas ejecutar una herramienta, considera usar run_binary en su lugar.

Al igual que cualquier otra acción, la acción creada por genrules no debe suponer nada sobre su directorio de trabajo. Lo único que garantiza Bazel es que sus entradas declaradas estarán disponibles en la ruta que $(location) muestra para su etiqueta. Por ejemplo, si la acción se ejecuta en una zona de pruebas o de forma remota, la implementación de la zona de pruebas o la ejecución remota determinará el directorio de trabajo. Si se ejecuta directamente (con la estrategia standalone), el directorio de trabajo será la raíz de ejecución, es decir, el resultado de bazel info execution_root.

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 genrules se ejecuta durante la compilación y en la arquitectura de ejecución (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 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 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 las genrules, el sistema de compilación garantiza que las dependencias se compilen de forma correcta: srcs se compilan (si es necesario) para la configuración target, tools para la configuración exec y se considera que el resultado corresponde a la configuración 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 genrules funcionan solo a nivel de archivo y runfiles.

Casos especiales

Compilación exec-exec: 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 de ejecución, ya que es allí 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 de exec 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 paquete del compilador C++, el sistema de compilación proporciona un conjunto de variables para usar. Consulta Variable "Make" para obtener más detalles.

Entorno de genrule

El comando genrule se ejecuta en 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 procesos depurado 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.

Consejos generales

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 los archivos de salida para diferentes parámetros de configuración, las genrules no pueden depender de rutas hard-coded o absolutas.
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 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 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 srcs de 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 también funcionaría el uso de $(SRCS) en lugar de directivas $(location) explícitas. En este ejemplo, se usa esta última para una 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`	Nombre: Obligatorio Un nombre único para este destino. 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`	Es una lista de etiquetas. El valor predeterminado es `[]`. Es una lista de entradas para esta regla, como los archivos de origen que se procesarán. Este atributo no es adecuado para enumerar las herramientas que ejecuta `cmd`. En su lugar, usa el atributo `tools`. 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 `$(SRCS)`. Como alternativa, la ruta de acceso de un objetivo `//x:y` `srcs` individual se puede obtener con `$(location //x:y)` o con `$<`, siempre que sea la única entrada en `srcs`.
`outs`	Es una lista de nombres de archivos no configurables obligatoria. Una lista de los archivos que genera esta regla. 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 `executable`, `outs` debe contener exactamente una etiqueta. Se espera que el comando genrule cree cada archivo de salida en una ubicación predeterminada. La ubicación está disponible en `cmd` con variables "Make" específicas de genrule (`$@`, `$(OUTS)`, `$(@D)` o `$(RULEDIR)`) o con la sustitución `$(location)`.
`cmd`	Cadena; el valor predeterminado es `""` Es el comando que se ejecutará. Sujeto a la sustitución de `$(location)` y la variable “Make”. Primero, se aplica la sustitución `$(location)`, que reemplaza todas las ocurrencias de `$(location label)` y `$(locations label)` (y construcciones similares con las variables relacionadas `execpath`, `execpaths`, `rootpath` y `rootpaths`). A continuación, se expanden las variables"Make". Ten en cuenta que las variables predefinidas `$(JAVA)`, `$(JAVAC)` y `$(JAVABASE)` se expanden en la configuración exec, por lo que las invocaciones de Java que se ejecutan como parte de un paso de compilación pueden cargar correctamente las bibliotecas compartidas y otras dependencias. Por último, el comando resultante se ejecuta con la shell de Bash. Si su código de salida es distinto de cero, se considera que el comando falló. Este es el resguardo de `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 (64,000 en Linux/macOS y 8,000 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`, `cmd_bash`, `cmd_ps`, `cmd_bat`).
`cmd_bash`	String; el valor predeterminado es `""` Es el comando Bash que se ejecutará. Este atributo tiene una prioridad más alta que `cmd`. El comando se expande y se ejecuta de la misma manera que el atributo `cmd`.
`cmd_bat`	Cadena; el valor predeterminado es `""` El comando Batch que se ejecutará en Windows. Este atributo tiene mayor prioridad que `cmd` y `cmd_bash`. El comando se ejecuta de manera similar al atributo `cmd`, con las siguientes diferencias: Este atributo solo se aplica en Windows. El comando se ejecuta con `cmd.exe /c` con los siguientes argumentos predeterminados: `/S`: Quita las primeras y últimas comillas y ejecuta todo lo demás tal como está. `/E:ON`: Habilita el conjunto de comandos extendido. `/V:ON`: Habilita la expansión de variables demorada. `/D`: Ignora las entradas del registro de AutoRun. Después de la sustitución de $(location) y de variable "Make", las rutas de acceso se expandirán a las de estilo de Windows (con barra inversa).
`cmd_ps`	Cadena; el valor predeterminado es `""` El comando de PowerShell que se ejecutará en Windows. Este atributo tiene una prioridad más alta que `cmd`, `cmd_bash` y `cmd_bat`. El comando se ejecuta de manera similar al atributo `cmd`, con las siguientes diferencias: Este atributo solo se aplica en Windows. El comando se ejecuta con `powershell.exe /c`. 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. `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`: Permite ejecutar secuencias de comandos sin firmar. `$errorActionPreference='Stop'`: En caso de que haya varios comandos separados por `;`, la acción se cierra de inmediato si falla un CmdLet de Powershell, pero NO funciona para el comando externo. `$PSDefaultParameterValues['*:Encoding'] = 'utf8'`: Cambia la codificación predeterminada de UTF-16 a UTF-8.
`executable`	Booleano; no configurable; el valor predeterminado es `False` Declara que el resultado sea ejecutable. Si estableces esta marca en "True", el resultado es un archivo ejecutable y se puede ejecutar con el comando `run`. En este caso, genrule debe producir exactamente un resultado. Si se establece este atributo, `run` intentará ejecutar el archivo independientemente de su contenido. No se admite la declaración de dependencias de datos para el ejecutable generado.
`local`	Booleano; el valor predeterminado es `False` Si se establece como "true", esta opción obliga a que `genrule` se ejecute con la estrategia "local", lo que significa que no hay ejecución remota, zona de pruebas ni trabajadores persistentes. Esto equivale a proporcionar una etiqueta "local" (`tags=["local"]`).
`message`	Cadena; el valor predeterminado es `""` Un mensaje de progreso. 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 insípido), pero puedes proporcionar uno más específico. Usa este atributo en lugar de `echo` u otras declaraciones de impresión en tu comando `cmd`, ya que esto permite que la herramienta de compilación controle si se imprimen o no tales mensajes de progreso.
`output_licenses`	Tipo de licencia (el valor predeterminado es `["none"]`) Consulta `common attributes`.
`output_to_bindir`	Booleano; no configurable; el valor predeterminado es `False` Si se establece en "True", esta opción hace que los archivos de salida se escriban en el directorio `bin` en lugar del directorio `genfiles`.
`toolchains`	Es una lista de etiquetas no configurables. El valor predeterminado es `[]`. Es el conjunto de destinos a cuyas variables Make puede acceder esta genrule o los destinos `toolchain_type` a los que accederá esta genrule. Las cadenas de herramientas a las que se accede a través de `toolchain_type` también deben proporcionar un proveedor de `TemplateVariableInfo`, que el destino puede usar para acceder a los detalles de la cadena de herramientas.
`tools`	Es una lista de etiquetas. El valor predeterminado es `[]`. Es una lista de dependencias de herramienta para esta regla. Consulta la definición de dependencias para obtener más información. 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 de exec, ya que estas herramientas se ejecutan como parte de la compilación. La ruta de un `//x:y` de destino `tools` individual se puede obtener con `$(location //x:y)`. Cualquier `*_binary` o herramienta que `cmd` ejecute debe aparecer en esta lista, no en `srcs`, para garantizar que se compilen con la configuración correcta.

starlark_doc_extract

Ver la fuente de la regla

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 documentación para reglas, funciones (incluidas las macros), aspectos y proveedores definidos o reexportados en un archivo .bzl o .scl determinado. El resultado de esta regla es un proto binario ModuleInfo como se define en stardoc_output.proto en el árbol de fuentes de Bazel.

Objetivos de salida implícitos

name.binaryproto (el resultado predeterminado): Un proto binario ModuleInfo.
name.textproto (solo se compila si se solicita de forma explícita): la versión de proto de texto de name.binaryproto.

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

Argumentos

Atributos
`name`	Nombre: Obligatorio Un nombre único para este destino.
`deps`	Es una lista de etiquetas. El valor predeterminado es `[]`. Es una lista de destinos que unen los archivos Starlark que `src` `load()`. En el uso normal, estos objetivos deben ser objetivos `bzl_library`, pero la regla `starlark_doc_extract` no lo aplica y acepta cualquier destino que proporcione archivos de Starlark en su `DefaultInfo`. Ten en cuenta que los archivos Starlark unidos deben ser archivos del árbol de origen. Bazel no puede compilar archivos `load()`.
`src`	Etiqueta (Label): Obligatorio Un archivo de Starlark del que se extrae la documentación. Ten en cuenta que debe ser un archivo en el árbol de origen. Bazel no puede `load()` generar archivos.
`render_main_repo_name`	Booleano; el valor predeterminado es `False` Si es verdadero, las etiquetas renderizadas en el repositorio principal de la documentación emitida con un componente de repositorio (en otras palabras, `//foo:bar.bzl` se emitirá como `@main_repo_name//foo:bar.bzl`). El nombre que se usará para el repositorio principal se obtiene de `module(name = ...)` en el archivo `MODULE.bazel` del repositorio principal (si Bzlmod está habilitado) o de `workspace(name = ...)` en el archivo `WORKSPACE` del repositorio principal. Este atributo se debe establecer en `False` cuando se genera documentación para archivos Starlark que se diseñaron para usarse solo dentro del mismo repositorio y en `True` cuando se genera documentación para archivos Starlark que se diseñaron para usarse desde otros repositorios.
`symbol_names`	Lista de cadenas; el valor predeterminado es `[]` Es una lista opcional de nombres calificados de funciones, reglas, proveedores o aspectos exportados (o las estructuras en las que se anidan) para los que se extraerá la documentación. Aquí, un nombre calificado significa el nombre con el que una entidad está disponible para un usuario del módulo, incluidos cualquier struct en el que la entidad está anidada para el espacio de nombres. `starlark_doc_extract` emite documentación para una entidad solo si cada componente del nombre calificado de la entidad es público (en otras palabras, el primer carácter de cada componente del nombre calificado es alfabético, no `"_"`) y O bien la lista `symbol_names` está vacía (que es el caso predeterminado), o El nombre calificado de la entidad o el nombre calificado de una estructura en la que se anida la entidad se encuentra en la lista `symbol_names`.

test_suite

Ver el origen de la regla

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 bazel test respeta este tipo de organización: para una invocación como bazel test //some/test:suite, Bazel 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

Atributos
`name`	Name; obligatorio Un nombre único para este destino.
`tags`	Es una lista de cadenas no configurable. El valor predeterminado es `[]`. Lista de etiquetas de texto, como “pequeño” o “base de datos” o “-fiable”. Las etiquetas pueden ser cualquier cadena válida. 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. Solo se incluirán en el conjunto de pruebas 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 omite la comprobación de errores en las pruebas que se filtran; las dependencias en las pruebas omitidas aún deben ser legales (p.ej., que no estén bloqueadas por restricciones de visibilidad). La palabra clave de la etiqueta `manual` se trata de manera diferente a la anterior con la "expansión de test_suite" que realiza el comando `bazel test` en invocaciones que involucran comodines en patrones de destino. Allí, se filtran los objetivos de `test_suite` etiquetados como "manual" (por lo que no se expanden). Este comportamiento es coherente con la forma en que `bazel build` y `bazel test` manejan los patrones de destino comodín en general. Ten en cuenta que esto es diferente de la forma en que se comporta `bazel query 'tests(E)'`, ya que la función de consulta `tests` siempre expande los paquetes, independientemente de la etiqueta `manual`. Ten en cuenta que el `size` de una prueba se considera una etiqueta para filtrar. Si necesitas un `test_suite` que contenga pruebas con etiquetas mutuamente excluyentes (p.ej., todas las pruebas pequeñas y medianas), tendrás que crear tres reglas `test_suite`: una para todas las pruebas de nivel inferior, una para todas las pruebas de nivel intermedio y otra que incluya las dos anteriores.
`tests`	Es una lista de etiquetas no configurables. El valor predeterminado es `[]`. Es una lista de paquetes de pruebas y objetivos de prueba en cualquier idioma. Aquí se acepta cualquier `_test`, independientemente del idioma. Sin embargo, no se aceptan objetivos `_binary`, incluso si ejecutan una prueba. El filtrado por el `tags` especificado solo se realiza para las pruebas que se enumeran directamente en este atributo. Si este atributo contiene `test_suite`, este `test_suite` no filtrará las pruebas que se encuentran dentro de ellos (se considera que ya se filtraron). Si no se especifica el atributo `tests` o está vacío, la regla incluirá de forma predeterminada todas las reglas de prueba del archivo de COMPILACIÓN actual que no estén etiquetadas como `manual`. Estas reglas aún están sujetas al filtrado de `tag`.

name

Name; obligatorio

Un nombre único para este destino.

tags

Es una lista de cadenas no configurable. El valor predeterminado es [].

Lista de etiquetas de texto, como “pequeño” o “base de datos” o “-fiable”. Las etiquetas pueden ser cualquier cadena válida.

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.

Solo se incluirán en el conjunto de pruebas 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 omite la comprobación de errores en las pruebas que se filtran; las dependencias en las pruebas omitidas aún deben ser legales (p.ej., que no estén bloqueadas por restricciones de visibilidad).

La palabra clave de la etiqueta manual se trata de manera diferente a la anterior con la "expansión de test_suite" que realiza el comando bazel test en invocaciones que involucran comodines en patrones de destino. Allí, se filtran los objetivos de test_suite etiquetados como "manual" (por lo que no se expanden). Este comportamiento es coherente con la forma en que bazel build y bazel test manejan los patrones de destino comodín en general. Ten en cuenta que esto es diferente de la forma en que se comporta bazel query 'tests(E)', ya que la función de consulta tests siempre expande los paquetes, independientemente de la etiqueta manual.

Ten en cuenta que el size de una prueba se considera una etiqueta para filtrar.

Si necesitas un test_suite que contenga pruebas con etiquetas mutuamente excluyentes (p.ej., todas las pruebas pequeñas y medianas), tendrás que crear tres reglas test_suite: una para todas las pruebas de nivel inferior, una para todas las pruebas de nivel intermedio y otra que incluya las dos anteriores.

tests

Es una lista de etiquetas no configurables. El valor predeterminado es [].

Es una lista de paquetes de pruebas y objetivos de prueba en cualquier idioma.

Aquí se acepta cualquier *_test, independientemente del idioma. Sin embargo, no se aceptan objetivos *_binary, incluso si ejecutan una prueba. El filtrado por el tags especificado solo se realiza para las pruebas que se enumeran directamente en este atributo. Si este atributo contiene test_suite, este test_suite no filtrará las pruebas que se encuentran dentro de ellos (se considera que ya se filtraron).

Si no se especifica el atributo tests o está vacío, la regla incluirá de forma predeterminada todas las reglas de prueba del archivo de COMPILACIÓN actual que no estén etiquetadas como manual. Estas reglas aún están sujetas al filtrado de tag.