Args

Informar um problema Ver fonte Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Um objeto que encapsula, de maneira eficiente em termos de memória, os dados necessários para criar parte ou toda uma linha de comando.

Muitas vezes, uma ação exige uma linha de comando grande com valores acumulados de dependências transitivas. Por exemplo, uma linha de comando do vinculador pode listar todos os arquivos de objeto necessários para todas as bibliotecas vinculadas. A prática recomendada é armazenar esses dados transitivos em depsets para que possam ser compartilhados por várias metas. No entanto, se o autor da regra precisasse converter esses depsets em listas de strings para construir uma linha de comando de ação, isso prejudicaria essa otimização de compartilhamento de memória.

Por isso, as funções de construção de ações aceitam objetos Args além de strings. Cada objeto Args representa uma concatenação de strings e depsets, com transformações opcionais para manipular os dados. Os objetos Args não processam os conjuntos de dependências que encapsulam até a fase de execução, quando chega a hora de calcular a linha de comando. Isso ajuda a adiar qualquer cópia cara até que a fase de análise seja concluída. Consulte a página Como otimizar o desempenho para mais informações.

Os Args são criados chamando ctx.actions.args(). Eles podem ser transmitidos como o parâmetro arguments de ctx.actions.run() ou ctx.actions.run_shell(). Cada mutação de um objeto Args anexa valores à linha de comando final.

O recurso map_each permite personalizar a transformação de itens em strings. Se você não fornecer uma função map_each, a conversão padrão será a seguinte:

  • Os valores que já são strings permanecem como estão.
  • Os objetos File são transformados em valores File.path.
  • Os objetos Label são transformados em uma representação de string que é resolvida de volta para o mesmo objeto quando resolvida no contexto do repositório principal. Se possível, a representação de string usa o nome aparente de um repositório em vez do nome canônico dele, o que torna essa representação adequada para uso em arquivos BUILD. Embora a forma exata da representação não seja garantida, exemplos típicos são //foo:bar, @repo//foo:bar e @@canonical_name+//foo:bar.bzl.
  • Todos os outros tipos são transformados em strings de maneira não especificada. Por esse motivo, evite transmitir valores que não sejam do tipo string ou File para add(). Se você transmitir para add_all() ou add_joined(), forneça uma função map_each.

Ao usar a formatação de string (parâmetros format, format_each e format_joined dos métodos add*()), o modelo de formato é interpretado da mesma forma que a substituição de % em strings, exceto que o modelo precisa ter exatamente um marcador de posição de substituição, que precisa ser %s. Os percentuais literais podem ter escape como %%. A formatação é aplicada depois que o valor é convertido em uma string, conforme acima.

Cada um dos métodos add*() tem uma forma alternativa que aceita um parâmetro posicional extra, uma string "nome do argumento" para inserir antes do restante dos argumentos. Para add_all e add_joined, a string extra não será adicionada se a sequência estiver vazia. Por exemplo, o mesmo uso pode adicionar --foo val1 val2 val3 --bar ou apenas --bar à linha de comando, dependendo se a sequência especificada contém val1..val3 ou está vazia.

Se o tamanho da linha de comando puder exceder o limite máximo permitido pelo sistema, os argumentos poderão ser transferidos para arquivos de parâmetros. Consulte use_param_file() e set_param_file_format().

Exemplo: suponha que você queira gerar a linha de comando: 

--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz
Podemos usar o seguinte 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],
  ...
)

Membros

adicionar

Args Args.add(arg_name_or_value, value=unbound, *, format=None)

Adiciona um argumento a essa linha de comando.

Parâmetros

Parâmetro Descrição
arg_name_or_value required
Se dois parâmetros posicionais forem transmitidos, isso será interpretado como o nome do argumento. O nome do argumento é adicionado antes do valor sem nenhum processamento. Se apenas um parâmetro posicional for transmitido, ele será interpretado como value (veja abaixo).
value O padrão é unbound
O objeto a ser anexado. Ele será convertido em uma string usando a conversão padrão mencionada acima. Como não há parâmetro map_each para essa função, value precisa ser uma string ou um File. Uma lista, tupla, conjunto de dependências ou diretório File precisa ser transmitido para add_all() ou add_joined() em vez deste método.
format string ou None. O padrão é None
. Um padrão de string de formato a ser aplicado à versão de string 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)

Adiciona vários argumentos a essa linha de comando. Os itens são processados de forma lenta durante a fase de execução.

