Args

Un objeto que encapsula, de manera eficiente en términos de memoria, los datos necesarios para compilar una línea de comandos de forma parcial o total.

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 de File.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 a add(), y si los pasas a add_all() o add_joined(), debes proporcionar una función map_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 --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 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 = Ninguno
Es 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:

  1. Cada elemento File del directorio se reemplaza por todos los elementos File contenidos de manera recursiva en ese directorio.
  2. 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.
  3. Cada argumento de la lista tiene el formato format_each, si está presente.
  4. Si el elemento uniquify es verdadero, se quitan los argumentos duplicados. El primer caso es el que queda.
  5. 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.
  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 sujetos a todos estos pasos de procesamiento.

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 = unbound
La lista, tupla o desset cuyos elementos se agregarán.
map_each callable; or None; default = None
Es 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 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 del valor que se muestra depende de la cantidad de argumentos que se deben producir para el elemento:

  • En el caso común cuando cada elemento se convierte en una string, la función debería mostrar esa string.
  • Si se desea filtrar el elemento por completo, la función debe mostrar None.
  • Si el elemento se convierte en varias cadenas, la función devuelve una lista de esas cadenas.
Mostrar una sola string o 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 expand_directories=True. Sin embargo, esta acción no expandirá los directorios que están dentro de otros valores, por ejemplo, cuando los elementos son structs que tienen directorios como campos. En esta situación, se puede aplicar el argumento DirectoryExpander para obtener de forma manual los archivos de un directorio determinado.

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 map_each debe declararse mediante una sentencia def de nivel superior; no puede ser un cierre de función anidada de forma predeterminada.

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

format_each string; or None; predeterminado = Ninguno
Es 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 = Ninguno
Se 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 = Ninguno
Es 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 = unbound
La 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 = None
Igual que para add_all.
format_each string; or None; default = None
Igual que para add_all.
format_joined string; or None; predeterminado = Ninguno
Es 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:
  • “multiline”: Cada elemento (nombre o valor del argumento) se escribe textualmente en el archivo de parámetros con un carácter de línea nueva a continuación.
  • "shell": Igual que "multiline", pero los elementos están entre comillas de shell
  • “flag_per_line”: Igual que “multilínea”, pero (1) solo se escriben marcas (que comienzan con “--”) en el archivo de parámetros y (2) los valores de las marcas, si las hubiera, se escriben en la misma línea con un separador “=”. Este es el formato que espera la biblioteca de marcas Abseil.

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.