acciones

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

Módulo que proporciona funciones para crear acciones. Accede a este módulo usando ctx.actions.

Miembros

args

Args actions.args()

Muestra un objeto Args que se puede usar para compilar líneas de comandos eficientes en términos de memoria.

declare_directory

File actions.declare_directory(filename, *, sibling=None)

Declara que la regla o el aspecto crea un directorio con el nombre determinado en el paquete actual. Debes crear una acción que genere el directorio. No se puede acceder directamente al contenido del directorio desde Starlark, pero se puede expandir en un comando de acción con Args.add_all(). Solo los archivos y directorios normales pueden estar en el contenido expandido de un declare_directory.

Parámetros

Parámetro Descripción
filename string; obligatorio
Si no se incluye un “hermano” proporcionado, ruta de acceso del directorio nuevo, en relación con el paquete actual. De lo contrario, un nombre base para un archivo (el valor "del mismo nivel" define un directorio).
sibling Archivo; o None; el valor predeterminado es None
Un archivo que se encuentra en el mismo directorio que el directorio declarado recientemente. El archivo debe estar en el paquete actual.

declare_file

File actions.declare_file(filename, *, sibling=None)

Declara que la regla o el aspecto crea un archivo con el nombre de archivo determinado. Si no se especifica sibling, el nombre del archivo es relativo al directorio del paquete; de lo contrario, el archivo está en el mismo directorio que sibling. No se pueden crear archivos fuera del paquete actual.

Recuerda que, además de declarar un archivo, debes crear por separado una acción que emita el archivo. Para crear esa acción, deberás pasar el objeto File que se muestra a la función de construcción de la acción.

Ten en cuenta que los archivos de salida declarados previamente no necesitan declararse (y no pueden) declararse con esta función. En su lugar, puedes obtener sus objetos File de ctx.outputs. Consulta un ejemplo de uso.

Parámetros

Parámetro Descripción
filename string; obligatorio
Si no se incluye un “hermano” proporcionado, ruta de acceso del archivo nuevo, en relación con el paquete actual. De lo contrario, un nombre base para un archivo (el valor "del mismo nivel" determina un directorio)
sibling Archivo; o None; el valor predeterminado es None
Un archivo que se encuentra en el mismo directorio que el archivo recién creado. El archivo debe estar en el paquete actual. 

File actions.declare_symlink(filename, *, sibling=None)

Declara que la regla o el aspecto crea un symlink con el nombre dado en el paquete actual. Debes crear una acción que genere este symlink. Bazel nunca anulará las referencias a este symlink y lo transferirá literalmente a zonas de pruebas o ejecutores remotos. Actualmente, no se admiten los vínculos simbólicos dentro de artefactos de árbol.

Parámetros

Parámetro Descripción
filename string; obligatorio
Si no se incluye un “hermano” proporcionado, ruta de acceso del nuevo symlink, en relación con el paquete actual. De lo contrario, un nombre base para un archivo (el valor "del mismo nivel" define un directorio).
sibling Archivo; o None; el valor predeterminado es None
Un archivo que se encuentra en el mismo directorio que el symlink recientemente declarado.

do_nothing

None actions.do_nothing(mnemonic, inputs=[])

Crea una acción vacía que no ejecuta un comando ni produce resultados, pero que es útil para insertar "acciones adicionales".

Parámetros

Parámetro Descripción
mnemonic string; obligatorio
Es una descripción de la acción en una sola palabra, por ejemplo, CppCompile o GoLink.
inputs secuencia de Files; o depset; la configuración predeterminada es []
Lista de los archivos de entrada de la acción.

expand_template

None actions.expand_template(template, output, substitutions={}, is_executable=False, computed_substitutions=unbound)

Crea una acción de expansión de plantillas. Cuando se ejecute la acción, se generará un archivo basado en una plantilla. Las partes de la plantilla se reemplazarán con el diccionario substitutions, en el orden en que se especifican las sustituciones. Cuando una clave del diccionario aparece en la plantilla (o el resultado de una sustitución previa), se reemplaza por el valor asociado. No hay sintaxis especial para las claves. Por ejemplo, puedes usar llaves para evitar conflictos (por ejemplo, {KEY}). Consulta un ejemplo de uso.

Parámetros

Parámetro Descripción
template Archivo; obligatorio
El archivo de plantilla, que es un archivo de texto con codificación UTF-8.
output Archivo; obligatorio
El archivo de salida, que es un archivo de texto con codificación UTF-8.
substitutions dict; el valor predeterminado es {}
Sustituciones que se deben hacer al expandir la plantilla.
is_executable bool; el valor predeterminado es False
Si el archivo de salida debe ser ejecutable
computed_substitutions TemplateDict; el valor predeterminado es unbound
Sustituciones que se deben hacer al expandir la plantilla.

