acciones

Módulo que proporciona funciones para crear acciones. Accede a este módulo con 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 crean 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 mediante un comando de acción con Args.add_all().

Parámetros

Parámetro Descripción
filename obligatorio
Si no se proporciona un valor del mismo nivel, la ruta de acceso del directorio nuevo, en relación con el paquete actual. De lo contrario, un nombre base para un archivo ("sibling" define un directorio).
sibling File; or None; default = None
Un archivo que se encuentra en el mismo directorio que el directorio recién declarado. El archivo debe estar en el paquete actual.

declare_file

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

Declara que la regla o el aspecto crean un archivo con el nombre de archivo especificado. Si no se especifica sibling, el nombre del archivo está relacionado con el directorio del paquete; de lo contrario, el archivo estará 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 no es necesario declarar (ni se puede) declarar los archivos de salida declarados previamente 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 obligatorio
Si no se proporciona un "sibling", la ruta de acceso al archivo nuevo, en relación con el paquete actual. De lo contrario, un nombre base para un archivo (“sibling” determina un directorio).
sibling File; or None; default = 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)

Experimental. Este parámetro es experimental y puede cambiar en cualquier momento. No dependas de ello. Se puede habilitar de manera experimental estableciendo --experimental_allow_unresolved_symlinks.

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á la referencia de este symlink y lo transferirá de forma literal a las zonas de pruebas o a los ejecutores remotos.

Parámetros

Parámetro Descripción
filename obligatorio
Si no se proporciona un valor "sibling", la ruta de acceso del nuevo symlink, en relación con el paquete actual. De lo contrario, un nombre base para un archivo ("sibling" define un directorio).
sibling File; or None; default = None
Un archivo que se encuentra en el mismo directorio que el symlink recién declarado.

do_nothing

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

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

Parámetros

Parámetro Descripción
mnemonic required
Es una descripción de la acción de una palabra, por ejemplo, CppCompile o GoLink.
inputs sequence of Files; or depset; default = []
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. Algunas partes de la plantilla se reemplazarán con el diccionario substitutions, en el orden en que se especifiquen las sustituciones. Cada vez que aparece una clave del diccionario en la plantilla (o como resultado de una sustitución previa), se reemplaza con el valor asociado. No hay una 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 obligatorio
El archivo de plantilla, que es un archivo de texto codificado en UTF-8.
output obligatorio
El archivo de salida, que es un archivo de texto codificado en UTF-8.
substitutions default = {}
Sustituciones que se realizan al expandir la plantilla.
is_executable default = False
Si el archivo de salida debe ser ejecutable.
computed_substitutions TemplateDict; predeterminado = no vinculado
Experimental. Este parámetro es experimental y puede cambiar en cualquier momento. No dependas de ello. Se puede habilitar de manera experimental si se configura --+experimental_lazy_template_expansion
Experimental: Sustituciones para realizar cuando se expande 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=None)

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

Parámetros

Parámetro Descripción
outputs sequence of Files; obligatorio
Lista de los archivos de salida de la acción.
inputs sequence of Files; or depset; default = []
Enumera o depset de los archivos de entrada de la acción.
unused_inputs_list File; or None; default = None
Archivo que contiene una lista de entradas que la acción no usa.

El contenido de este archivo (por lo general, 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. Ningún cambio en esos archivos debe afectar de ninguna manera los resultados de la acción.

executable File; or string; or FilesToRunProvider; obligatorio
El archivo ejecutable al que debe llamar la acción.
tools sequence; or depset; default = unbound
Enumera o despone de cualquier herramienta que necesite la acción. Las herramientas son entradas con archivos de ejecución adicionales que están disponibles automáticamente para la acción. Cuando se proporciona una lista, puede ser un conjunto heterogéneo de archivos, instancias de FilesToRunProvider o dependencias de archivos. Se agregarán automáticamente los archivos runfile a los archivos que estén directamente en la lista y que provengan de un archivo ctx.executable. Cuando se proporciona una dependencia, solo debe contener Files. En ambos casos, los archivos dentro de dependencias no se hacen referencias cruzadas con el archivo ctx.executable para los archivos de ejecución.
arguments sequence; default = []
Argumentos de línea de comandos de la acción. Debe ser una lista de objetos actions.args() o strings.
mnemonic string; or None; default = None
Es una descripción de una palabra de la acción, por ejemplo, CppCompile o GoLink.
progress_message string; or None; default = None
Es el mensaje de progreso que se 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 de salida, respectivamente. Prefieres usar patrones en lugar de strings estáticas, porque las primeras son más eficientes.
use_default_shell_env default = False
Indica si la acción debe usar o no el entorno de shell integrado.
env dict; or None; default = None
Establece el diccionario de variables de entorno.
execution_requirements dict; or None; default = None
Es la información para programar la acción. Consulta las etiquetas para obtener claves útiles.
input_manifests sequence; or None; default = None
(Experimental) establece los metadatos de runfiles de entrada. Por lo general, los genera resolve_command.
exec_group string; or None; default = None
Ejecuta la acción en la plataforma de ejecución del grupo de ejecución determinado. Si no hay ninguna, usa la plataforma de ejecución predeterminada del destino.
shadowed_action Action; default = None
Ejecuta la acción mediante las entradas de la acción bloqueada específica 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 callable; or None; default = 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 en el momento de la ejecución si esta acción se ejecuta de forma local.

La función acepta dos argumentos posicionales: una string que representa un nombre de SO (p.ej., “osx”) y un número entero que representa el número de entradas a 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 int:

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

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

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

toolchain Label; or string; or None; predeterminado = Ninguno

Tipo de cadena de herramientas del ejecutable o las herramientas que se usan en esta acción. Se debe establecer el parámetro para que la acción se ejecute en la plataforma de ejecución correcta.

En este momento, no funciona, pero te recomendamos que lo configures cuando se use una cadena de herramientas, ya que será necesaria en versiones futuras de Bazel.

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

Si se configuran los parámetros `toolchain` y `exec_group`, se usará `exec_group`. Se genera un error en caso de que el `exec_group` no especifique lo mismo.

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=None)

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

