Un objeto que encapsula, de manera eficiente en la memoria, los datos necesarios para compilar parte o toda una línea de comandos.
A menudo, 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 todos los archivos de objeto que necesitan todas las bibliotecas vinculadas. Se recomienda almacenar esos datos transitivos en depset
para que varios destinos puedan compartirlos. Sin embargo, si el autor de la regla tuviera que convertir estos conjuntos de dependencias en listas de cadenas para construir una línea de comandos de acción, se anularía esta optimización de uso compartido de la 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 conjuntos de dependencias, con transformaciones opcionales para manipular los datos. Los objetos Args
no procesan los conjuntos de dependencias que encapsulan hasta la fase de ejecución, cuando llega el momento de calcular la línea de comandos. Esto ayuda a posponer cualquier copia costosa hasta que se complete la fase de análisis. Consulta la página Optimización del rendimiento para obtener más información.
Las 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 valoresFile.path
. - Todos los demás tipos se convierten en cadenas de una manera no especificada. Por este motivo, debes evitar pasar valores que no sean de tipo cadena o
File
aadd()
y, si los pasas aadd_all()
oadd_joined()
, debes proporcionar una funciónmap_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 %
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 según lo anterior.
Cada uno de los métodos add*()
tiene una forma alternativa que acepta un parámetro posicional adicional, una cadena "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, en función de si la secuencia dada contiene val1..val3
o está vacía.
Si el tamaño de la línea de comandos puede ser superior al tamaño máximo permitido por el sistema, los argumentos se pueden expandir a los archivos de parámetros. Consulta use_param_file()
y set_param_file_format()
.
Ejemplo: Supongamos que queremos generar la línea de comandos:
--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz
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)
Parámetros
Parámetro | Descripción |
---|---|
arg_name_or_value
|
obligatorio Si se pasan dos parámetros posicionales, 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 Es el objeto que se agregará. 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, tupla, depset o 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 con 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)
La mayor parte del procesamiento se realiza en una lista de argumentos que se agregarán, según los siguientes pasos:
- Cada elemento
File
del directorio se reemplaza por todos losFile
que se contienen de forma recursiva en ese directorio. - 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. - Cada argumento de la lista tiene el formato
format_each
, si está presente. - Si
uniquify
es verdadero, se quitan los argumentos duplicados. El primer caso es el que persiste. - Si se proporciona una cadena
before_each
, se inserta como un argumento nuevo antes de cada argumento existente en la lista. Esto duplica efectivamente la cantidad de argumentos que se agregarán en este punto. - Excepto en el caso de que la lista esté vacía y
omit_if_empty
sea verdadero (la configuración predeterminada), el nombre del argumento yterminate_with
se insertan como el primer y el último argumento, respectivamente, si se proporcionan.
Parámetros
Parámetro | Descripción |
---|---|
arg_name_or_values
|
required 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 (la configuración predeterminada) 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 conjunto de dependencias cuyos elementos se agregarán. |
map_each
|
que admite llamadas o None ; el valor predeterminado es None Es una función que convierte cada elemento en cero o más strings, que pueden procesarse antes de agregarse. Si no se proporciona este parámetro, se usa la conversión estándar. A la función se le pasan uno o dos argumentos posicionales: el elemento que se convertirá, seguido de un El tipo de valor que se muestra depende de la cantidad de argumentos que se deben producir para el elemento:
None tiene el mismo efecto que mostrar una lista de 1 o 0 elementos, respectivamente. Sin embargo, es más eficiente y legible evitar crear una lista donde no sea necesaria.Por lo general, los elementos que son directorios se expanden automáticamente a su contenido cuando se configura Para evitar la retención no deseada de estructuras de datos grandes de la fase de análisis en la fase de ejecución, la función Advertencia: Las sentencias |
format_each
|
string o None ; el valor predeterminado es None Es un patrón de string de formato opcional que se aplica a cada string que muestra 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 para agregar antes de cada argumento derivado de values .
|
omit_if_empty
|
el valor predeterminado es True Si es verdadero, si no hay argumentos derivados de values para agregar, todo el procesamiento posterior se suprimirá y la línea de comandos no se modificará. Si es falso, el nombre del argumento y terminate_with , si se proporcionan, se adjuntarán independientemente de si hay otros argumentos o no.
|
uniquify
|
El valor predeterminado es False Si es verdadero, se omitirán los argumentos duplicados que se deriven de values . Solo permanecerá el primer caso de cada argumento. Por lo general, no se necesita esta función porque los conjuntos de dependencias ya omiten los duplicados, pero puede ser útil si map_each emite la misma cadena para varios elementos.
|
expand_directories
|
El valor predeterminado es True Si es verdadero, los directorios de values se expandirán a una lista plana de archivos. Esto ocurre antes de que se aplique map_each .
|
terminate_with
|
cadena; o None ;
el valor predeterminado es None Es un argumento opcional para agregar después de todos los demás argumentos. Este argumento no se agregará si omit_if_empty es verdadero (la configuración predeterminada) y no se agregan otros elementos (como sucede si values está vacío o se filtran todos sus elementos).
|
allow_closure
|
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 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)
El procesamiento es similar a add_all()
, pero la lista de argumentos derivada de values
se combina en un solo argumento como si fuera join_with.join(...)
y, luego, se le da formato según la plantilla de cadenas format_joined
dada. A diferencia de add_all()
, no hay un parámetro 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 (el 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, 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 (el 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 conjunto de dependencias cuyos elementos se unirán. |
join_with
|
obligatorio Una cadena delimitadora que se usa para unir las cadenas obtenidas a partir de la aplicación de map_each y format_each , de la misma manera que string.join() .
|
map_each
|
que admite llamadas; o None ; el valor predeterminado es None . Igual que add_all .
|
format_each
|
cadena o None ;
el valor predeterminado es None Es igual que para add_all .
|
format_joined
|
string o None ; el valor predeterminado es None Es un patrón de string de formato opcional que se aplica a la string unida. La cadena de formato debe tener exactamente un marcador de posición “%s”. |
omit_if_empty
|
El valor predeterminado es True Si es verdadero, si no hay cadenas para unir (ya sea porque values está vacía o porque todos sus elementos están filtrados), se suprime todo el procesamiento adicional 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
|
el valor predeterminado es False . Igual que add_all .
|
expand_directories
|
El valor predeterminado es True Es igual que para add_all .
|
allow_closure
|
El valor predeterminado es False Es igual que para add_all .
|
set_param_file_format
Args Args.set_param_file_format(format)
Parámetros
Parámetro | Descripción |
---|---|
format
|
obligatorio Debe ser una de las siguientes opciones:
Si no se lo llama, el formato predeterminado es “shell”. |
use_param_file
Args Args.use_param_file(param_file_arg, *, use_always=False)
Para mayor eficiencia, Bazel puede optar por dejar de escribir el archivo de parámetros en el árbol de resultados durante la ejecución. Si estás depurando acciones y deseas inspeccionar el archivo de parámetros, pasa --materialize_param_files
a tu compilación.
Parámetros
Parámetro | Descripción |
---|---|
param_file_arg
|
obligatorio Es una cadena de formato con un solo "%s". Si los argumentos se vuelcan a un archivo de parámetros, se reemplazan por un argumento que consta de esta cadena con el formato de la ruta de acceso del archivo de parámetros. Por ejemplo, si los argumentos se vuelcan a un archivo de parámetros "params.txt", especificar "--file=%s" haría que la línea de comandos de la acción contenga "--file=params.txt". |
use_always
|
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 se deben derramar en función de la longitud del sistema y del argumento. |