Args

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

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 de File.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 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 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 --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 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 = Ninguno
Es 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:

  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 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.
  3. Cada argumento de la lista tiene el formato format_each, si está presente.
  4. Si el valor de 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 efectivamente 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 strings 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 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 = unbound
Es la lista, tupla o depset cuyos elementos se agregarán.
map_each callable; or None; default = None
Una 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 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 deben producir para el elemento:

  • En el caso común en el que cada elemento se convierte en una string, la función debería mostrar esa string.
  • Si se va a filtrar el elemento por completo, la función debe mostrar None.
  • Si el elemento se convierte en varias strings, la función muestra una lista de esas strings.
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 necesario.

Por lo general, los elementos que son directorios se expanden automáticamente a su contenido cuando se configura 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, se puede aplicar el argumento DirectoryExpander para obtener manualmente los archivos de un directorio determinado.

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 map_each debe declararse mediante una sentencia def de nivel superior. Puede no 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
Patró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 = Ninguno
Una 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 = Ninguno
Una 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 = unbound
La 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 = 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
Patró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:
  • “multiline”: Cada elemento (nombre o valor del argumento) se escribe literalmente en el archivo de parámetros con un carácter de salto de línea después de él.
  • "shell": Igual que "multiline", pero los elementos están entrecomillados por shell
  • “flag_per_line” es igual a “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 hubiera, en la misma línea, con un separador “=”. Este es el formato que espera la biblioteca de marcas Abseil.

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.