Parámetros

Parámetro Descripción
outputs sequence of Files; obligatorio
Lista de los archivos de salida de la acción.
inputs sequence of Files; or depset; default = []
Enumera o depset de los archivos de entrada de la acción.
tools sequence of Files; or depset; default = unbound
Enumera o despone de cualquier herramienta que necesite la acción. Las herramientas son entradas con archivos de ejecución adicionales que están disponibles automáticamente para la acción. La lista puede contener Files o instancias de FilesToRunProvider.
arguments sequence; default = []
Argumentos de línea de comandos de la acción. Debe ser una lista de objetos actions.args() o strings.

Bazel pasa los elementos de este atributo como argumentos al comando.El comando puede acceder a estos argumentos mediante 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 ser útil usar $@ (para recuperar todos los argumentos) junto con objetos Args de tamaño indeterminado.

Si command es una lista de strings, es posible que no se use este parámetro.

mnemonic string; or None; default = None
Es una descripción de una palabra de la acción, por ejemplo, CppCompile o GoLink.
command string; or sequence of strings; se requiere
comando de shell para ejecutarse. Puede ser una string (opción preferida) o una secuencia de strings (obsoleta).

Si command es una string, se ejecuta como si lo hiciera sh -c <command> "" <arguments>, es decir, los elementos de arguments están disponibles para el comando como $1, $2 (o %1, %2 si se usa el lote de Windows), etc. Si arguments contiene cualquier objeto actions.args(), su contenido se agrega uno por uno a la línea de comandos, de modo que $i puede hacer referencia a strings 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 estarán en índices desconocidos; en este caso, la sustitución de shell $@ (recuperar todos los argumentos) puede ser útil.

(Obsoleto) Si command es una secuencia de strings, el primer elemento es el ejecutable para la ejecución 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 es obsoleto y se quitará pronto. Se inhabilita con `--incompatible_run_shell_command_string`. Usa esta marca para verificar que tu código sea compatible.

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

progress_message string; or None; default = None
Es el mensaje de progreso que se 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 de salida, respectivamente. Prefieres usar patrones en lugar de strings estáticas, porque las primeras son más eficientes.
use_default_shell_env default = False
Indica si la acción debe usar o no el entorno de shell integrado.
env dict; or None; default = None
Establece el diccionario de variables de entorno.
execution_requirements dict; or None; default = None
Es la información para programar la acción. Consulta las etiquetas para obtener claves útiles.
input_manifests sequence; or None; default = None
(Experimental) establece los metadatos de runfiles de entrada. Por lo general, los genera resolve_command.
exec_group string; or None; default = None
Ejecuta la acción en la plataforma de ejecución del grupo de ejecución determinado. Si no hay ninguna, usa la plataforma de ejecución predeterminada del destino.
shadowed_action Action; default = None
Ejecuta la acción mediante las entradas descubiertas de la acción bloqueada específica 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 callable; or None; default = None
Es una función de devolución de llamada para estimar el uso de recursos si se ejecuta de manera local. Consulta ctx.actions.run().
toolchain Label; or string; or None; predeterminado = Ninguno

Tipo de cadena de herramientas del ejecutable o las herramientas que se usan en esta acción. Se debe establecer el parámetro para que la acción se ejecute en la plataforma de ejecución correcta.

En este momento, no funciona, pero te recomendamos que lo configures cuando se use una cadena de herramientas, ya que será necesaria en versiones futuras de Bazel.

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

Si se configuran los parámetros `toolchain` y `exec_group`, se usará `exec_group`. Se genera un error en caso de que el `exec_group` no especifique lo mismo. 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 exactamente uno de los valores target_file o target_path especificado.

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, esto se puede usar para crear un symlink colgante.

Parámetros

Parámetro Descripción
output required
Es el resultado de esta acción.
target_file File; or None; default = None
El archivo al que apuntará el symlink de salida.
target_path string; or None; predeterminado = Ninguno
(Experimental) La ruta de acceso exacta a la que apuntará el symlink de salida. No se aplica ninguna normalización ni otro procesamiento. El acceso a esta función requiere la configuración --experimental_allow_unresolved_symlinks.
is_executable default = 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 sea ejecutable y, de lo contrario, 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 los symlinks colgantes no existan durante el tiempo de compilación.
progress_message string; or None; default = None
Es el mensaje de progreso que se mostrará al usuario durante la compilación.

template_dict

TemplateDict actions.template_dict()

Experimental. Esta API es experimental y puede cambiar en cualquier momento. No dependas de ello. Se puede habilitar de manera experimental si configuras --+experimental_lazy_template_expansion
Experimental: Muestra un objeto TemplateDict para la expansión de plantillas que ahorran memoria.

write

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

Crea una acción de escritura de archivo. Cuando se ejecute la acción, se escribirá el contenido dado 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 required
El archivo de salida.
content string; or Args (obligatorio)
el contenido del archivo Puede ser una string o un objeto actions.args().
is_executable default = False
Si el archivo de salida debe ser ejecutable.