Args

Informar un problema Ver fuente Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Es un objeto que encapsula, de manera eficiente en cuanto a la memoria, los datos necesarios para compilar parte o la totalidad de una línea de comandos.

A menudo, sucede que una acción requiere una línea de comandos grande que contiene valores acumulados de dependencias transitivas. Por ejemplo, una línea de comandos del vinculador podría enumerar cada archivo de objeto que necesitan todas las bibliotecas que se vinculan. Se recomienda almacenar esos datos transitivos en objetos depset, de modo que se puedan compartir entre varios destinos. Sin embargo, si el autor de la regla tuviera que convertir estos depsets en listas de cadenas para construir una línea de comandos de acción, se anularía esta optimización de uso compartido de memoria.

Por este motivo, las funciones de construcción de acciones aceptan objetos Args además de cadenas. Cada objeto Args representa una concatenación de cadenas y depsets, con transformaciones opcionales para manipular los datos. Los objetos Args no procesan los depsets que encapsulan hasta la fase de ejecución, cuando llega el momento de calcular la línea de comandos. Esto ayuda a aplazar cualquier copia costosa hasta que se complete la fase de análisis. Consulta la página Optimizing Performance para obtener más información.

Los Args se construyen llamando a ctx.actions.args(). Se pueden pasar como el parámetro arguments de ctx.actions.run() o ctx.actions.run_shell(). Cada mutación de un objeto Args agrega valores a la línea de comandos final.

La función map_each te permite personalizar la forma en que los elementos se transforman en cadenas. Si no proporcionas una función map_each, la conversión estándar es la siguiente:

  • Los valores que ya son cadenas se dejan como están.
  • Los objetos File se convierten en sus valores de File.path.
  • Los objetos Label se convierten en una representación de cadena que se resuelve en el mismo objeto cuando se resuelve en el contexto del repositorio principal. Si es posible, la representación de cadena usa el nombre visible de un repositorio en lugar del nombre canónico del repositorio, lo que hace que esta representación sea adecuada para su uso en archivos BUILD. Si bien no se garantiza la forma exacta de la representación, los ejemplos típicos son //foo:bar, @repo//foo:bar y @@canonical_name+//foo:bar.bzl.
  • Todos los demás tipos se convierten en cadenas de una manera sin especificar. Por este motivo, debes evitar pasar valores que no sean de tipo cadena o File a add(). Si los pasas a add_all() o add_joined(), debes proporcionar una función map_each.

Cuando se usa el formato de cadenas (parámetros format, format_each y format_joined de los métodos add*()), la plantilla de formato se interpreta de la misma manera que la sustitución de % en cadenas, excepto que la plantilla debe tener exactamente un marcador de posición de sustitución y debe ser %s. Los porcentajes literales se pueden escapar como %%. El formato se aplica después de que el valor se convierte en una cadena, como se indicó anteriormente.

Cada uno de los métodos add*() tiene una forma alternativa que acepta un parámetro posicional adicional, una cadena de "nombre de arg" para insertar antes del resto de los argumentos. En el caso de add_all y add_joined, no se agregará la cadena adicional si la secuencia resulta estar vacía. Por ejemplo, el mismo uso puede agregar --foo val1 val2 val3 --bar o solo --bar a la línea de comandos, según si la secuencia determinada contiene val1..val3 o está vacía.

Si el tamaño de la línea de comandos puede superar el tamaño máximo permitido por el sistema, los argumentos se pueden desbordar en archivos de parámetros. Consulta use_param_file() y set_param_file_format().

Ejemplo: Supongamos que queremos generar la siguiente línea de comandos: 

--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz
Podríamos usar el siguiente objeto Args: 
# foo_deps and bar_deps are depsets containing
# File objects for the foo and bar .txt files.
args = ctx.actions.args()
args.add_all("--foo", foo_deps)
args.add_joined("--bar", bar_deps, join_with=",")
args.add("--baz")
ctx.actions.run(
  ...
  arguments = [args],
  ...
)

Miembros

add

Args Args.add(arg_name_or_value, value=unbound, *, format=None)

Agrega un argumento a esta línea de comandos.

Parámetros

Parámetro Descripción
arg_name_or_value obligatorio
Si se pasan dos parámetros posicionales, esto se interpreta como el nombre del argumento. El nombre del argumento se agrega antes del valor sin ningún procesamiento. Si solo se pasa un parámetro posicional, se interpreta como value (consulta a continuación).
value El valor predeterminado es unbound.
Objeto que se anexará. Se convertirá en una cadena con la conversión estándar mencionada anteriormente. Como no hay un parámetro map_each para esta función, value debe ser una cadena o un File. Se debe pasar una lista, una tupla, un depset o un directorio File a add_all() o add_joined() en lugar de este método.
format cadena o None; el valor predeterminado es None
Es un patrón de cadena de formato que se aplicará a la versión en formato de cadena de value.

add_all

Args Args.add_all(arg_name_or_values, values=unbound, *, map_each=None, format_each=None, before_each=None, omit_if_empty=True, uniquify=False, expand_directories=True, terminate_with=None, allow_closure=False)