A maior parte do processamento ocorre em uma lista de argumentos a serem anexados, de acordo com as seguintes etapas:

  1. Cada item de diretório File é substituído por todos os Files contidos recursivamente nesse diretório.
  2. Se map_each for fornecido, ele será aplicado a cada item, e as listas de strings resultantes serão concatenadas para formar a lista de argumentos inicial. Caso contrário, a lista de argumentos inicial é o resultado da aplicação da conversão padrão a cada item.
  3. Cada argumento na lista é formatado com format_each, se presente.
  4. Se uniquify for verdadeiro, os argumentos duplicados serão removidos. A primeira ocorrência é a que permanece.
  5. Se uma string before_each for fornecida, ela será inserida como um novo argumento antes de cada argumento na lista. Isso dobra o número de argumentos a serem anexados até esse ponto.
  6. Exceto no caso em que a lista está vazia e omit_if_empty é verdadeiro (o padrão), o nome do argumento e terminate_with são inseridos como o primeiro e o último argumentos, respectivamente, se forem fornecidos.
Strings vazias são argumentos válidos que estão sujeitos a todas essas etapas de processamento.

Parâmetros

Parâmetro Descrição
arg_name_or_values required
Se dois parâmetros posicionais forem transmitidos, isso será interpretado como o nome do argumento. O nome do argumento é adicionado antes do values como um argumento separado, sem processamento. Esse nome de argumento não será adicionado se omit_if_empty for verdadeiro (o padrão) e nenhum outro item for anexado (como acontece se values estiver vazio ou todos os itens forem filtrados). Se apenas um parâmetro posicional for transmitido, ele será interpretado como values (veja abaixo).
values sequence ou depset; o padrão é unbound
A lista, a tupla ou o conjunto de dependências cujos itens serão anexados.
map_each chamável ou None; o padrão é None
. Uma função que converte cada item em zero ou mais strings, que podem ser processadas antes de serem anexadas. Se esse parâmetro não for fornecido, a conversão padrão será usada.

A função recebe um ou dois argumentos posicionais: o item a ser convertido, seguido por um DirectoryExpander opcional. O segundo argumento será transmitido apenas se a função fornecida for definida pelo usuário (não integrada) e declarar mais de um parâmetro.

O tipo do valor de retorno depende de quantos argumentos serão produzidos para o item:

  • No caso comum em que cada item se torna uma string, a função precisa retornar essa string.
  • Se o item precisar ser totalmente filtrado, a função vai retornar None.
  • Se o item se transformar em várias strings, a função vai retornar uma lista delas.
Retornar uma única string ou None tem o mesmo efeito que retornar uma lista de tamanho 1 ou 0, respectivamente. No entanto, é mais eficiente e legível evitar a criação de uma lista quando ela não é necessária.

Normalmente, os itens que são diretórios são expandidos automaticamente para o conteúdo quando expand_directories=True é definido. No entanto, isso não vai expandir diretórios contidos em outros valores, por exemplo, quando os itens são structs que têm diretórios como campos. Nessa situação, o argumento DirectoryExpander pode ser aplicado para obter manualmente os arquivos de um determinado diretório.

Para evitar a retenção não intencional de grandes estruturas de dados da fase de análise na fase de execução, a função map_each precisa ser declarada por uma instrução def de nível superior. Por padrão, ela não pode ser um fechamento de função aninhada.

Aviso:as instruções print() executadas durante a chamada para map_each não produzem saída visível.

format_each string ou None. O padrão é None
. Uma string de formato opcional, aplicada a cada string retornada pela função map_each. A string de formato precisa ter exatamente um marcador de posição "%s".
before_each string ou None. O padrão é None
. Um argumento opcional a ser anexado antes de cada argumento derivado de values.
omit_if_empty bool; o padrão é True
Se for "true", e não houver argumentos derivados de values para serem anexados, todo o processamento posterior será suprimido e a linha de comando não será alterada. Se for "false", o nome do argumento e terminate_with, se fornecidos, ainda serão anexados, independentemente de haver outros argumentos.
uniquify bool; o padrão é False
Se for verdadeiro, os argumentos duplicados derivados de values serão omitidos. Somente a primeira ocorrência de cada argumento vai permanecer. Normalmente, esse recurso não é necessário porque os depsets já omitem duplicados, mas pode ser útil se map_each emitir a mesma string para vários itens.
expand_directories bool; o padrão é True
Se for "verdadeiro", todos os diretórios em values serão expandidos para uma lista simples de arquivos. Isso acontece antes de map_each ser aplicado.
terminate_with string ou None; o padrão é None
Um argumento opcional a ser anexado depois de todos os outros argumentos. Esse argumento não será adicionado se omit_if_empty for verdadeiro (o padrão) e nenhum outro item for anexado (como acontece se values estiver vazio ou todos os itens forem filtrados).
allow_closure bool; o padrão é False
Se for verdadeiro, permite o uso de closures em parâmetros de função como map_each. Normalmente, isso não é necessário e corre o risco de reter grandes estruturas de dados da fase de análise na fase de execução.

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)

