Esta página foi traduzida pela API Cloud Translation.

args

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 para todas as bibliotecas vinculadas. Recomendamos armazenar esses dados transitivos em depsets para que eles possam ser compartilhados por vários destinos. No entanto, se o autor da regra tivesse que converter esses recursos em listas de strings para construir uma linha de comando de ação, essa otimização de compartilhamento de memória seria invalidada.

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 as dependências que encapsulam até a fase de execução, quando chega a hora de calcular a linha de comando. Isso ajuda a adiar cópias caras 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 mantidos como estão.
Objetos File são transformados em seus valores File.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 para add(). Se eles forem transmitidos 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 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 explicado acima.

Cada um dos métodos add*() tem uma forma alternativa que aceita um parâmetro de posicionamento extra, uma string "arg name" (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 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: imagine 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],
  ...
)

adicionar

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

Anexa um argumento a essa linha de comando.

Parâmetros

Parâmetro	Descrição
`arg_name_or_value`	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 valor, sem qualquer 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á 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 em strings 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 essa linha de comando. Os itens são processados lentamente durante a fase de execução.

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

Cada item File do diretório é substituído por todos os Files 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 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 efetivamente o número de argumentos a serem anexados a esse ponto.
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 argumento, respectivamente, se forem fornecidos.

As strings vazias são argumentos válidos 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, ele será interpretado como o nome do argumento. O nome do argumento é adicionado antes de `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 quando `values` está vazio ou se todos os itens são filtrados. Se apenas um parâmetro posicional for transmitido, ele será interpretado como `values` (veja abaixo).
`values`	sequência; ou depset; o padrão é `unbound` A lista, a tupla ou o encerramento 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á passado somente 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 precisam ser produzidos para o item: No caso comum, em que cada item se transforma em uma string, a função precisa 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 delas. 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 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 `expand_directories=True` é definido. No entanto, isso não expandirá os diretórios contidos em outros valores, por exemplo, quando os itens forem 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 na 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. Ela pode não ser um fechamento de função aninhada por padrão. Aviso:as instruções `print()` executadas durante a chamada para `map_each` não vão produzir saídas visíveis.
`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 "%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`	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 falso, o nome do argumento e `terminate_with`, se fornecido, ainda serão anexados, independentemente de haver ou não outros argumentos.
`uniquify`	o padrão é `False` Se verdadeiro, os argumentos duplicados derivados de `values` são omitidos. Somente a primeira ocorrência de cada argumento será mantida. 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`	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 a ser anexado 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 quando `values` está vazio ou se todos os itens são filtrados.
`allow_closure`	O padrão é `False` Se verdadeiro, permite o uso de interdições em parâmetros de função, como `map_each`. Normalmente, isso não é necessário e arrisca manter grandes estruturas de dados na 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 usando 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 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, 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`	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 de `values` sem nenhum 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 seus itens estiverem filtrados). Se apenas um parâmetro posicional for transmitido, ele será interpretado como `values` (veja abaixo).
`values`	sequência; ou depset; o padrão é `unbound` A lista, a tupla ou o encerramento cujos itens serão unidos.
`join_with`	obrigatório Uma string delimitadora usada para unir as strings provenientes da aplicação de `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` Igual a `add_all`.
`format_joined`	string; ou `None`; o padrão é `None`. Um padrão de string de formato opcional aplicado à string mesclada. A string de formato precisa ter exatamente um marcador "%s".
`omit_if_empty`	o padrão é `True` Se verdadeiro, se não houver strings para unir (seja porque `values` está vazio ou todos os seus itens estão 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 unir, dois argumentos serão anexados: o nome do argumento seguido por uma string vazia (que é a junção lógica das strings zero).
`uniquify`	o padrão é `False` Igual a `add_all`.
`expand_directories`	o padrão é `True` Igual a `add_all`.
`allow_closure`	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âmetro, se um for usado.

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`format`	obrigatório Precisa ser um dos seguintes: "multiline": cada item (nome do argumento ou valor) é escrito literalmente no arquivo de parâmetro com um caractere de nova linha após ele. "shell": o mesmo que "multiline", mas os itens estão entre aspas simples. "flag_per_line": igual a "multiline", mas (1) somente os sinalizadores (começando com '--') são gravados no arquivo de parâmetro 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".

format

obrigatório
Precisa ser um dos seguintes:

"multiline": cada item (nome do argumento ou valor) é escrito literalmente no arquivo de parâmetro com um caractere de nova linha após ele.
"shell": o mesmo que "multiline", mas os itens estão entre aspas simples.
"flag_per_line": igual a "multiline", mas (1) somente os sinalizadores (começando com '--') são gravados no arquivo de parâmetro 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".

use_param_file

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

Distribui os argumentos para um arquivo de parâmetros, substituindo-os por um ponteiro para o arquivo de parâmetro. Use quando seus argumentos forem grandes demais para os limites de tamanho de comando do sistema.

O Bazel pode optar por ignorar a gravação do 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âmetro, transmita --materialize_param_files para seu build.

Parâmetros

Parâmetro Descrição

Parâmetro	Descrição
`param_file_arg`	obrigatório Uma string de formato com um único "%s". Se os argumentos forem espalhados para um arquivo params, eles serão substituídos por um argumento que consiste nessa string formatada com o caminho do arquivo params. 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`	o padrão é `False` Define se os argumentos devem ser sempre transmitidos 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.

param_file_arg

obrigatório
Uma string de formato com um único "%s". Se os argumentos forem espalhados para um arquivo params, eles serão substituídos por um argumento que consiste nessa string formatada com o caminho do arquivo params.

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 o padrão é False
Define se os argumentos devem ser sempre transmitidos 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.