Agrega varios argumentos a esta línea de comandos. Los elementos se procesan de forma diferida durante la fase de ejecución.

La mayor parte del procesamiento se realiza en una lista de argumentos que se agregarán, según los siguientes pasos:

  1. Cada elemento de directorio File se reemplaza por todos los File incluidos de forma recursiva en ese directorio.
  2. Si se proporciona map_each, se aplica a cada elemento, y las listas de cadenas resultantes se concatenan para formar la lista de argumentos inicial. De lo contrario, la lista de argumentos inicial es el resultado de aplicar la conversión estándar a cada elemento.
  3. Cada argumento de la lista se formatea con format_each, si está presente.
  4. Si uniquify es verdadero, se quitan los argumentos duplicados. La primera repetición es la que permanece.
  5. Si se proporciona una cadena de before_each, se inserta como un argumento nuevo antes de cada argumento existente en la lista. Esto duplica de manera efectiva la cantidad de argumentos que se deben agregar hasta este punto.
  6. Excepto en el caso de que la lista esté vacía y omit_if_empty sea verdadero (el valor predeterminado), el nombre del argumento y terminate_with se insertan como el primer y el último argumento, respectivamente, si se proporcionan.
Ten en cuenta que las cadenas vacías son argumentos válidos que están sujetos a todos estos pasos de procesamiento.

Parámetros

Parámetro Descripción
arg_name_or_values obligatorio
Si se pasan dos parámetros posicionales, esto se interpreta como el nombre del argumento. El nombre del argumento se agrega antes de values como un argumento independiente sin ningún procesamiento. Este nombre de argumento no se agregará si omit_if_empty es verdadero (el valor predeterminado) y no se agregan otros elementos (como sucede si values está vacío o se filtran todos sus elementos). Si solo se pasa un parámetro posicional, se interpreta como values (consulta a continuación).
values sequence o depset; el valor predeterminado es unbound
Es la lista, la tupla o el depset cuyos elementos se agregarán.
map_each Es invocable o None; el valor predeterminado es None
Es una función que convierte cada elemento en cero o más cadenas, que se pueden procesar aún más antes de agregarlas. Si no se proporciona este parámetro, se usa la conversión estándar.

A la función se le pasa uno o dos argumentos posicionales: el elemento que se convertirá, seguido de un DirectoryExpander opcional. El segundo argumento solo se pasará si la función proporcionada está definida por el usuario (no integrada) y declara más de un parámetro.

El tipo de valor que se muestra depende de la cantidad de argumentos que se producirán para el elemento:

  • En el caso común en que cada elemento se convierte en una cadena, la función debe devolver esa cadena.
  • Si el elemento se debe filtrar por completo, la función debe devolver None.
  • Si el elemento se convierte en varias cadenas, la función devuelve una lista de esas cadenas.
Devolver una sola cadena o None tiene el mismo efecto que devolver una lista de longitud 1 o longitud 0, respectivamente. Sin embargo, es más eficiente y legible evitar crear una lista cuando no es necesario.

Por lo general, los elementos que son directorios se expanden automáticamente a su contenido cuando se establece expand_directories=True. Sin embargo, esto no expandirá los directorios contenidos dentro de otros valores, por ejemplo, cuando los elementos son structs que tienen directorios como campos. En esta situación, el argumento DirectoryExpander se puede aplicar para obtener manualmente los archivos de un directorio determinado.

Para evitar la retención no deseada de grandes estructuras de datos de la fase de análisis en la fase de ejecución, la función map_each se debe declarar con una instrucción def de nivel superior; no puede ser un cierre de función anidada de forma predeterminada.

Advertencia: Las instrucciones print() que se ejecuten durante la llamada a map_each no producirán ningún resultado visible.

format_each cadena o None; El valor predeterminado es None
Es un patrón de cadena de formato opcional que se aplica a cada cadena que devuelve la función map_each. La cadena de formato debe tener exactamente un marcador de posición "%s".
before_each cadena o None; El valor predeterminado es None
Es un argumento opcional que se agrega antes de cada argumento derivado de values.
omit_if_empty bool; el valor predeterminado es True
Si es verdadero, si no hay argumentos derivados de values para agregar, se suprime todo el procesamiento posterior y la línea de comandos no se modificará. Si es falso, el nombre del argumento y terminate_with, si se proporciona, se agregarán de todos modos, independientemente de si hay otros argumentos.
uniquify bool; el valor predeterminado es False
Si es verdadero, se omitirán los argumentos duplicados que se deriven de values. Solo permanecerá la primera ocurrencia de cada argumento. Por lo general, esta función no es necesaria porque los depsets ya omiten los duplicados, pero puede ser útil si map_each emite la misma cadena para varios elementos.
expand_directories bool; el valor predeterminado es True
Si es verdadero, los directorios de values se expandirán a una lista plana de archivos. Esto sucede antes de que se aplique map_each.
terminate_with cadena o None; el valor predeterminado es None
Es un argumento opcional que se agrega después de todos los demás argumentos. Este argumento no se agregará si omit_if_empty es verdadero (el valor predeterminado) y no se agregan otros elementos (como sucede si values está vacío o se filtran todos sus elementos).
allow_closure bool; el valor predeterminado es False
Si es verdadero, permite el uso de cierres en parámetros de funciones como map_each. Por lo general, esto no es necesario y se corre el riesgo de retener grandes estructuras de datos de la fase de análisis en la fase de ejecución.