Adiciona um argumento a essa linha de comando concatenando vários valores usando um separador. Os itens são processados de forma lenta durante a fase de execução.

O processamento é semelhante a add_all(), mas a lista de argumentos derivada de values é combinada em um único argumento como se fosse por join_with.join(...) e formatada usando o modelo de string format_joined. Ao contrário de add_all(), não há parâmetros before_each ou terminate_with, já que eles geralmente não são úteis quando os itens são combinados em um único argumento.

Se, após a filtragem, não houver strings para unir em um argumento e se omit_if_empty for verdadeiro (o padrão), nenhum processamento será feito. Caso contrário, se não houver strings para unir, mas omit_if_empty for falso, a string unida será uma string vazia.

Parâmetros

Parâmetro Descrição
arg_name_or_values required
Se dois parâmetros posicionais forem transmitidos, isso será interpretado como o nome do argumento. O nome do argumento é adicionado antes de values sem processamento. Esse argumento não será adicionado se omit_if_empty for verdadeiro (o padrão) e não houver strings derivadas de values para unir (o que pode acontecer se values estiver vazio ou se todos os itens dele forem filtrados). Se apenas um parâmetro posicional for transmitido, ele será interpretado como values (veja abaixo).
values sequence ou depset. O padrão é unbound
. A lista, a tupla ou o depset cujos itens serão unidos.
join_with string; required
Uma string delimitadora usada para unir as strings obtidas ao aplicar map_each e format_each, da mesma forma que string.join().
map_each chamável ou None. O padrão é None
. Igual a add_all.
format_each string; ou None; o padrão é None
Igual a add_all.
format_joined string ou None; o padrão é None
Um padrão de string de formato opcional aplicado à string unida. A string de formato precisa ter exatamente um marcador de posição "%s".
omit_if_empty bool; o padrão é True
Se for "true" e não houver strings para unir (porque values está vazio ou todos os itens foram filtrados), todo o processamento será suprimido e a linha de comando não será alterada. Se for "false", mesmo que não haja strings para unir, dois argumentos serão anexados: o nome do argumento seguido por uma string vazia (que é a junção lógica de zero strings).
uniquify bool; o padrão é False
Igual a add_all.
expand_directories bool; o padrão é True
Igual a add_all.
allow_closure bool; o padrão é False
Igual a add_all.

set_param_file_format

Args Args.set_param_file_format(format)

Define o formato do arquivo de parâmetros, se um for usado.

Parâmetros

Parâmetro Descrição
format string; required
Must be one of:
  • "multiline": cada item (nome ou valor do argumento) é gravado literalmente no arquivo de parâmetros com um caractere de nova linha após ele.
  • "shell": igual a "multiline", mas os itens são entre aspas simples.
  • "flag_per_line": igual a "multiline", mas (1) apenas flags (que começam com "--") são gravadas no arquivo de parâmetros e (2) os valores das flags, se houver, são gravados na mesma linha com um separador "=". Esse é o formato esperado pela biblioteca de flags do Abseil.

O formato padrão é "shell" se não for chamado.

use_param_file

Args Args.use_param_file(param_file_arg, *, use_always=False)

Transborda os argumentos para um arquivo de parâmetros, substituindo-os por um ponteiro para o arquivo de parâmetros. Use quando os argumentos forem muito grandes para os limites de comprimento de comando do sistema.

O Bazel pode optar por não gravar o arquivo de parâmetros na árvore de saída durante a execução para aumentar a eficiência. Se você estiver depurando ações e quiser inspecionar o arquivo de parâmetros, transmita --materialize_param_files para sua build.

Parâmetros

Parâmetro Descrição
param_file_arg string; required
Uma string de formato com um único "%s". Se os argumentos forem transferidos para um arquivo de parâmetros, eles serão substituídos por um argumento que consiste nessa string formatada com o caminho do arquivo de parâmetros.

Por exemplo, se os argumentos forem transferidos para um arquivo de parâmetros "params.txt", especificar "--file=%s" fará com que a linha de comando da ação contenha "--file=params.txt".

use_always bool; o padrão é False
Define se os argumentos sempre devem ser transferidos para um arquivo de parâmetros. Se for "false", o bazel vai decidir se os argumentos precisam ser divididos com base no seu sistema e no comprimento do argumento.