Reglas generales

Informar un problema . Ver fuente . Por la noche · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Reglas

alias

Ver el código fuente de la regla
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 asignación de alias puede ser útil en repositorios grandes en los que cambiar el nombre de un objetivo requeriría cambios en muchos archivos. También puedes usar una regla de alias para almacenar un select si quieres reutilizar esa lógica para múltiples 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., 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 su tests .
  • Cuando se definen grupos de entornos, los alias de las reglas environment no 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

Nombre: obligatorio.

Un nombre único para este destino.

actual

Etiqueta; obligatorio.

El objetivo al que hace referencia este alias. No necesita ser una regla, también puede ser una entrada .

config_setting

Ver el código 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 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",
      ]
  )
  
En todos estos casos, es posible que la configuración cambie dentro de la compilación, por ejemplo, si un destino debe crearse para una plataforma distinta de la de 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 de todas formas algunos objetivos de compilación.

Notas

  • Consulta seleccionar para saber qué sucede cuando varias config_setting coincide con el estado de configuración actual.
  • Para marcas que admiten formas abreviadas (p. ej., --compilation_mode frente a -c), las definiciones de values deben usar el formato completo. Estos se configuran automáticamente hacer coincidir las invocaciones con cualquiera de las dos formas.
  • Si una marca toma varios valores (como --copt=-Da --copt=-Db o 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,b y --myflag=c,b,a. La semántica exacta varía entre marcas. Por ejemplo, --copt no admite varios valores en la misma instancia: --copt=a,b produce ["a,b"], mientras que --copt=a --copt=b produce ["a", "b"] (por lo 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,b y ios_multi_cpus=a --ios_multi_cpus=b producen ["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_setting 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 puede usarse en cualquier combinación en el mismo config_setting, pero al menos uno debe se puede establecer para cualquier config_setting.

Argumentos

Atributos
name

Nombre: obligatorio.

Un nombre único para este destino.

constraint_values

Lista de etiquetas; no configurable; el valor predeterminado es []

El conjunto mínimo de 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.

Si dos config_setting coinciden en la misma select y uno tiene las mismas marcas y constraint_setting que las demás, más las adicionales, se seleccionará la que tenga más parámetros de configuración. Esto se conoce como “especialización”. Por ejemplo: una config_setting que coincide con x86 y Linux se especializa un config_setting que coincida con x86.

Si dos config_setting coinciden y ambos tienen constraint_values que no está presente en el otro, esto es un error.

define_values

Diccionario: Cadena -> String; no configurable; el valor predeterminado 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 tecla (define) aparece dos veces en el diccionario. Con este atributo, se resuelve el 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 puede seguir apareciendo en values con sintaxis de marca normal, y se pueden mezclar libremente con este atributo, siempre que las claves del diccionario sean diferentes.

flag_values

Diccionario: label -> 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 las marcas definidas por el usuario se referencian como etiquetas, mientras que se hace referencia a las marcas integradas como cadenas arbitrarias.

values

Diccionario: Cadena -> 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 él en una sentencia select. Se considera que "coincidencia" una invocación de Bazel si, para cada entrada del diccionario, 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 objetivos.

Para mayor comodidad, los valores de configuración se especifican como marcas de compilación (sin el "--" anterior). Pero ten en cuenta que ambos no son iguales. Esta es que los destinos pueden crearse en múltiples configuraciones dentro de la misma compilar. Por ejemplo, la “cpu” de una configuración de ejecución coincide con el valor de --host_cpu, no --cpu. Por lo tanto, las diferentes instancias del mismo config_setting puede coincidir con la misma invocación de manera diferente según la configuración de la regla que los usa.

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., bazel build --copt=foo --copt=bar --copt=baz ...), se produce una coincidencia si coincide cualquiera de esos parámetros de configuración.

grupo de archivos

Ver el código fuente 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 un solo etiqueta.

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

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",
        "//a/library:target",
        "//a/binary:target",
    ],
)

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