add_joined

Args Args.add_joined(arg_name_or_values, values=unbound, *, join_with, map_each=None, format_each=None, format_joined=None, omit_if_empty=True, uniquify=False, expand_directories=True, allow_closure=False)

Agrega un argumento a esta línea de comandos concatenando varios valores con un separador. Los elementos se procesan de forma diferida durante la fase de ejecución.

El procesamiento es similar a add_all(), pero la lista de argumentos derivados de values se combina en un solo argumento como si fuera join_with.join(...) y, luego, se le da formato con la plantilla de cadena format_joined proporcionada. A diferencia de add_all(), no hay parámetros before_each ni terminate_with, ya que, por lo general, no son útiles cuando los elementos se combinan en un solo argumento.

Si, después de filtrar, no hay cadenas para unir en un argumento y si omit_if_empty es verdadero (valor predeterminado), no se realiza ningún procesamiento. De lo contrario, si no hay cadenas para unir, pero omit_if_empty es falso, la cadena unida será una cadena vacía.

Parámetros

Parámetro Descripción
arg_name_or_values obligatorio
Si se pasan dos parámetros posicionales, esto se interpreta como el nombre del argumento. El nombre del argumento se agrega antes de values sin ningún procesamiento. Este argumento no se agregará si omit_if_empty es verdadero (valor predeterminado) y no hay cadenas derivadas de values para unir (lo que puede suceder si values está vacío o si se filtran todos sus elementos). Si solo se pasa un parámetro posicional, se interpreta como values (consulta a continuación).
values sequence o depset; el valor predeterminado es unbound
Es la lista, la tupla o el depset cuyos elementos se unirán.
join_with string; obligatorio
Es una cadena de delimitador que se usa para unir las cadenas obtenidas de la aplicación de map_each y format_each, de la misma manera que string.join().
map_each callable; o None; el valor predeterminado es None
Igual que para add_all.
format_each cadena o None; el valor predeterminado es None
Igual que para add_all.
format_joined cadena o None; El valor predeterminado es None
Es un patrón de cadena de formato opcional que se aplica a la cadena unida. La cadena de formato debe tener exactamente un marcador de posición "%s".
omit_if_empty bool; valor predeterminado es True
Si es verdadero, si no hay cadenas para unir (ya sea porque values está vacío o todos sus elementos se filtraron), se suprimirá todo el procesamiento posterior y la línea de comandos no cambiará. Si es falso, incluso si no hay cadenas para unir, se agregarán dos argumentos: el nombre del argumento seguido de una cadena vacía (que es la unión lógica de cero cadenas).
uniquify bool; El valor predeterminado es False
Es igual que para add_all.
expand_directories bool; El valor predeterminado es True
Es igual que para add_all.
allow_closure bool; El valor predeterminado es False
Es igual que para add_all.

set_param_file_format

Args Args.set_param_file_format(format)

Establece el formato del archivo de parámetros, si se usa uno.

Parámetros

Parámetro Descripción
format string; obligatorio
Debe ser uno de los siguientes:
  • "multiline": Cada elemento (nombre o valor del argumento) se escribe textualmente en el archivo de parámetros con un carácter de salto de línea a continuación.
  • "shell": Igual que "multiline", pero los elementos se entrecomillan para la shell.
  • "flag_per_line": Es igual que "multiline", pero (1) solo se escriben marcas (que comienzan con "--") en el archivo de parámetros y (2) los valores de las marcas, si los hay, se escriben en la misma línea con un separador "=". Este es el formato que espera la biblioteca de marcas de Abseil.

Si no se llama, el formato predeterminado es "shell".

use_param_file

Args Args.use_param_file(param_file_arg, *, use_always=False)

Vuelca los argumentos en un archivo de parámetros y los reemplaza por un puntero al archivo de parámetros. Se usa cuando los argumentos pueden ser demasiado grandes para los límites de longitud de comandos del sistema.

Bazel puede optar por no escribir el archivo de parámetros en el árbol de salida durante la ejecución para mayor eficiencia. Si estás depurando acciones y quieres inspeccionar el archivo de parámetros, pasa --materialize_param_files a tu compilación.

Parámetros

Parámetro Descripción
param_file_arg string; obligatorio
Es una cadena de formato con un solo "%s". Si los argumentos se vuelcan en un archivo de parámetros, se reemplazan por un argumento que consiste en esta cadena con el formato de la ruta de acceso del archivo de parámetros.

Por ejemplo, si los argumentos se vuelcan en un archivo de parámetros "params.txt", especificar "--file=%s" hará que la línea de comandos de la acción contenga "--file=params.txt".

use_always bool; el valor predeterminado es False
Indica si siempre se deben volcar los argumentos en un archivo de parámetros. Si es falso, bazel decidirá si los argumentos deben desbordarse según tu sistema y la longitud del argumento.