run

None actions.run(outputs, inputs=[], unused_inputs_list=None, executable, tools=unbound, arguments=[], mnemonic=None, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None, shadowed_action=None, resource_set=None, toolchain=unbound)

Crea una acción que ejecuta un ejecutable. Consulta un ejemplo de uso.

Parámetros

Parámetro Descripción
outputs secuencia de Files; obligatorio
Lista de los archivos de salida de la acción.
inputs secuencia de Files; o depset; la configuración predeterminada es []
Es la lista o el depset de los archivos de entrada de la acción.
unused_inputs_list Archivo; o None; el valor predeterminado es None
Archivo que contiene la lista de entradas que la acción no usa.

El contenido de este archivo (generalmente uno de los resultados de la acción) corresponde a la lista de archivos de entrada que no se usaron durante toda la ejecución de la acción. Cualquier cambio en esos archivos no debe afectar de ninguna manera los resultados de la acción.

executable Archivo; o string; o FilesToRunProvider; obligatorio
El archivo ejecutable al que llamará la acción.
tools secuencia; o depset; el valor predeterminado es unbound
Lista o déficit de las herramientas que necesita la acción. Las herramientas son entradas con archivos runfiles adicionales que se ponen automáticamente a disposición para la acción. Cuando se proporciona una lista, puede ser una colección heterogénea de archivos, instancias de FilesToRunProvider o bases de archivos. Se agregarán automáticamente los archivos runfiles a los archivos que están directamente en la lista y provienen de ctx.executable. Cuando se proporciona un punto de acceso, solo debe contener Files. En ambos casos, los archivos dentro de depsets no tienen referencia cruzada con ctx.executable para runfiles.
arguments secuencia; el valor predeterminado es []
Son los argumentos de línea de comandos de la acción. Debe ser una lista de cadenas o de objetos actions.args().
mnemonic string; o None; el valor predeterminado es None
Es una descripción de la acción en una sola palabra, por ejemplo, CppCompile o GoLink.
progress_message string; o None; el valor predeterminado es None
Es el mensaje de progreso que se le mostrará al usuario durante la compilación. Por ejemplo, “Compiling foo.cc to create foo.o”. El mensaje puede contener patrones %{label}, %{input} o %{output}, que se sustituyen por la cadena de etiqueta, la primera entrada o la ruta del resultado, respectivamente. Prefieres usar patrones en lugar de cadenas estáticas porque las primeras son más eficientes.
use_default_shell_env bool; el valor predeterminado es False
Indica si la acción debe usar el entorno de shell predeterminado, que consiste en algunas variables dependientes del SO, así como variables establecidas a través de --action_env.

Si tanto use_default_shell_env como env se configuran en True, los valores establecidos en env reemplazarán el entorno de shell predeterminado si --incompatible_merge_fixed_and_default_shell_env está habilitado (predeterminado). Si la marca no está habilitada, se ignora env.

env dict; o None; el valor predeterminado es None
Establece el diccionario de variables de entorno.

Si tanto use_default_shell_env como env se configuran en True, los valores establecidos en env reemplazarán el entorno de shell predeterminado si --incompatible_merge_fixed_and_default_shell_env está habilitado (predeterminado). Si la marca no está habilitada, se ignora env.

execution_requirements dict; o None; el valor predeterminado es None
Información para programar la acción. Consulta las etiquetas para ver claves útiles.
input_manifests secuencia; o None; el valor predeterminado es None
Legacy. Ignorados.
exec_group string; o None; el valor predeterminado es None
Ejecuta la acción en la plataforma de ejecución del grupo ejecutivo determinado. Si no hay ninguna, se usa la plataforma de ejecución predeterminada del destino.
shadowed_action Acción; el valor predeterminado es None
Ejecuta la acción con las entradas de la acción paralela determinada y el entorno que se agregó a la lista de entradas y al entorno de la acción. El entorno de acción puede reemplazar cualquiera de las variables de entorno de la acción bloqueada. Si no hay ninguna, usa solo las entradas de la acción y el entorno determinado.
resource_set que se puede llamar; o None; el valor predeterminado es None
Una función de devolución de llamada que muestra un diccionario de conjunto de recursos, que se usa para estimar el uso de recursos al momento de la ejecución si la acción se ejecuta localmente.

La función acepta dos argumentos posicionales: una cadena que representa el nombre de un SO (p.ej., “osx”) y un número entero que representa el número de entradas para la acción. El diccionario devuelto puede contener las siguientes entradas, cada una de las cuales puede ser un número de punto flotante o un número entero:

  • "cpu": cantidad de CPU; predeterminado 1
  • “memory”: en MB; predeterminado: 250
  • "local_test": cantidad de pruebas locales; predeterminado 1

