acciones

Nocturno · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6
Módulo que proporciona funciones para crear acciones. Accede a este módulo con ctx.actions.

Miembros

args

Args actions.args()

Devuelve un objeto Args que se puede usar para compilar líneas de comandos eficientes en el uso 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; required
Si no se proporciona ningún "elemento secundario", es la ruta del directorio nuevo, relativa al paquete actual. De lo contrario, es un nombre base para un archivo (el "hermano" define un directorio).
sibling Archivo o None; El valor predeterminado es None
Es 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 se encuentra 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 devolvió a la función de construcción de la acción.

Ten en cuenta que los archivos de salida predeclarados no necesitan (ni 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 cadena; obligatorio
Si no se proporciona ningún "elemento secundario", es la ruta del archivo nuevo, relativa al paquete actual. De lo contrario, es un nombre base para un archivo (el "elemento secundario" determina un directorio).
sibling Archivo o None; el valor predeterminado es None
Es 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 vínculo simbólico con el nombre determinado en el paquete actual. Debes crear una acción que genere este vínculo simbólico. Bazel nunca anulará la referencia de este vínculo simbólico y lo transferirá literalmente a los espacios de pruebas o ejecutores remotos. Actualmente, no se admiten vínculos simbólicos dentro de los artefactos de árbol.

Parámetros

Parámetro Descripción
filename string; obligatorio
Si no se proporciona ningún "elemento secundario", es la ruta de acceso del nuevo vínculo simbólico, relativa al paquete actual. De lo contrario, es un nombre base para un archivo (el "hermano" define un directorio).
sibling Archivo o None; el valor predeterminado es None
Un archivo que se encuentra en el mismo directorio que el vínculo simbólico declarado recientemente.

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 que es útil para insertar "acciones adicionales".

Parámetros

Parámetro Descripción
mnemonic string; obligatorio
Es una descripción de la acción de una sola palabra, por ejemplo, CppCompile o GoLink.
inputs secuencia de Files o depset; el valor predeterminado 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 plantilla. 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. Cada vez que aparece una clave del diccionario en la plantilla (o en el resultado de una sustitución anterior), se reemplaza por 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 Archivo: obligatorio
Es el archivo de plantilla, que es un archivo de texto con codificación UTF-8.
output Archivo: obligatorio
Es el archivo de salida, que es un archivo de texto codificado en UTF-8.
substitutions dict; El valor predeterminado es {}
Sustituciones que se deben realizar cuando se expande la plantilla.
is_executable bool; el valor predeterminado es False
Indica si el archivo de salida debe ser ejecutable.
computed_substitutions TemplateDict; el valor predeterminado es unbound
Son las sustituciones que se deben realizar cuando se expande la plantilla.

map_directory

None actions.map_directory(*, input_directories, additional_inputs={}, output_directories, tools, additional_params={}, execution_requirements=None, exec_group=None, toolchain=None, use_default_shell_env=False, env=None, mnemonic=None, implementation)

Crea varias acciones basadas en los archivos de uno o más directorios de entrada para generar uno o más directorios de salida.

Parámetros

Parámetro Descripción
input_directories dict de Files; obligatorio
Diccionario que asigna cadenas a directorios de entrada, según lo declarado por ctx.actions.declare_directory() (solo se permiten directorios como valores aquí). Los valores especifican los directorios que queremos expandir para acceder a sus archivos en la función de implementación. Las claves (cadenas) actúan como identificadores para hacer referencia fácilmente a un directorio específico en la función de implementación.
additional_inputs dict; El valor predeterminado es {}
Es un diccionario de la asignación de cadenas a entradas adicionales (aquí solo se permiten archivos, FilesToRunProvider(s) y Depset(s)). Los valores especifican cualquier entrada adicional a la que queremos que accedan las acciones creadas por la función de implementación. Las claves (cadenas) actúan como identificadores para hacer referencia fácilmente a una entrada específica desde la función de implementación.
output_directories dict de Files; obligatorio
Diccionario que asigna cadenas a directorios de salida, según lo declarado por ctx.actions.declare_directory(). Los valores especifican los directorios de salida que queremos generar con las acciones creadas por la función de implementación. Las claves (cadenas) actúan como identificadores para hacer referencia fácilmente a un directorio de salida específico desde la función de implementación.
tools dict; obligatorio
Diccionario que asigna cadenas a herramientas (solo se permiten archivos, FilesToRunProvider(s) y Depset(s)). Los valores especifican las herramientas a las que queremos que accedan las acciones creadas por la función de implementación. Las claves (cadenas) actúan como identificadores para hacer referencia fácilmente a una herramienta específica desde la función de implementación.
additional_params dict; El valor predeterminado es {}
Es un diccionario que asigna cadenas a parámetros adicionales (aquí solo se permiten valores de cadena, booleanos y enteros). Los valores especifican cualquier parámetro adicional al que queremos que se pueda acceder desde la función de implementación y que se podría usar para influir en su comportamiento. Las claves (cadenas) actúan como identificadores para hacer referencia fácilmente a un parámetro específico desde la función de implementación.
execution_requirements dict o None; el valor predeterminado es None
Es la información para programar las acciones creadas. Consulta etiquetas para ver las claves útiles.
exec_group cadena o None; el valor predeterminado es None
Ejecuta las acciones creadas en la plataforma de ejecución del grupo de ejecución determinado. Si no se especifica ninguno, se usa la plataforma de ejecución predeterminada del destino.
toolchain Label, cadena o None; el valor predeterminado es None

Es el tipo de cadena de herramientas del ejecutable o de las herramientas que usan las acciones creadas.

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, se debe establecer el tipo de cadena de herramientas para que las acciones creadas se ejecuten en la plataforma de ejecución correcta.

Ten en cuenta que la regla que crea estas acciones debe definir esta cadena de herramientas dentro de su función "rule()".

Cuando se establecen los parámetros toolchain y exec_group, se usará exec_group. Se genera un error en caso de que exec_group no especifique la misma cadena de herramientas.
use_default_shell_env bool; el valor predeterminado es False
Indica si las acciones creadas deben usar el entorno de shell predeterminado, que consta de algunas variables dependientes del SO y variables establecidas a través de --action_env.

Si tanto use_default_shell_env como env se configuran como True, los valores establecidos en env reemplazarán el entorno de shell predeterminado.

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 como True, los valores establecidos en env reemplazarán el entorno de shell predeterminado.

mnemonic cadena o None; el valor predeterminado es None
Es una descripción de una palabra de las acciones creadas, por ejemplo, CppCompile o GoLink.
implementation function; required
Es una función de Starlark que se llama después de que se compilan los directorios de entrada para generar acciones que generan archivos en los directorios de salida especificados. A esta función se le pasan los siguientes argumentos:
  • template_ctx (posición): Es un objeto template_ctx que se puede usar para crear acciones.
  • input_directories (solo palabras clave): Es un diccionario que asigna las claves de cadena del argumento input_directories de actions.map_directory() a sus objetos ExpandedDirectory correspondientes.
  • output_directories (solo palabras clave): Es el valor del argumento output_directories de actions.map_directory(), un diccionario que asigna cadenas a directorios de salida.
  • additional_inputs (solo palabras clave): Es el valor del argumento additional_inputs de actions.map_directory(), un diccionario que asigna cadenas a archivos de entrada.
  • tools (solo palabras clave): Es el valor del argumento tools de actions.map_directory(), un diccionario que asigna cadenas a herramientas.
  • additional_params (solo palabras clave): Es el valor del argumento additional_params de actions.map_directory(); un diccionario que asigna cadenas a cadenas, valores booleanos o números enteros.
Esta función debe ser de nivel superior, es decir, no se permiten lambdas ni funciones anidadas.

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 archivo ejecutable. Consulta un ejemplo de uso.

Parámetros

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

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. Ningún cambio en esos archivos debe afectar de ninguna manera los resultados de la acción.

executable File, string o FilesToRunProvider; obligatorio
Es el archivo ejecutable al que llamará la acción.
tools sequence o depset; El valor predeterminado es unbound
Lista o depset de las herramientas que necesita la acción. Las herramientas son entradas ejecutables que pueden tener sus propios archivos ejecutables, los cuales se ponen a disposición de la acción automáticamente.

Cuando se proporciona una lista, puede ser una colección heterogénea de los siguientes elementos:

  • File s
  • FilesToRunProvider instancias
  • depsets de Files
Los Files de ctx.executable y los FilesToRunProviders que se encuentran directamente en la lista tendrán sus archivos ejecutables agregados automáticamente. Todas las herramientas se agregan de forma implícita como entradas.

arguments sequence; el valor predeterminado es []
Son los argumentos de la línea de comandos de la acción. Debe ser una lista de cadenas o de objetos actions.args().
mnemonic cadena o None; el valor predeterminado es None
Es una descripción de una palabra de la acción, por ejemplo, CppCompile o GoLink.
progress_message cadena o None; el valor predeterminado es None
Es el mensaje de progreso que se muestra al usuario durante la compilación, por ejemplo, "Compilando foo.cc para crear foo.o". El mensaje puede contener patrones %{label}, %{input} o %{output}, que se reemplazan por la cadena de la etiqueta, la primera entrada o la ruta de acceso de la salida, respectivamente. Es preferible usar patrones en lugar de cadenas estáticas, ya que los primeros 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 consta de algunas variables dependientes del SO y variables establecidas a través de --action_env.

Si tanto use_default_shell_env como env se configuran como True, los valores establecidos en env reemplazarán el entorno de shell predeterminado.

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 como True, los valores establecidos en env reemplazarán el entorno de shell predeterminado.

execution_requirements dict o None; el valor predeterminado es None
Es la información para programar la acción. Consulta etiquetas para ver las claves útiles.
input_manifests sequence o None; el valor predeterminado es None
Argumento heredado. Ignorados.
exec_group cadena o None; el valor predeterminado es None
Ejecuta la acción en la plataforma de ejecución del grupo de ejecución determinado. Si no se especifica ninguno, se usa la plataforma de ejecución predeterminada del destino.
shadowed_action Action: El valor predeterminado es None
Ejecuta la acción con las entradas y el entorno de la acción sombreada determinados que se agregaron a la lista de entradas y al entorno de la acción. El entorno de acción puede anular cualquiera de las variables de entorno de la acción sombreada. Si no hay ninguna, solo se usan las entradas de la acción y el entorno determinado.
resource_set Es un objeto invocable o None. El valor predeterminado es None
. Es una función de devolución de llamada que devuelve un diccionario de conjuntos de recursos y que se usa para estimar el uso de recursos en el tiempo de ejecución si esta acción se ejecuta de forma local.

La función acepta dos argumentos posicionales: una cadena que representa un nombre de SO (p.ej., "osx") y un número entero que representa la cantidad 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 CPUs; el valor predeterminado es 1
  • "memory": en MB; el valor predeterminado es 250
  • "local_test": cantidad de pruebas locales; el valor predeterminado es 1

Si este parámetro se establece en None , se usan los valores predeterminados.

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

toolchain Label, cadena o None; el valor predeterminado es unbound

Es el tipo de cadena de herramientas del ejecutable o de 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, se debe establecer el tipo de cadena de herramientas para 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 función "rule()".

Cuando se configuran los parámetros "toolchain" y "exec_group", se usará "exec_group". Se genera un error en caso de que `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 sequence de Files; obligatorio
Lista de los archivos de salida de la acción.
inputs sequence de Files o depset; el valor predeterminado es []
Lista o depset de los archivos de entrada de la acción.
tools sequence de Files o depset; el valor predeterminado es unbound
Lista o depset de cualquier herramienta que necesite la acción. Las herramientas son entradas ejecutables que pueden tener sus propios archivos ejecutables, los cuales se ponen a disposición de la acción automáticamente.

Cuando se proporciona una lista, puede ser una colección heterogénea de los siguientes elementos:

  • File s
  • FilesToRunProvider instancias
  • depsets de Files
Los Files de ctx.executable y los FilesToRunProviders que se encuentran directamente en la lista tendrán sus archivos ejecutables agregados automáticamente. Todas las herramientas se agregan de forma implícita como entradas.

arguments sequence; el valor predeterminado es []
Son los argumentos de la 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étera. Ten en cuenta que, dado que los objetos Args se aplanan antes de la indexación, si hay un objeto Args de tamaño desconocido, todas las cadenas posteriores estarán en índices impredecibles. Puede ser útil usar $@ (para recuperar todos los argumentos) junto con objetos Args de tamaño indeterminado.

En el caso en que command sea una lista de cadenas, es posible que no se use este parámetro.

mnemonic cadena o None; el valor predeterminado es None
Es una descripción de una palabra de la acción, por ejemplo, CppCompile o GoLink.
command string o sequence de strings; obligatorio
Comando de shell para ejecutar. Puede ser una cadena (preferida) o una secuencia de cadenas (obsoleta).

Si command es una cadena, se ejecuta como si fuera 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 un lote de Windows), etcétera. Si arguments contiene objetos actions.args(), sus contenidos se agregan 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 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 cadenas, el primer elemento es el ejecutable que se debe 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.

Bazel usa el mismo shell para ejecutar el comando que para las genrules.

progress_message cadena o None; el valor predeterminado es None
Es el mensaje de progreso que se muestra al usuario durante la compilación, por ejemplo, "Compilando foo.cc para crear foo.o". El mensaje puede contener patrones %{label}, %{input} o %{output}, que se reemplazan por la cadena de la etiqueta, la primera entrada o la ruta de acceso de la salida, respectivamente. Es preferible usar patrones en lugar de cadenas estáticas, ya que los primeros 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 consta de algunas variables dependientes del SO y variables establecidas a través de --action_env.

Si tanto use_default_shell_env como env se configuran como True, los valores establecidos en env reemplazarán el entorno de shell predeterminado.

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 como True, los valores establecidos en env reemplazarán el entorno de shell predeterminado.

execution_requirements dict o None; el valor predeterminado es None
Es la información para programar la acción. Consulta etiquetas para ver las claves útiles.
input_manifests sequence o None; el valor predeterminado es None
Argumento heredado. Ignorados.
exec_group cadena o None; el valor predeterminado es None
Ejecuta la acción en la plataforma de ejecución del grupo de ejecución determinado. Si no se especifica ninguno, se usa la plataforma de ejecución predeterminada del destino.
shadowed_action Action: El valor predeterminado es None
Ejecuta la acción con las entradas descubiertas de la acción sombreada determinada que se agregaron a la lista de entradas de la acción. Si no hay ninguno, solo se usan las entradas de la acción.
resource_set Se puede llamar o None; El valor predeterminado es None
Es una función de devolución de llamada para estimar el uso de recursos si se ejecuta de forma local. Consultactx.actions.run().
toolchain Label, cadena o None; el valor predeterminado es unbound

Es el tipo de cadena de herramientas del ejecutable o de 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, se debe establecer el tipo de cadena de herramientas para 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 función "rule()".

Cuando se configuran los parámetros "toolchain" y "exec_group", se usará "exec_group". Se genera un error en caso de que `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 exactamente uno de los parámetros target_file o target_path especificados.

Cuando usas target_file, declara output con declare_file() o declare_directory() y haz que coincida con el tipo de target_file. Esto hace que el symlink apunte a target_file. Bazel invalida el resultado de esta acción cada vez que cambia el destino del vínculo simbólico o su contenido.

De lo contrario, cuando uses target_path, declara output con declare_symlink()). En este caso, el vínculo simbólico apunta a target_path. Bazel nunca resuelve el vínculo simbólico, y el resultado de esta acción solo se invalida cuando cambia el contenido de texto del vínculo simbólico (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
Es el resultado de esta acción.
target_file File o None; el valor predeterminado es None
Es el archivo al que apuntará el vínculo simbólico de salida.
target_path cadena o None; el valor predeterminado es None
Es la ruta de acceso exacta a la que apuntará el vínculo simbólico de salida. No se aplica ninguna normalización ni otro tipo de 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 se puede ejecutar y se informa un error si no es así. Establecer is_executable en False no significa que el destino no sea ejecutable, sino que no se realiza ninguna verificación.

Esta función no tiene sentido para target_path porque es posible que no existan vínculos simbólicos pendientes en el momento de la compilación.
progress_message cadena o None; el valor predeterminado es None
Mensaje de progreso que se muestra al usuario durante la compilación.

template_dict

TemplateDict actions.template_dict()

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

write

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

Crea una acción de escritura de archivo. Cuando se ejecute la acción, se escribirá el contenido proporcionado 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
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
Indica si el archivo de salida debe ser ejecutable.
mnemonic cadena o None; el valor predeterminado es None
Es una descripción de una palabra de la acción, por ejemplo, CppCompile o GoLink.