A menudo, una acción requiere una gran línea de comandos que contenga 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. La práctica recomendada es almacenar estos datos transitivos en depset
para que puedan compartirse con varios destinos. Sin embargo, si el autor de la regla tuviera que convertir estos elementos 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 dependencias, con transformaciones opcionales para manipular los datos. Los objetos Args
no procesan las dependencias que encapsulan hasta la fase de ejecución, cuando llega el momento de calcular la línea de comandos. Esto ayuda a diferir las copias costosas hasta después de que se complete la fase de análisis. Consulta la página Cómo optimizar el rendimiento para obtener más información.
Args
se crean 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 eventual.
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 será la siguiente:
- Los valores que ya son cadenas se dejan tal como están.
- Los objetos
File
se convierten en sus valores deFile.path
. - Todos los demás tipos se convierten en cadenas no especificadas. Por este motivo, debes evitar pasar valores que no sean de tipo string o
File
aadd()
, y si los pasas aadd_all()
oadd_joined()
, debes proporcionar una funciónmap_each
.
Cuando se usa el formato de cadena (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, con la excepción de que la plantilla debe tener exactamente un marcador de posición de sustitución y debe ser %s
. Los porcentajes literales pueden escaparse como %%
. El formato se aplica después de que el valor se convierte en una string, como se indica más arriba.
Cada uno de los métodos add*()
tiene una forma alternativa que acepta un parámetro posicional adicional, una cadena de "arg name" para insertar antes del resto de los argumentos. Para add_all
y add_joined
, la cadena adicional no se agregará 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, dependiendo de si la secuencia dada 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, es posible que los argumentos se conviertan en 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 --bazPodrí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
|
required Si se pasan dos parámetros posicionales, se interpreta como el nombre del argumento. El nombre del argumento se agrega antes que el valor sin ningún procesamiento. Si solo se pasa un parámetro posicional, se interpreta como value (consulta a continuación).
|
value
|
default = unbound El objeto que se adjuntará. Se convertirá en una cadena con la conversión estándar que se mencionó anteriormente. Como no hay un parámetro map_each para esta función, value debe ser una cadena o un File . Una lista, una tupla, un depset o un directorio File se debe pasar a add_all() o add_joined() , en lugar de a este método.
|
format
|
string; or None ;
predeterminado = NingunoEs un patrón de cadena de formato que se aplica a la versión en 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 ocurre en una lista de argumentos que se deben agregar, según los pasos siguientes:
- Cada elemento
File
del directorio se reemplaza por todos los elementosFile
contenidos de manera recursiva en ese directorio. - Si se proporciona un
map_each
, se aplica a cada elemento, y las listas resultantes de cadenas se concatenan para formar la lista de argumentos inicial. De lo contrario, la lista inicial de argumentos 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 el elemento
uniquify
es verdadero, se quitan los argumentos duplicados. El primer caso es el que queda. - Si se proporciona una cadena
before_each
, se inserta como un argumento nuevo antes de cada argumento existente en la lista. Esto duplica eficazmente 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 (el valor predeterminado), 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, se interpreta como el nombre del argumento. El nombre del argumento se agrega antes de values sin ningún procesamiento. No se agregará este nombre de argumento 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; or depset ;
default = unboundLa lista, tupla o desset cuyos elementos se agregarán. |
map_each
|
callable; or None ;
default = NoneEs una función que convierte cada elemento en cero o más strings, que se pueden procesar antes de agregar. 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 El tipo del 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 longitud 1 o longitud 0, respectivamente. Sin embargo, es más eficiente y legible evitar crear una lista cuando no sea necesaria.Por lo general, los elementos que son directorios se expanden automáticamente a su contenido cuando se establece Para evitar la retención involuntaria de estructuras de datos de la fase de análisis grande en la fase de ejecución, la función Advertencia: Las sentencias |
format_each
|
string; or None ;
predeterminado = NingunoEs un patrón de cadena de formato opcional, que se aplica a cada cadena que muestra la función map_each . La cadena de formato debe tener exactamente un marcador de posición "%s".
|
before_each
|
string; or None ; predeterminado = NingunoSe agrega una cadena opcional para agregar antes de cada argumento derivado de values .
|
omit_if_empty
|
default = True Si no hay argumentos derivados de values que se agreguen, se suprime todo el procesamiento posterior y la línea de comandos no se modifica. Si es falso, el nombre del argumento y terminate_with , si se proporcionan, se seguirán agregando independientemente de si hay otros argumentos o no.
|
uniquify
|
default = False Si este valor es verdadero, se omitirán los argumentos duplicados que deriven de values . Solo se conserva el primer caso de cada argumento. Por lo general, esta función no es necesaria porque los depsets ya omiten duplicados, pero puede ser útil si map_each emite la misma cadena para varios elementos.
|
expand_directories
|
default = True Si es verdadero, los directorios de values se expandirán a una lista plana de archivos. Esto sucede antes de que se aplique la map_each .
|
terminate_with
|
string; or None ;
predeterminado = NingunoEs una cadena opcional para agregar después de todos los demás argumentos. No se agregará esta cadena si el valor de omit_if_empty es verdadero (configuración predeterminada) y no se agregan otros elementos (como sucede si values está vacío o se filtran todos sus elementos).
|
allow_closure
|
default = False Si es verdadero, se 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 fases 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 mediante la concatenación de 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 lo hiciera join_with.join(...)
y, luego, se le da formato con la plantilla de cadenas format_joined
dada. A diferencia de add_all()
, no hay ningún parámetro before_each
ni terminate_with
, ya que, por lo general, no son útiles cuando se combinan los elementos en un solo argumento.
Si después de filtrar no hay cadenas para unir en un argumento, y 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
|
required 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 todos sus elementos están filtrados). Si solo se pasa un parámetro posicional, se interpreta como values (consulta a continuación).
|
values
|
sequence; or depset ;
default = unboundLa lista, tupla o desset cuyos elementos se unirán. |
join_with
|
required Es una cadena delimitador que se usa para unir las cadenas obtenidas de aplicar map_each y format_each , de la misma manera que string.join() .
|
map_each
|
callable; or None ;
default = NoneIgual que para add_all .
|
format_each
|
string; or None ;
default = NoneIgual que para add_all .
|
format_joined
|
string; or None ;
predeterminado = NingunoEs un patrón de cadena de formato opcional aplicado a la cadena unida. La cadena de formato debe tener exactamente un marcador de posición "%s". |
omit_if_empty
|
default = True Si no hay strings para unir (ya sea porque values está vacío o porque se filtraron todos sus elementos), se suprime todo el procesamiento adicional y la línea de comandos no se modifica. Si es falso, incluso si no hay cadenas para unir, se anexarán dos argumentos: el nombre del argumento seguido de una cadena vacía (que es la unión lógica de las cadenas con cero).
|
uniquify
|
default = False Igual que para add_all .
|
expand_directories
|
default = True Igual que para add_all .
|
allow_closure
|
default = False Igual que para add_all .
|
set_param_file_format
Args Args.set_param_file_format(format)Configura el formato del archivo de parámetros, si se usa uno.
Parámetros
Parámetro | Descripción |
---|---|
format
|
obligatorio Debe ser uno de los siguientes:
Si no se llama, el formato predeterminado es “shell”. |
use_param_file
Args Args.use_param_file(param_file_arg, *, use_always=False)Devuelve los args en un archivo de parámetros y los reemplaza con un puntero al archivo de parámetros. Úsalo cuando tus argumentos sean demasiado grandes para los límites de longitud de los comandos del sistema.
Para mayor eficiencia, Bazel puede optar por no escribir el archivo de parámetros en el árbol de resultados durante la ejecución. 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
|
required Una string 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 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” provocaría que la línea de comandos de acción contenga “--file=params.txt”. |
use_always
|
default = False Establece si siempre se deben desbordar los args en un archivo de parámetros. Si es falso, Bazel decidirá si los argumentos deben derramarse en función de tu sistema y la longitud del argumento. |