Si este parámetro se establece en None o si --experimental_action_resource_set es falso, se usan los valores predeterminados.

La devolución de llamada debe ser de nivel superior (no se permiten funciones lambda ni anidadas).

toolchain Etiqueta; o string; o None; la configuración predeterminada es unbound

Tipo de cadena de herramientas del ejecutable o las herramientas que se usan en esta acción.

Si el ejecutable y las herramientas no provienen de una cadena de herramientas, establece este parámetro en `None`.

Si el ejecutable y las herramientas provienen de una cadena de herramientas, el tipo de cadena de herramientas debe configurarse de modo que la acción se ejecute en la plataforma de ejecución correcta.

Ten en cuenta que la regla que crea esta acción debe definir esta cadena de herramientas dentro de su “rule()”. .

Cuando se establezcan los parámetros `toolchain` y `exec_group`, se usará `exec_group`. Se genera un error en caso de que el `exec_group` no especifique la misma cadena de herramientas.

run_shell

None actions.run_shell(outputs, inputs=[], tools=unbound, arguments=[], mnemonic=None, command, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None, shadowed_action=None, resource_set=None, toolchain=unbound)

Crea una acción que ejecuta un comando de shell. Consulta un ejemplo de uso.

Parámetros

Parámetro Descripción
outputs secuencia de Files; obligatorio
Lista de los archivos de salida de la acción.
inputs secuencia de Files; o depset; la configuración predeterminada es []
Es la lista o el depset de los archivos de entrada de la acción.
tools secuencia de Files; o depset; la configuración predeterminada es unbound
Lista o déficit de las herramientas que necesita la acción. Las herramientas son entradas con archivos runfiles adicionales que se ponen automáticamente a disposición para la acción. La lista puede contener instancias de Files o FilesToRunProvider.
arguments secuencia; el valor predeterminado es []
Son los argumentos de línea de comandos de la acción. Debe ser una lista de cadenas o de objetos actions.args().

Bazel pasa los elementos de este atributo como argumentos al comando.El comando puede acceder a estos argumentos con sustituciones de variables de shell, como $1, $2, etc. Ten en cuenta que, como los objetos Args se aplanan antes de la indexación, si hay un objeto Args de tamaño desconocido, todas las strings posteriores estarán en índices impredecibles. Puede resultar útil usar $@ (para recuperar todos los argumentos) junto con objetos Args de tamaño indeterminado.

Si command es una lista de cadenas, no se puede usar este parámetro.

mnemonic string; o None; el valor predeterminado es None
Es una descripción de la acción en una sola palabra, por ejemplo, CppCompile o GoLink.
command string; o secuencia de cadenas; obligatorio
Shell que se ejecutará. Puede ser una cadena (opción preferida) o una secuencia de cadenas (obsoleta).

Si command es una cadena, se ejecuta como si sh -c <command> "" <arguments>, es decir, los elementos en arguments están disponibles para el comando como $1, $2 (o %1, %2 si se usa por lotes de Windows), etc. Si arguments contiene objetos actions.args(), su contenido se agrega uno por uno a la línea de comandos, por lo que $i puede hacer referencia a cadenas individuales dentro de un objeto Args. Ten en cuenta que si se pasa un objeto Args de tamaño desconocido como parte de arguments, las cadenas tendrán índices desconocidos. En este caso, la sustitución de shell $@ (recuperar todos los argumentos) puede ser útil.

(Obsoleto) Si command es una secuencia de cadenas, el primer elemento es el ejecutable que se ejecutará y los elementos restantes son sus argumentos. Si se usa este formulario, no se debe proporcionar el parámetro arguments. Ten en cuenta que este formulario dejó de estar disponible y se quitará pronto. Se inhabilita con `--incompatible_run_shell_command_string`. Usa esta marca para verificar que tu código sea compatible.

Para ejecutar el comando, Bazel usa la misma shell que para genrules.

progress_message string; o None; el valor predeterminado es None
Es el mensaje de progreso que se le mostrará al usuario durante la compilación. Por ejemplo, “Compiling foo.cc to create foo.o”. El mensaje puede contener patrones %{label}, %{input} o %{output}, que se sustituyen por la cadena de etiqueta, la primera entrada o la ruta del resultado, respectivamente. Prefieres usar patrones en lugar de cadenas estáticas porque las primeras son más eficientes.
use_default_shell_env bool; el valor predeterminado es False
Indica si la acción debe usar el entorno de shell predeterminado, que consiste en algunas variables dependientes del SO, así como variables establecidas a través de --action_env.