Nombre: obligatorio.

Un nombre único para este destino.

srcs

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

Lista de etiquetas; el valor predeterminado es []

La lista de archivos que necesita esta regla en el entorno de ejecución.

Los destinos nombrados en el atributo data se agregarán al runfiles de esta regla filegroup. Cuando el valor Se hace referencia a filegroup en el atributo data de otra regla, su runfiles se agregará a runfiles de la regla dependiente. Consulta las dependencias de datos y la documentación general de data para obtener más información sobre cómo depender de los archivos de datos y usarlos.

output_group

String; el valor predeterminado es ""

El grupo de salida a partir del cual se recopilan los artefactos de las fuentes. Si este atributo es especificado, 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 objetivo, especificada en ese implementación de la regla.

consulta generativa

Ver el código 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 archivo Lenguaje de consulta de Bazel 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 genquery está ordenado de manera lexicográfica para aplicar un resultado determinista. con la excepción 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 de la un destino especificado a 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 destino.

compressed_output

Booleano; el valor predeterminado es False

Si es True, el resultado de la consulta se escribe en formato de archivo GZIP. Puedes usar este parámetro de configuración para evitar los 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 de más de 220 bytes, sin importar la el valor de este parámetro de configuración, por lo que establecerlo en True quizás no reduzca la cantidad de el montón. Sin embargo, permite que Bazel omita la descompresión cuando escribe el archivo de salida. lo que puede consumir mucha memoria.
expression

String; obligatorio.

La consulta que se ejecutará. A diferencia de la línea de comandos y otros lugares en los archivos BUILD, aquí las etiquetas se resuelven en relación con el directorio raíz del lugar de trabajo. Por ejemplo, el la etiqueta :b en este atributo en el archivo a/BUILD hará referencia al elemento objetivo //:b.
opts

Lista de cadenas; el valor predeterminado es []

Las opciones que se pasan al motor de consultas. Estas se corresponden con la línea de comandos que se pueden pasar a 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

Lista de etiquetas; obligatorio.

El alcance de la consulta. La consulta no tiene permitido el toque de objetivos táctiles fuera de la interfaz transitiva el cierre de estos objetivos.
strict

Booleano; el valor predeterminado es True

Si es verdadero, los objetivos cuyas consultas escapan del cierre transitivo de sus alcances no podrán compilar. Si es falso, Bazel imprimirá una advertencia y omitirá cualquier ruta de consulta que la haya llevado al exterior. el permiso, mientras se completa el resto de la consulta.

genrule

Ver el código fuente 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)

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 un mensaje de una sola línea 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.

