Um objeto que encapsula, com eficiência de memória, os dados necessários para criar parte ou a totalidade de uma linha de comando.
Muitas vezes, uma ação exige uma grande linha de comando contendo valores acumulados de dependências transitivas. Por exemplo, uma linha de comando do vinculador pode listar todos os arquivos de objeto necessários por todas as bibliotecas vinculadas. É recomendável armazenar esses dados transitivos em depset
s para que possam ser compartilhados por vários destinos. 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 anularia essa otimização de compartilhamento de memória.
Por esse motivo, 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 depsets 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.
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 eventual.
O recurso map_each
permite personalizar como os itens são transformados 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 são mantidos como estão.
- Os objetos
File
são transformados nos valores deFile.path
. - Os objetos
Label
são transformados em uma representação de string que resolve o mesmo objeto quando resolvido 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, 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
paraadd()
. Se eles forem transmitidos paraadd_all()
ouadd_joined()
, forneça uma funçãomap_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 maneira que a substituição %
em strings, exceto pelo fato de que o modelo precisa ter exatamente um marcador de posição de substituição e ser %s
. As porcentagens de literal podem ter escape como %%
. A formatação é aplicada depois que o valor é convertido em uma string, conforme mostrado acima.
Cada um dos métodos add*()
tem uma forma alternativa que aceita um parâmetro posicional extra, uma string "arg name" 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 ultrapassar o tamanho máximo permitido pelo sistema, os argumentos poderão ser espalhados para os arquivos de parâmetros. Consulte use_param_file()
e set_param_file_format()
.
Exemplo: suponha que queremos gerar a linha de comando:
--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz
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)
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 (consulte 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á um parâmetro map_each para essa função, value precisa ser uma string ou um File . Uma lista, tupla, depset 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 convertida em 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)
A maior parte do processamento ocorre em uma lista de argumentos a serem anexados, conforme as etapas a seguir:
- Cada item
File
do diretório é substituído por todos osFile
s contidos recursivamente nesse diretório. - 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 iniciais. Caso contrário, a lista inicial de argumentos vai ser o resultado da aplicação da conversão padrão a cada item. - Cada argumento na lista é formatado com
format_each
, se presente. - Se
uniquify
for verdadeiro, os argumentos duplicados serão removidos. A primeira ocorrência é a que permanece. - Se uma string
before_each
for fornecida, ela será inserida como um novo argumento antes de cada argumento atual na lista. Isso dobra o número de argumentos a serem anexados até esse ponto. - Exceto no caso em que a lista está vazia e
omit_if_empty
é verdadeiro (padrão), o nome do argumento eterminate_with
são inseridos como o primeiro e o último argumento, respectivamente, se forem fornecidos.
Parâmetros
Parâmetro | Descrição |
---|---|
arg_name_or_values
|
obrigatório Se dois parâmetros de posição forem transmitidos, ele será interpretado como o nome do argumento. O nome do argumento é adicionado antes do values como um argumento separado sem nenhum processamento. Esse nome de argumento não será adicionado se omit_if_empty for verdadeiro (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 (consulte abaixo).
|
values
|
sequência ou depset;
o padrão é unbound . A lista, tupla ou depset cujos itens serão anexados. |
map_each
|
callable ou None ;
o padrão é None Uma função que converte cada item em zero ou mais strings, que podem ser processadas antes do anexo. 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 O tipo do valor de retorno depende de quantos argumentos serão produzidos para o item:
None tem o mesmo efeito que retornar uma lista de comprimento 1 ou 0, respectivamente. No entanto, é mais eficiente e legível evitar a criação de uma lista onde ela não é necessária.Normalmente, os itens que são diretórios são expandidos automaticamente para o conteúdo quando 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 Aviso:as instruções |
format_each
|
string; ou None ; o padrão é None . Um padrão de string de formato opcional, aplicado 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 para anexar antes de cada argumento derivado de values .
|
omit_if_empty
|
bool;
o padrão é True . Se verdadeiro, se não houver argumentos derivados de values a serem anexados, todo o processamento adicional será suprimido e a linha de comando não será alterada. Se for false, o nome do argumento e o terminate_with , se fornecidos, ainda serão anexados, independentemente de haver ou não outros argumentos.
|
uniquify
|
bool;
o padrão é False Se verdadeiro, os argumentos duplicados derivados de values serão omitidos. Apenas a primeira ocorrência de cada argumento vai permanecer. Normalmente, esse recurso não é necessário porque os depsets já omitem cópias, mas pode ser útil se map_each emitir a mesma string para vários itens.
|
expand_directories
|
bool;
o padrão é True Se verdadeiro, todos os diretórios em values serão expandidos para uma lista simples de arquivos. Isso acontece antes da aplicação de map_each .
|
terminate_with
|
string ou None ;
o padrão é None Um argumento opcional para anexar depois de todos os outros argumentos. Esse argumento não será adicionado se omit_if_empty for verdadeiro (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 verdadeiro, permite o uso de fechamentos em parâmetros de função, como map_each . Normalmente, isso não é necessário e pode comprometer a retenção de 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)
O processamento é semelhante ao add_all()
, mas a lista de argumentos derivados de values
é combinada em um único argumento como se fosse por join_with.join(...)
e, em seguida, formatada usando o modelo de string format_joined
. Ao contrário de add_all()
, não há parâmetro 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 mesclar em um argumento e se omit_if_empty
for verdadeiro (padrão), nenhum processamento será concluído. Caso contrário, se não houver strings para mesclar, 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 nenhum processamento. Esse argumento não será adicionado se omit_if_empty for verdadeiro (padrão) e não houver strings derivadas de values para serem combinadas. Isso 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 (consulte abaixo).
|
values
|
sequence ou depset.
O padrão é unbound . A lista, tupla ou depset cujos itens serão unidos. |
join_with
|
string;
required Uma string delimitadora usada para juntar as strings obtidas ao aplicar map_each e format_each , da mesma maneira 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 O mesmo que add_all .
|
format_joined
|
string ou None ;
O padrão é None Um padrão de string de formato opcional aplicado à string combinada. A string de formato precisa ter exatamente um marcador "%s". |
omit_if_empty
|
bool;
o padrão é True Se verdadeiro, se não houver strings para serem combinadas (porque values está vazia ou todos os itens dela foram filtrados), todo o processamento adicional será suprimido e a linha de comando não será alterada. Se for falso, mesmo que não haja strings para serem combinadas, dois argumentos serão anexados: o nome do argumento seguido por uma string vazia (que é a união lógica de strings nulas).
|
uniquify
|
bool;
O padrão é False O mesmo que add_all .
|
expand_directories
|
bool;
O padrão é True O mesmo que add_all .
|
allow_closure
|
bool;
O padrão é False O mesmo que add_all .
|
set_param_file_format
Args Args.set_param_file_format(format)
Parâmetros
Parâmetro | Descrição |
---|---|
format
|
string;
required Precisa ser um dos seguintes:
Se não for chamado, o formato padrão será "shell". |
use_param_file
Args Args.use_param_file(param_file_arg, *, use_always=False)
O Bazel pode optar por omitir a gravação do arquivo de parâmetros na árvore de saída durante a execução para maior eficiência. Se você estiver depurando ações e quiser inspecionar o arquivo de parâmetro, transmita --materialize_param_files
para o build.
Parâmetros
Parâmetro | Descrição |
---|---|
param_file_arg
|
string:
obrigatório 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", a especificação de "--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 serão sempre transferidos para um arquivo de parâmetros. Se for falso, o Bazel vai decidir se os argumentos precisam ser espalhados com base no sistema e no comprimento do argumento. |