Si tanto use_default_shell_env como env se configuran en True, los valores establecidos en env reemplazarán el entorno de shell predeterminado si --incompatible_merge_fixed_and_default_shell_env está habilitado (predeterminado). Si la marca no está habilitada, se ignora env.

env dict; o None; el valor predeterminado es None
Establece el diccionario de variables de entorno.

Si tanto use_default_shell_env como env se configuran en True, los valores establecidos en env reemplazarán el entorno de shell predeterminado si --incompatible_merge_fixed_and_default_shell_env está habilitado (predeterminado). Si la marca no está habilitada, se ignora env.

execution_requirements dict; o None; el valor predeterminado es None
Información para programar la acción. Consulta las etiquetas para ver claves útiles.
input_manifests secuencia; o None; el valor predeterminado es None
Legacy. Ignorados.
exec_group string; o None; el valor predeterminado es None
Ejecuta la acción en la plataforma de ejecución del grupo ejecutivo determinado. Si no hay ninguna, se usa la plataforma de ejecución predeterminada del destino.
shadowed_action Acción; el valor predeterminado es None
Ejecuta la acción con las entradas descubiertas de la acción bloqueada que se agregaron a la lista de entradas de la acción. Si no hay ninguna, usa solo las entradas de la acción.
resource_set que se puede llamar; o None; el valor predeterminado es None
Una función de devolución de llamada para estimar el uso de recursos si se ejecuta localmente. Consulta ctx.actions.run().
toolchain Etiqueta; o string; o None; la configuración predeterminada es unbound

Tipo de cadena de herramientas del ejecutable o las herramientas que se usan en esta acción.

Si el ejecutable y las herramientas no provienen de una cadena de herramientas, establece este parámetro en `None`.

Si el ejecutable y las herramientas provienen de una cadena de herramientas, el tipo de cadena de herramientas debe configurarse de modo que la acción se ejecute en la plataforma de ejecución correcta.

Ten en cuenta que la regla que crea esta acción debe definir esta cadena de herramientas dentro de su “rule()”. .

Cuando se establezcan los parámetros `toolchain` y `exec_group`, se usará `exec_group`. Se genera un error en caso de que el `exec_group` no especifique la misma cadena de herramientas.

 

None actions.symlink(output, target_file=None, target_path=None, is_executable=False, progress_message=None)

Crea una acción que escribe un symlink en el sistema de archivos.

Se debe llamar a esta función con solo uno de los valores target_file o target_path especificados.

Cuando uses target_file, declara output con declare_file() o declare_directory(), y haz coincidir el tipo de target_file. De esta manera, el symlink apunta a target_file. Bazel invalida el resultado de esta acción cada vez que cambia el destino del symlink o su contenido.

De lo contrario, cuando uses target_path, declara output con declare_symlink(). En este caso, el symlink apunta a target_path. Bazel nunca resuelve el symlink, y el resultado de esta acción se invalida solo cuando cambia el contenido de texto del symlink (es decir, el valor de readlink()). En particular, se puede usar para crear un symlink colgante.

Parámetros

Parámetro Descripción
output Archivo; obligatorio
El resultado de esta acción.
target_file Archivo; o None; el valor predeterminado es None
El archivo al que apuntará el symlink de salida.
target_path string; o None; el valor predeterminado es None
La ruta de acceso exacta a la que apuntará el symlink de salida. No se aplica ninguna normalización ni otro procesamiento.
is_executable bool; el valor predeterminado es False
Solo se puede usar con target_file, no con target_path. Si es verdadero, cuando se ejecuta la acción, se verifica la ruta de acceso de target_file para confirmar que es ejecutable y, si no es así, se informa un error. Establecer is_executable como falso no significa que el destino no sea ejecutable, solo que no se realiza ninguna verificación.

Esta función no tiene sentido para target_path, ya que es posible que no existan vínculos simbólicos colgantes durante el tiempo de compilación.
progress_message string; o None; el valor predeterminado es None
Mensaje de progreso para mostrarle al usuario durante la compilación.

template_dict

TemplateDict actions.template_dict()

Muestra un objeto TemplateDict para una expansión de plantillas eficiente en cuanto a la memoria.

write

None actions.write(output, content, is_executable=False)

Crea una acción de escritura de archivos. Cuando se ejecute la acción, escribirá el contenido determinado en un archivo. Se usa para generar archivos con la información disponible en la fase de análisis. Si el archivo es grande y tiene mucho contenido estático, considera usar expand_template.

Parámetros

Parámetro Descripción
output Archivo; obligatorio
Es el archivo de salida.
content string; o Args; obligatorio
el contenido del archivo. Puede ser una cadena o un objeto actions.args().
is_executable bool; el valor predeterminado es False
Si el archivo de salida debe ser ejecutable