Ten en cuenta que genrule requiere una shell para interpretar el argumento del comando. También es fácil hacer referencia a programas arbitrarios disponibles en PATH, sin embargo, esto hace que el comando no es hermético y es posible que no se pueda reproducir. 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; Bazel garantiza que sus entradas declaradas estarán disponibles en el Ruta de acceso que $(location) muestra para su etiqueta. Por ejemplo, si la acción se ejecuta en un la zona de pruebas o de forma remota, la implementación de la zona de pruebas o la ejecución remota de trabajo actual. Si se ejecutan directamente (con la estrategia standalone), el directorio 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 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 exec (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 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 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 exec y se considera que el resultado 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 Exec-exec: En algunos casos, el sistema de compilación debe ejecutar genrules para que la 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 exec, 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 de ejecución 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 se sigue 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. Si bien es útil para la depuración, 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 as ls $(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 srcs de 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

Nombre: obligatorio.

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

Lista de etiquetas; el valor predeterminado es []

Una lista de entradas para esta regla, como los archivos de origen que se procesarán.

Estos atributos no son adecuados para enumerar las herramientas que ejecuta cmd. usar en su lugar, el atributo tools.

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 $(SRCS); o la ruta de un individuo El //x:y objetivo de srcs se puede obtener usando $(location //x:y) o $< siempre que sea la única entrada en srcs

outs

Lista de nombres de archivo; no configurable; obligatorio.

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 configura la marca executable, outs debe contener exactamente uno. 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 "Make" específico de genrule variables ($@, $(OUTS), $(@D) o $(RULEDIR)) o mediante $(location).

cmd

String; el valor predeterminado es ""

El comando que se ejecutará. Sujeto a $(location) y "Marca" de variables.
  1. Se aplica la primera sustitución $(location) , reemplazando todos los casos de $(location label) y de $(locations label) (y similares construcciones con las variables relacionadas execpath, execpaths rootpath y rootpaths).
  2. A continuación, "Make" variables. Ten en cuenta que variables predefinidas $(JAVA), $(JAVAC) y $(JAVABASE) se expande en la configuración exec para que las invocaciones de Java que se ejecutan como parte de un paso de compilación pueden cargar correctamente las bibliotecas compartidas y otros dependencias.
  3. Por último, el comando resultante se ejecuta con la shell Bash. Si el código de salida es distinto de cero el comando se considera que falló.
Este es el resguardo de 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, cmd_bash, cmd_ps, cmd_bat).

cmd_bash

String; el valor predeterminado es ""

El comando Bash que se ejecutará.

Este atributo tiene mayor prioridad que cmd. El comando se expande y se ejecuta exactamente de la misma manera que el atributo cmd.

cmd_bat

String; 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 la misma manera que el atributo cmd, con el 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 las últimas comillas, y ejecuta todo lo demás como está.
    • /E:ON: Habilita el conjunto de comandos extendido.
    • /V:ON: Habilita la expansión de variables demorada.
    • /D: Ignora las entradas de registro de AutoRun.
  • Después de $(location) y "Marca" variable, las rutas de acceso se mostrarán se expandió a las rutas de estilo de Windows (con barra inversa).
cmd_ps

String; el valor predeterminado es ""

El comando de PowerShell que se ejecutará en Windows.

Este atributo tiene mayor prioridad que cmd, cmd_bash y cmd_bat El comando se ejecuta de manera similar a 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 el siguiente comando: para configurar el entorno antes de ejecutar el comando de PowerShell en genrule.

  • Set-ExecutionPolicy -Scope CurrentUser RemoteSigned - permite la ejecución secuencias de comandos sin firmar.
  • $errorActionPreference='Stop', en caso de que haya varios comandos separados por ;, la acción finaliza de inmediato si falla un CmdLet de PowerShell pero esto NO funciona para el comando externo.
  • $PSDefaultParameterValues['*:Encoding'] = 'utf8': Cambiar el valor predeterminado codificando de utf-16 a utf-8.
executable

Booleano; no configurable; el valor predeterminado es False

Declara el resultado como ejecutable.

Si estableces esta marca como verdadera, el resultado es un archivo ejecutable y se podrá ejecutar mediante el Comando run. En este caso, la 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 verdadera, esta opción obliga a que este genrule se ejecute con la configuración "local". lo que significa que no hay ejecución remota, zona de pruebas ni trabajadores persistentes.

Esto equivale a proporcionar valores "locales" como etiqueta (tags=["local"]).

message

String; el valor predeterminado es ""

Un mensaje de progreso.

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 echo o cualquier otra copia sentencias 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 como verdadera, esta opción hace que los archivos de salida se escriban en bin en lugar del directorio genfiles.

tools

Lista de etiquetas; el valor predeterminado es []

Una lista de dependencias tool para esta regla. Consulta la definición de dependencias para obtener más información.

El sistema de compilación garantiza que estos requisitos se compilen antes de ejecutar el comando genrule. se compilan con el comando exec configuración, ya que estas herramientas se ejecutan como parte de la compilación. La ruta de un el objetivo individual de tools //x:y se puede obtener usando $(location //x:y)

Cualquier *_binary o herramienta que ejecute cmd debe aparecer en esta de la aplicación, no en srcs, para garantizar que se compilen con la configuración correcta.

starlark_doc_extract

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

Destinos de salida implícitos

  • name.binaryproto (el resultado predeterminado): A Archivo proto binario ModuleInfo.
  • name.textproto (solo se compila si se solicita de manera explícita): Es el texto. versión proto de name.binaryproto.

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

Argumentos

Atributos
name

Nombre: obligatorio.

Un nombre único para este destino.

deps

Lista de etiquetas; el valor predeterminado es []

Una lista de destinos que unen los archivos de Starlark y que están unidos por load() src En condiciones de uso normal, estos objetivos deben bzl_library destinos, 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 de Starlark unidos deben estar en el árbol de fuentes. Bazel no puede load() archivos generados.

src

Etiqueta; obligatorio.

Un archivo de Starlark del que se extrae la documentación.

Ten en cuenta que debe ser un archivo en el árbol de fuentes. Bazel no puede load(). archivos generados.

render_main_repo_name

Booleano; el valor predeterminado es False

Si es verdadero, renderiza las etiquetas en el repositorio principal en 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 desde workspace(name = ...) en el archivo WORKSPACE del repositorio principal.

Este atributo se debe establecer en False cuando se genere documentación para Archivos de Starlark diseñados para usarse solo dentro del mismo repositorio True cuando se genera documentación para archivos de Starlark cuya finalidad es que se usan en otros repositorios.

symbol_names

Lista de cadenas; el valor predeterminado es []

Una lista opcional de nombres calificados de funciones, reglas, proveedores o aspectos exportados (o structs en las que están anidadas) para las que se debe extraer documentación. En este caso, un cliente calificado name significa el nombre con el que una entidad está disponible para un usuario del módulo incluidos los structs en los que la entidad está anidada para el espacio de nombres.

starlark_doc_extract emite documentación para una entidad solo si

  1. cada componente del nombre calificado de la entidad es público (es decir, el primer el carácter de cada componente del nombre calificado es alfabético, no "_"); y
    1. cualquiera sea la lista symbol_names esté vacía (que es la configuración predeterminada caso) o
    2. el nombre calificado de la entidad o el nombre calificado de un struct en el que la entidad está anidado, está en la lista symbol_names.

test_suite

Ver el código fuente 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" 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 bazel test respeta este orden. de la organización: Para una invocación como bazel test //some/test:suite, Bazel primero enumera todos los objetivos de prueba incluidos transitivamente en el objetivo //some/test:suite (se llamada "expansión del paquete_de_prueba"), luego, Bazel compila y prueba esos destinos.

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

Nombre: obligatorio.

Un nombre único para este destino.

tags

Lista de cadenas; no configurable; el valor predeterminado es []

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

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 manual se trata de manera diferente que la anterior "expansión de test_suite" que realiza el comando bazel test en las invocaciones con comodín patrones del objetivo. Allí, test_suite segmentación etiquetada como "manual" se filtran (y, por lo tanto, no expandido). Este comportamiento es coherente con la forma en que bazel build y bazel test controla los patrones de destino comodín en general. Ten en cuenta que es es explícitamente diferente del comportamiento de bazel query 'tests(E)', ya que los paquetes siempre se expande con la función de consulta tests, sin importar 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), deberás crear tres test_suite. una para todas las pruebas pequeñas, otra para todas las pruebas de nivel intermedio y otra que incluye las dos anteriores.

tests

Lista de etiquetas; no configurable; 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. No Sin embargo, se aceptan objetivos *_binary, incluso si ejecutan una prueba. Solo se filtra por el tags especificado para las pruebas indicadas directamente en este atributo. Si este atributo contiene test_suite, las pruebas dentro estos no se filtrarán por este test_suite (se consideran ya se filtró).

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