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 necesarios para todas las bibliotecas vinculadas. Se recomienda almacenar los datos transitivos de este tipo en objetos depset
, de modo que puedan compartirse con varios destinos. Sin embargo, si el autor de la regla tuviera que convertir estas dependencias en listas de cadenas para construir una línea de comandos de acción, se vería afectada esta optimización del uso compartido de memoria.
Por este motivo, las funciones de construcción de acciones aceptan objetos Args
, además de strings. Cada objeto Args
representa una concatenación de strings 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 cualquier copia costosa hasta después de que se haya completado la fase de análisis. Consulta la página Cómo optimizar el rendimiento para obtener más información.
Args
se crea llamando a ctx.actions.args()
. Se pueden pasar como 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 strings. Si no proporcionas una función map_each
, la conversión estándar es la siguiente:
- Los valores que ya son cadenas quedan como están.
- Los objetos
File
se convierten en sus valores deFile.path
. - Todos los demás tipos se convierten en strings sin especificar. 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 string (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 strings, 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 cadena como se indicó anteriormente.
Cada uno de los métodos add*()
tiene una forma alternativa que acepta un parámetro posicional adicional, una string de "nombre de argumento" para insertar antes del resto de los argumentos. Para add_all
y add_joined
, la cadena adicional no se agregará si la secuencia está 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 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 incluir 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
|
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
|
default = unbound El objeto que se agregará. Se convertirá en una string mediante la conversión estándar mencionada anteriormente. Dado que no hay un parámetro map_each para esta función, value debe ser una string o una File . Una lista, una tupla, una depset o un directorio File debe pasarse 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 aplicará a la versión de value en cadena.
|
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 lleva a cabo en una lista de argumentos que se deben agregar, de acuerdo con los siguientes pasos:
- 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 strings 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 valor de
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 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 (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
|
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 nombre de argumento no se agregará si omit_if_empty es verdadero (el valor predeterminado) y no se agrega ningún otro elemento (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 = unboundEs la lista, tupla o depset cuyos elementos se agregarán. |
map_each
|
callable; or None ;
default = NoneUna función que convierte cada elemento en cero o más cadenas, que se pueden procesar antes de agregar datos. Si no se proporciona este parámetro, se usa la conversión estándar. La función recibe 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 longitud 1 o longitud 0, respectivamente. Sin embargo, es más eficiente y legible evitar crear una lista cuando no sea necesario.Por lo general, los elementos que son directorios se expanden automáticamente a su contenido cuando se configura Para evitar la retención involuntaria de grandes estructuras de datos de la fase de análisis en la fase de ejecución, la función Advertencia: Las sentencias |
format_each
|
string; or None ;
predeterminado = NingunoPatrón de string 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 = NingunoUna string opcional para agregar antes de que se agregue cada argumento derivado de values .
|
omit_if_empty
|
default = True Si este valor es verdadero, si no hay argumentos derivados de values para agregar, se suprimirá todo el procesamiento posterior y no se modificará la línea de comandos. Si es falso, se agregará el nombre del argumento y terminate_with , si se proporcionan, independientemente de si existen otros argumentos o no.
|
uniquify
|
default = False Si este valor es verdadero, se omitirán los argumentos duplicados que derivan de values . Solo se conserva el primer caso de cada argumento. Por lo general, esta función no es necesaria porque las dependencias ya omiten los duplicados, pero puede ser útil si map_each emite la misma cadena para varios elementos.
|
expand_directories
|
default = True Si es verdadero, cualquier directorio en values se expandirá a una lista plana de archivos. Esto sucede antes de que se aplique la map_each .
|
terminate_with
|
string; or None ;
predeterminado = NingunoUna string opcional para agregar después de todos los demás argumentos. Esta cadena no se agregará si omit_if_empty es verdadero (valor predeterminado) 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, permite el uso de cierres en parámetros de funciones como map_each . Por lo general, esto no es necesario y se arriesga a 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 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 fuera join_with.join(...)
y, luego, se le da formato con la plantilla de cadenas format_joined
dada. 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 strings para unir en un argumento, y si omit_if_empty
es verdadero (la opción predeterminada), no se realiza ningún procesamiento. De lo contrario, si no hay strings para unir, pero omit_if_empty
es falso, la string unida será una 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 (el valor predeterminado) y no hay cadenas derivadas de values para unirse (lo cual puede suceder 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 depset cuyos elementos se unirán. |
join_with
|
obligatorio Una cadena delimitadora que se usa para unir las cadenas que se obtienen de la aplicación de 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 = NingunoPatrón de string de formato opcional aplicado a la string unida. La cadena de formato debe tener exactamente un marcador de posición "%s". |
omit_if_empty
|
default = True Si el valor es verdadero, si no hay strings para unir (ya sea porque values está vacío o porque todos sus elementos están filtrados), 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 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
|
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)Establece 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 lo llama, el formato predeterminado es "shell". |
use_param_file
Args Args.use_param_file(param_file_arg, *, use_always=False)Devuelve los argumentos en un archivo de parámetros y los reemplaza por 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.
Bazel puede optar por escribir el archivo de parámetros en el árbol de resultados durante la ejecución para lograr una mayor eficiencia. Si depuras 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
|
obligatorio String de formato con un solo “%s”. Si los argumentos se despliegan en un archivo de parámetros, se reemplazan por un argumento que consta de esta string con el formato de la ruta de acceso del archivo de parámetros. Por ejemplo, si los argumentos se despliegan 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 Especifica si siempre se deben desbordar los argumentos en un archivo de parámetros. Si es falso, Bazel decidirá si los argumentos deben desbordarse en función de tu sistema y la longitud del argumento. |