Muitas vezes, uma ação exige uma linha de comando grande contendo 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. É uma prática recomendada armazenar esses dados transitivos em depset
s para que possam ser compartilhados por vários destinos. No entanto, se o autor da regra tivesse que converter esses depsets em listas de strings para criar uma linha de comando de ação, isso invalidaria essa otimização de compartilhamento de memória.
Por esse motivo, as funções de criação de ações aceitam objetos Args
, além das 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 encapsulados 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é a conclusão da fase de análise. Consulte a página Como otimizar o desempenho para mais informações.
Args
são construídos 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á esta:
- Os valores que já são strings são deixados como estão.
- Objetos
File
são transformados nos valoresFile.path
. - 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 você os transmitir 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 forma que a substituição de %
em strings, exceto que o modelo precisa ter exatamente um marcador de substituição e ser %s
. As porcentagens literais podem ter escape como %%
. A formatação é aplicada depois que o valor é convertido em uma string, conforme descrito acima.
Cada um dos métodos add*()
tem um formulário alternativo que aceita um parâmetro de posição extra, uma string "arg name" para inserir antes dos outros 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 limite permitido pelo sistema, os argumentos poderão ser espalhados em arquivos de parâmetros. Consulte use_param_file()
e set_param_file_format()
.
Exemplo: suponha que quiséssemos gerar a linha de comando:
--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --bazPoderíamos 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], ... )
Participantes
adicionar
Args Args.add(arg_name_or_value, value=unbound, *, format=None)Anexa um argumento a esta linha de comando.
Parâmetros
Parâmetro | Descrição |
---|---|
arg_name_or_value
|
obrigatório Se dois parâmetros de posição forem passados, isso será interpretado como o nome do argumento. O nome do argumento é adicionado antes do valor sem processamento. Se apenas um parâmetro de posição for transmitido, ele será interpretado como value (confira abaixo).
|
value
|
padrão = não vinculado 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 transmitida para add_all() ou add_joined() em vez desse método.
|
format
|
string; or None ;
default = NoneUm padrão de string de formato a ser aplicado à versão 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)Anexa vários argumentos a esta linha de comando. Os itens são processados lentamente 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:
- Cada item
File
de diretório é substituído por todos osFile
s recursivamente contidos 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 inicial. Caso contrário, a lista inicial de argumentos será o resultado da aplicação da conversão padrão a cada item. - Cada argumento na lista será formatado com
format_each
, se estiver 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 existente na lista. Isso dobra o número de argumentos a serem anexados a esse ponto. - Exceto quando a lista estiver vazia e
omit_if_empty
for verdadeiro (padrão), o nome do argumento eterminate_with
serão inseridos como o primeiro e o último argumentos, respectivamente, se fornecidos.
Parâmetros
Parâmetro | Descrição |
---|---|
arg_name_or_values
|
obrigatório Se dois parâmetros de posição forem passados, isso será interpretado como o nome do argumento. O nome do argumento é adicionado antes do values sem nenhum 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 de posição for transmitido, ele será interpretado como values (confira abaixo).
|
values
|
sequence; or depset ;
default = unboundA lista, tupla ou depset com itens que serão anexados. |
map_each
|
callable; or None ;
default = NoneUma função que converte cada item em zero ou mais strings, que podem ser processadas antes da anexação. 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 devem ser produzidos para o item:
None tem o mesmo efeito que retornar uma lista com comprimento 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 Para evitar a retenção não intencional de grandes estruturas de dados na fase de análise na fase de execução, a função Aviso:as instruções |
format_each
|
string; or None ;
default = NoneUm padrão de string de formato opcional, aplicado a cada string retornada pela função map_each . A string de formatação precisa ter exatamente um marcador "%s".
|
before_each
|
string; or None ;
default = NoneUma string opcional para anexar antes de cada argumento derivado de values .
|
omit_if_empty
|
default = True Se for verdadeiro, se não houver argumentos derivados de values a serem anexados, todo o processamento será suprimido e a linha de comando não vai mudar. Se for falso, o nome do argumento e terminate_with , se fornecido, ainda serão anexados, independentemente de haver ou não outros argumentos.
|
uniquify
|
default = False Se verdadeiro, os argumentos duplicados derivados de values serão omitidos. Apenas a primeira ocorrência de cada argumento permanecerá. Normalmente, esse recurso não é necessário porque os depsets já omitem duplicatas, mas pode ser útil se map_each emitir a mesma string para vários itens.
|
expand_directories
|
default = True Se verdadeiro, todos os diretórios em values serão expandidos em uma lista simples de arquivos. Isso acontece antes da aplicação da map_each .
|
terminate_with
|
string; or None ;
default = NoneUma string opcional para anexar depois de todos os outros argumentos. Essa string não será adicionada 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
|
default = False Se verdadeiro, permite o uso de fechamentos em parâmetros de função, como map_each . Em geral, isso não é necessário e há 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)Anexa um argumento a esta linha de comando concatenando vários valores com um separador. Os itens são processados lentamente durante a fase de execução.
O processamento é semelhante ao add_all()
, mas a lista de argumentos derivados de values
é combinada em um único argumento, como se fosse join_with.join(...)
, e formatada usando o modelo de string format_joined
fornecido. 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 mesclar em um argumento e se omit_if_empty
for verdadeiro (o padrão), nenhum processamento será feito. 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
|
obrigatório Se dois parâmetros de posição forem passados, 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 mesclar. Isso pode acontecer se values estiver vazio ou se todos os itens dele forem filtrados. Se apenas um parâmetro de posição for transmitido, ele será interpretado como values (confira abaixo).
|
values
|
sequence; or depset ;
default = unboundA lista, a tupla ou a depset com itens que serão unidos. |
join_with
|
obrigatório Uma string delimitador usada para unir as strings extraídas da aplicação de map_each e format_each , da mesma maneira que string.join() .
|
map_each
|
callable; or None ;
padrão = NoneIgual a add_all .
|
format_each
|
string; or None ;
padrão = NoneIgual a add_all .
|
format_joined
|
string; or None ;
default = NoneUm padrão de string de formato opcional aplicado à string unida. A string de formatação precisa ter exatamente um marcador "%s". |
omit_if_empty
|
default = True Se for verdadeiro, se não houver strings para unir (porque values está vazio ou todos os itens estão filtrados), todo o processamento adicional será suprimido e a linha de comando não vai mudar. Se for falso, mesmo que não haja strings para unir, dois argumentos serão anexados: o nome do argumento seguido de uma string vazia (que é a junção lógica de zero strings).
|
uniquify
|
default = False Igual a add_all .
|
expand_directories
|
padrão = Verdadeiro Igual a add_all .
|
allow_closure
|
default = 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
|
obrigatório 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)Espalha os argumentos para um arquivo de parâmetros, substituindo-os por um ponteiro para o arquivo de parâmetros. Use quando seus argumentos forem muito grandes para os limites de comprimento do comando do sistema.
Para fins de eficiência, o Bazel pode evitar a gravação do arquivo de parâmetros na árvore de saída durante a execução. Se você estiver depurando ações e quiser inspecionar o arquivo de parâmetro, transmita --materialize_param_files
para seu build.
Parâmetros
Parâmetro | Descrição |
---|---|
param_file_arg
|
obrigatório Uma string de formatação com um único "%s". Se os argumentos forem espalhados 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 espalhados para um arquivo de parâmetros "params.txt", a especificação de "--file=%s" fará com que a linha de comando de ação contenha "--file=params.txt". |
use_always
|
default = False Define se os argumentos sempre são enviados para um arquivo de parâmetros. Se definido como falso, o bazel decidirá se os argumentos precisam ser espalhados com base no seu sistema e no comprimento do argumento. |