args

Informar um problema Ver código-fonte

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

Muitas vezes, uma ação requer 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. É uma prática recomendada armazenar esses dados transitórios em depsets para que eles possam ser compartilhados por vários destinos. No entanto, se o autor da regra tiver que converter essas dependências em listas de strings para construir uma linha de comando de ação, a otimização do compartilhamento de memória será rejeitada.

Por esse motivo, as funções de construção de ação 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 anexos 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é que a fase de análise seja concluída. 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á a seguinte:

  • Os valores que já são strings são deixados como estão.
  • Os objetos File são transformados nos valores File.path deles.
  • 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ê os 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 % nas strings, exceto pelo fato de que o modelo precisa ter exatamente um marcador de posição e precisa ser %s. As porcentagens de literal podem ser escapadas como %%. A formatação é aplicada depois que o valor é convertido em uma string, conforme mostrado acima.

Cada método add*() tem uma forma alternativa que aceita um parâmetro de posição 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 contém val1..val3 ou está vazia.

Se o tamanho da linha de comando pode crescer por mais tempo do que o tamanho máximo permitido pelo sistema, os argumentos podem ser derramados em arquivos de parâmetros. Consulte use_param_file() e set_param_file_format().

Exemplo: suponha que queríamos gerar a linha de comando: 

--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz
Poderí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 transmitidos, 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 (veja abaixo).
value default = unbound
O objeto a ser anexado. Ela será convertida 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 = None
Um padrão de string de formato a ser aplicado à versão em string de value.

adicionar_tudo

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:

  1. Cada item de diretório File é substituído por todos os Files recursivamente contidos 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 atual na lista. Isso efetivamente dobra o número de argumentos a serem anexados por este ponto.
  6. Exceto no caso de que a lista está vazia e omit_if_empty é verdadeiro (padrão), o nome do argumento e terminate_with são inseridos como o primeiro e último argumentos, respectivamente, se forem fornecidos.
Strings vazias são argumentos válidos e estão sujeitos a todas essas etapas de processamento.

Parâmetros

Parâmetro Descrição
arg_name_or_values obrigatório
Se dois parâmetros de posição forem transmitidos, isso será interpretado como o nome do argumento. O nome do argumento é adicionado antes de values como um argumento separado sem 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 se todos os itens forem filtrados. Se apenas um parâmetro de posição for transmitido, ele será interpretado como values (veja abaixo).
values sequence; or depset; default = unbound
A lista, a tupla ou o depset cujos itens serão anexados.
map_each callable; or None; default = None
Uma 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 DirectoryExpander opcional. O segundo argumento só será passado 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 devem ser produzidos para o item:

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

Normalmente, os itens que são diretórios são expandidos automaticamente para o conteúdo quando o expand_directories=True é definido. No entanto, isso não expandirá os diretórios contidos em outros valores -- por exemplo, quando os itens são estruturas que têm diretórios como campos. Nessa situação, o argumento DirectoryExpander pode ser aplicado para receber 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 uma saída visível.

format_each string; or None; default = None
Um padrão de string de formato opcional, aplicado a cada string retornada pela função map_each. A string do formato precisa ter exatamente um marcador "%s".
before_each string; or None; default = None
Um argumento opcional a ser anexado antes que cada argumento derivado de values seja anexado.
omit_if_empty default = True
Se verdadeiro, se não houver argumentos derivados de values para serem anexados, todo o processamento adicional será suprimido e a linha de comando não será alterada. Se for falso, o nome do argumento e terminate_with, se fornecido, ainda serão anexados, independentemente de haver outros argumentos.
uniquify default = False
Se verdadeiro, os argumentos duplicados derivados de values serão omitidos. Somente a primeira ocorrência de cada argumento permanecerá. Normalmente, esse recurso não é necessário porque as dependências já omitem cópias, 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 para uma lista simples de arquivos. Isso acontece antes da aplicação de map_each.
terminate_with string; or None; default = None
Um argumento opcional a ser anexado depois de todos os outros argumentos. Este 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 se 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. Normalmente, 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 essa linha de comando concatenando diversos valores usando um separador. Os itens são processados lentamente durante a fase de execução.

O processamento é semelhante a add_all(), mas a lista de argumentos derivados de values é combinada em um único argumento como se fosse por join_with.join(...) e formatada usando o modelo de string format_joined fornecido. Ao contrário de add_all(), não há o 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, depois da filtragem, não houver strings para mesclar em um argumento e se omit_if_empty for verdadeiro (padrão), nenhum processamento será feito. Caso contrário, se não houver strings para mesclar, mas omit_if_empty for falso, a string mesclada será uma string vazia.

Parâmetros

Parâmetro Descrição
arg_name_or_values obrigatório
Se dois parâmetros de posição 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 (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 forem filtrados). Se apenas um parâmetro de posição for transmitido, ele será interpretado como values (veja abaixo).
values sequence; or depset; default = unbound
A lista, a tupla ou o depset cujos itens serão unidos.
join_with obrigatório
Uma string delimitadora usada para unir as strings obtidas da aplicação de map_each e format_each, da mesma maneira que string.join().
map_each callable; or None; default = None
O mesmo que para add_all.
format_each string; or None; default = None
O mesmo que para add_all.
format_joined string; or None; default = None
Um padrão de string de formato opcional aplicado à string unida. A string do formato precisa ter exatamente um marcador "%s".
omit_if_empty default = True
Se verdadeiro, se não houver strings para unir (seja porque values está vazio ou todos os itens são filtrados), todo o processamento será suprimido e a linha de comando não será alterada. Se for falso, mesmo se não houver 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 default = False
O mesmo que para add_all.
expand_directories default = True
O mesmo que add_all.
allow_closure default = False
O mesmo que para add_all.

set_param_file_format

Args Args.set_param_file_format(format)

Define o formato do arquivo de parâmetros, se houver.

Parâmetros

Parâmetro Descrição
format obrigatório
Deve ser um dos seguintes:
  • "multiline": cada item (nome ou argumento do argumento) é escrito na íntegra para o arquivo de parâmetro com um caractere de nova linha após ele.
  • "shell": o mesmo que "multilinha", mas os itens são entre aspas
  • "flag_per_line": o mesmo que "multiline", mas (1) somente sinalizadores (começando com "--") são gravados no arquivo de parâmetros e (2) os valores dos sinalizadores, se houver, são gravados na mesma linha com um separador "=". Esse é o formato esperado pela biblioteca de sinalizações do Abseil.

Se não for chamado, o formato padrão será "shell".

usar_arquivo_param

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

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

Para melhorar a eficiência, o Bazel pode optar por gravar o 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âmetros, transmita --materialize_param_files para seu build.

Parâmetros

Parâmetro Descrição
param_file_arg obrigatório
Uma string de formato com um único "%s". Se os argumentos forem derramados em um arquivo de parâmetros, eles serão substituídos por um argumento que consiste nessa sequência formatada com o caminho do arquivo de parâmetros.

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

use_always default = False
Indica se os argumentos sempre serão derramados em um arquivo de parâmetros. Se for falso, o Bazel vai decidir se os argumentos precisam ser derramados com base no seu sistema e no comprimento do argumento.