ações

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6
Módulo que fornece funções para criar ações. Acesse este módulo usando ctx.actions.

Membros

args

Args actions.args()

Retorna um objeto Args que pode ser usado para criar linhas de comando com eficiência de memória.

declare_directory

File actions.declare_directory(filename, *, sibling=None)

Declara que a regra ou o aspecto cria um diretório com o nome especificado no pacote atual. Você precisa criar uma ação que gere o diretório. O conteúdo do diretório não pode ser acessado diretamente do Starlark, mas pode ser expandido em um comando de ação com Args.add_all(). Somente arquivos e diretórios regulares podem estar no conteúdo expandido de um declare_directory.

Parâmetros

Parâmetro Descrição
filename string; required
Se nenhum "sibling" for fornecido, o caminho do novo diretório será relativo ao pacote atual. Caso contrário, um nome base para um arquivo ("sibling" define um diretório).
sibling Arquivo ou None; o padrão é None
Um arquivo que está no mesmo diretório que o diretório recém-declarado. O arquivo precisa estar no pacote atual.

declare_file

File actions.declare_file(filename, *, sibling=None)

Declara que a regra ou o aspecto cria um arquivo com o nome de arquivo especificado. Se sibling não for especificado, o nome do arquivo será relativo ao diretório do pacote. Caso contrário, o arquivo estará no mesmo diretório que sibling. Não é possível criar arquivos fora do pacote atual.

Além de declarar um arquivo, você precisa criar uma ação que o emita. Para criar essa ação, é necessário transmitir o objeto File retornado à função de construção da ação.

Os arquivos de saída pré-declarados não precisam (e não podem) ser declarados usando essa função. Em vez disso, obtenha os objetos File de ctx.outputs. Veja um exemplo de uso.

Parâmetros

Parâmetro Descrição
filename string; required
Se nenhum "sibling" for fornecido, o caminho do novo arquivo será relativo ao pacote atual. Caso contrário, um nome base para um arquivo ("sibling" determina um diretório).
sibling Arquivo ou None. O padrão é None
. Um arquivo que está no mesmo diretório do arquivo recém-criado. O arquivo precisa estar no pacote atual. 

File actions.declare_symlink(filename, *, sibling=None)

Declara que a regra ou o aspecto cria um link simbólico com o nome especificado no pacote atual. Você precisa criar uma ação que gere esse link simbólico. O Bazel nunca vai desreferenciar esse link simbólico e o transferirá literalmente para sandboxes ou executores remotos. No momento, não há suporte para links simbólicos em artefatos de árvore.

Parâmetros

Parâmetro Descrição
filename string; required
Se nenhum "sibling" for fornecido, o caminho do novo link simbólico será relativo ao pacote atual. Caso contrário, um nome base para um arquivo ("sibling" define um diretório).
sibling Arquivo ou None. O padrão é None
. Um arquivo que fica no mesmo diretório do novo link simbólico declarado.

do_nothing

None actions.do_nothing(*, mnemonic, inputs=[])

Cria uma ação vazia que não executa um comando nem produz saída, mas é útil para inserir "ações extras".

Parâmetros

Parâmetro Descrição
mnemonic string; required
Uma descrição de uma palavra da ação, por exemplo, CppCompile ou GoLink.
inputs sequência de Files ou depset; o padrão é []
Lista dos arquivos de entrada da ação.

expand_template

None actions.expand_template(*, template, output, substitutions={}, is_executable=False, computed_substitutions=unbound)

Cria uma ação de expansão de modelo. Quando a ação é executada, ela gera um arquivo com base em um modelo. Partes do modelo serão substituídas usando o dicionário substitutions, na ordem em que as substituições forem especificadas. Sempre que uma chave do dicionário aparece no modelo (ou em um resultado de uma substituição anterior), ela é substituída pelo valor associado. Não há uma sintaxe especial para as chaves. Por exemplo, você pode usar chaves para evitar conflitos (por exemplo, {KEY}). Confira um exemplo de uso.

Parâmetros

Parâmetro Descrição
template Arquivo; required
O arquivo de modelo, que é um arquivo de texto codificado em UTF-8.
output Arquivo; required
O arquivo de saída, que é um arquivo de texto codificado em UTF-8.
substitutions dict; o padrão é {}
Substituições a serem feitas ao expandir o modelo.
is_executable bool; o padrão é False
Se o arquivo de saída deve ser executável.
computed_substitutions TemplateDict; o padrão é unbound
Substituições a serem feitas ao expandir o modelo.

map_directory

None actions.map_directory(*, input_directories, additional_inputs={}, output_directories, tools, additional_params={}, execution_requirements=None, exec_group=None, toolchain=None, use_default_shell_env=False, env=None, mnemonic=None, implementation)

Cria várias ações com base nos arquivos em um ou mais diretórios de entrada para gerar um ou mais diretórios de saída.

Parâmetros

Parâmetro Descrição
input_directories dict de Files; required
Um dicionário que mapeia strings para diretórios de entrada, conforme declarado por ctx.actions.declare_directory(). Somente diretórios são permitidos como valores aqui. Os valores especificam os diretórios que queremos expandir para acessar os arquivos na função de implementação. As chaves (strings) funcionam como identificadores para referenciar facilmente um diretório específico na função de implementação.
additional_inputs dict; o padrão é {}
Um dicionário de mapeamento de strings para entradas adicionais. Aqui, só são permitidos arquivos, FilesToRunProvider(s) e Depset(s). Os valores especificam outras entradas que queremos disponibilizar para ações criadas pela função de implementação. As chaves (strings) funcionam como identificadores para referenciar facilmente uma entrada específica na função de implementação.
output_directories dict de Files; required
Um dicionário que mapeia strings para diretórios de saída, conforme declarado por ctx.actions.declare_directory(). Os valores especificam os diretórios de saída que queremos gerar pelas ações criadas pela função de implementação. As chaves (strings) funcionam como identificadores para referenciar facilmente um diretório de saída específico na função de implementação.
tools dict; required
Um dicionário que mapeia strings para ferramentas. Aqui, só são permitidos arquivos, FilesToRunProvider(s) e Depset(s). Os valores especificam as ferramentas que queremos disponibilizar para ações criadas pela função de implementação. As chaves (strings) funcionam como identificadores para referenciar facilmente uma ferramenta específica na função de implementação.
additional_params dict; o padrão é {}
Um dicionário que mapeia strings para parâmetros adicionais. Aqui, só são permitidos valores de string, booleano e inteiro. Os valores especificam outros parâmetros que queremos disponibilizar para a função de implementação e que podem ser usados para influenciar o comportamento dela. As chaves (strings) funcionam como identificadores para referenciar facilmente um parâmetro específico na função de implementação.
execution_requirements dict ou None; o padrão é None
. Informações para agendar as ações criadas. Consulte tags para chaves úteis.
exec_group string ou None. O padrão é None
. Execute as ações criadas na plataforma de execução do grupo de execução especificado. Se nenhum, usa a plataforma de execução padrão do destino.
toolchain Rótulo; ou string; ou None; o padrão é None

Tipo de cadeia de ferramentas do executável ou das ferramentas usadas pelas ações criadas.

Se o executável e as ferramentas não vierem de uma cadeia de ferramentas, defina esse parâmetro como None.

Se o executável e as ferramentas vierem de uma cadeia de ferramentas, o tipo dela precisará ser definido para que as ações criadas sejam executadas na plataforma de execução correta.

A regra que cria essas ações precisa definir essa cadeia de ferramentas na função "rule()".

Quando os parâmetros toolchain e exec_group são definidos, o exec_group é usado. Um erro será gerado se o exec_group não especificar a mesma cadeia de ferramentas.
use_default_shell_env bool; o padrão é False
Indica se as ações criadas devem usar o ambiente de shell padrão, que consiste em algumas variáveis dependentes do SO e variáveis definidas por --action_env.

Se use_default_shell_env e env estiverem definidos como True, os valores definidos em env vão substituir o ambiente de shell padrão.

env dict ou None. O padrão é None
. Define o dicionário de variáveis de ambiente.

Se use_default_shell_env e env estiverem definidos como True, os valores definidos em env vão substituir o ambiente de shell padrão.

mnemonic string; ou None; o padrão é None
Uma descrição de uma palavra das ações criadas, por exemplo, CppCompile ou GoLink.
implementation function; required
Uma função Starlark chamada depois que os diretórios de entrada são criados para gerar ações que geram arquivos nos diretórios de saída especificados. Essa função recebe os seguintes argumentos:
  • template_ctx (posicional): um objeto template_ctx que pode ser usado para criar ações.
  • input_directories (somente palavra-chave): um dicionário que mapeia as chaves de string do argumento input_directories de actions.map_directory() para os objetos ExpandedDirectory correspondentes dos valores.
  • output_directories (somente palavra-chave): o valor do argumento output_directories de actions.map_directory(), um dicionário que mapeia strings para diretórios de saída.
  • additional_inputs (somente palavra-chave): o valor do argumento additional_inputs de actions.map_directory(), um dicionário que mapeia strings para arquivos de entrada.
  • tools (somente palavra-chave): o valor do argumento tools de actions.map_directory(); um dicionário que mapeia strings para ferramentas.
  • additional_params (somente palavra-chave): o valor do argumento additional_params de actions.map_directory(); um dicionário que mapeia strings para strings, booleanos ou números inteiros.
Essa função precisa ser de nível superior. Lambdas e funções aninhadas não são permitidos.

run

None actions.run(*, outputs, inputs=[], unused_inputs_list=None, executable, tools=unbound, arguments=[], mnemonic=None, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None, shadowed_action=None, resource_set=None, toolchain=unbound)

Cria uma ação que executa um executável. Veja um exemplo de uso.

Parâmetros

Parâmetro Descrição
outputs sequence de Files; required
Lista dos arquivos de saída da ação.
inputs sequência de Files ou depset; o padrão é []
Lista ou depset dos arquivos de entrada da ação.
unused_inputs_list File ou None; o padrão é None
. Arquivo que contém a lista de entradas não usadas pela ação.

O conteúdo desse arquivo (geralmente uma das saídas da ação) corresponde à lista de arquivos de entrada que não foram usados durante toda a execução da ação. Nenhuma mudança nesses arquivos pode afetar as saídas da ação.

executable File; ou string; ou FilesToRunProvider; required
O arquivo executável a ser chamado pela ação.
tools sequence ou depset; o padrão é unbound
Lista ou depset de todas as ferramentas necessárias para a ação. As ferramentas são entradas executáveis que podem ter seus próprios runfiles, que são disponibilizados automaticamente para a ação.

Quando uma lista é fornecida, ela pode ser uma coleção heterogênea de:

  • Files
  • FilesToRunProvider instâncias
  • depsets de Files
Os Files de ctx.executable e os FilesToRunProviders que estão diretamente na lista terão os runfiles adicionados automaticamente. Todas as ferramentas são adicionadas implicitamente como entradas.

arguments sequence; o padrão é []
Argumentos de linha de comando da ação. Precisa ser uma lista de strings ou objetos actions.args().
mnemonic string; ou None; o padrão é None
Uma descrição de uma palavra da ação, por exemplo, CppCompile ou GoLink.
progress_message string; ou None; o padrão é None
Mensagem de progresso a ser mostrada ao usuário durante a build. Por exemplo, "Compilando foo.cc para criar foo.o". A mensagem pode conter padrões %{label}, %{input} ou %{output}, que são substituídos pela string de marcador, pela primeira entrada ou pelo caminho da saída, respectivamente. Prefira usar padrões em vez de strings estáticas, porque os primeiros são mais eficientes.
use_default_shell_env bool; o padrão é False
Indica se a ação deve usar o ambiente de shell padrão, que consiste em algumas variáveis dependentes do SO e variáveis definidas via --action_env.

Se use_default_shell_env e env estiverem definidos como True, os valores definidos em env vão substituir o ambiente de shell padrão.

env dict ou None. O padrão é None
. Define o dicionário de variáveis de ambiente.

Se use_default_shell_env e env estiverem definidos como True, os valores definidos em env vão substituir o ambiente de shell padrão.

execution_requirements dict ou None. O padrão é None
. Informações para agendar a ação. Consulte tags para chaves úteis.
input_manifests sequence ou None. O padrão é None
. Argumento legado. Ignorado.
exec_group string ou None; o padrão é None
Executa a ação na plataforma de execução do grupo de execução especificado. Se nenhum, usa a plataforma de execução padrão do destino.
shadowed_action Ação; o padrão é None
Executa a ação usando as entradas e o ambiente da ação sombreada especificada adicionados à lista de entradas e ao ambiente da ação. O ambiente de ação pode substituir qualquer uma das variáveis de ambiente da ação sombreada. Se nenhum, usa apenas as entradas da ação e o ambiente especificado.
resource_set callable; or None; default is None
Uma função de callback que retorna um dicionário de conjunto de recursos, usado para estimar o uso de recursos no tempo de execução se essa ação for executada localmente.

A função aceita dois argumentos posicionais: uma string que representa um nome de SO (por exemplo, "osx") e um número inteiro que representa o número de entradas para a ação. O dicionário retornado pode conter as seguintes entradas, cada uma delas podendo ser um ponto flutuante ou um número inteiro:

  • "cpu": número de CPUs; padrão 1
  • "memory": em MB; padrão 250
  • "local_test": número de testes locais; padrão 1

Se esse parâmetro for definido como None , os valores padrão serão usados.

O callback precisa ser de nível superior (lambdas e funções aninhadas não são permitidos).

toolchain Rótulo, string ou None. O padrão é unbound
.

Tipo de cadeia de ferramentas do executável ou das ferramentas usadas nesta ação.

Se o executável e as ferramentas não vierem de uma cadeia de ferramentas, defina esse parâmetro como "None".

Se o executável e as ferramentas vierem de uma cadeia de ferramentas, o tipo dela precisará ser definido para que a ação seja executada na plataforma de execução correta.

A regra que cria essa ação precisa definir essa cadeia de ferramentas na função "rule()".

Quando os parâmetros "toolchain" e "exec_group" são definidos, o "exec_group" é usado. Um erro será gerado se o `exec_group` não especificar a mesma cadeia de ferramentas.

run_shell

None actions.run_shell(*, outputs, inputs=[], tools=unbound, arguments=[], mnemonic=None, command, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None, shadowed_action=None, resource_set=None, toolchain=unbound)

Cria uma ação que executa um comando de shell. Veja um exemplo de uso.

Parâmetros

Parâmetro Descrição
outputs sequence de Files; required
Lista dos arquivos de saída da ação.
inputs sequência de Files ou depset; o padrão é []
Lista ou depset dos arquivos de entrada da ação.
tools sequence de Files ou depset; o padrão é unbound
Lista ou depset de todas as ferramentas necessárias para a ação. As ferramentas são entradas executáveis que podem ter seus próprios runfiles, que são disponibilizados automaticamente para a ação.

Quando uma lista é fornecida, ela pode ser uma coleção heterogênea de:

  • Files
  • FilesToRunProvider instâncias
  • depsets de Files
Os Files de ctx.executable e os FilesToRunProviders que estão diretamente na lista terão os runfiles adicionados automaticamente. Todas as ferramentas são adicionadas implicitamente como entradas.

arguments sequence; o padrão é []
Argumentos de linha de comando da ação. Precisa ser uma lista de strings ou objetos actions.args().

O Bazel transmite os elementos nesse atributo como argumentos para o comando.O comando pode acessar esses argumentos usando substituições de variáveis de shell, como $1, $2 etc. Como os objetos Args são nivelados antes da indexação, se houver um objeto Args de tamanho desconhecido, todas as strings subsequentes estarão em índices imprevisíveis. Pode ser útil usar $@ (para extrair todos os argumentos) em conjunto com objetos Args de tamanho indeterminado.

Quando command é uma lista de strings, esse parâmetro não pode ser usado.

mnemonic string; ou None; o padrão é None
Uma descrição de uma palavra da ação, por exemplo, CppCompile ou GoLink.
command string ou sequência de strings; obrigatório
Comando do shell a ser executado. Pode ser uma string (preferencial) ou uma sequência de strings (descontinuado).

Se command for uma string, ela será executada como se fosse sh -c <command> "" <arguments>. Ou seja, os elementos em arguments serão disponibilizados para o comando como $1, $2 (ou %1, %2 se você estiver usando o lote do Windows) etc. Se arguments contiver objetos actions.args(), o conteúdo deles será anexado um por um à linha de comando. Assim, $i pode se referir a strings individuais em um objeto Args. Se um objeto Args de tamanho desconhecido for transmitido como parte de arguments, as strings estarão em índices desconhecidos. Nesse caso, a substituição de shell $@ (recuperar todos os argumentos) pode ser útil.

(Descontinuado) Se command for uma sequência de strings, o primeiro item será o executável a ser executado, e os itens restantes serão os argumentos dele. Se esse formato for usado, o parâmetro arguments não poderá ser fornecido. Este formulário foi descontinuado e será removido em breve. Ele é desativado com `--incompatible_run_shell_command_string`. Use essa flag para verificar se o código é compatível.

O Bazel usa o mesmo shell para executar o comando e as genrules.

progress_message string; ou None; o padrão é None
Mensagem de progresso a ser mostrada ao usuário durante a build. Por exemplo, "Compilando foo.cc para criar foo.o". A mensagem pode conter padrões %{label}, %{input} ou %{output}, que são substituídos pela string de marcador, pela primeira entrada ou pelo caminho da saída, respectivamente. Prefira usar padrões em vez de strings estáticas, porque os primeiros são mais eficientes.
use_default_shell_env bool; o padrão é False
Indica se a ação deve usar o ambiente de shell padrão, que consiste em algumas variáveis dependentes do SO e variáveis definidas via --action_env.

Se use_default_shell_env e env estiverem definidos como True, os valores definidos em env vão substituir o ambiente de shell padrão.

env dict ou None. O padrão é None
. Define o dicionário de variáveis de ambiente.

Se use_default_shell_env e env estiverem definidos como True, os valores definidos em env vão substituir o ambiente de shell padrão.

execution_requirements dict ou None. O padrão é None
. Informações para agendar a ação. Consulte tags para chaves úteis.
input_manifests sequence ou None. O padrão é None
. Argumento legado. Ignorado.
exec_group string ou None; o padrão é None
Executa a ação na plataforma de execução do grupo de execução especificado. Se nenhum, usa a plataforma de execução padrão do destino.
shadowed_action Action; o padrão é None
Executa a ação usando as entradas descobertas da ação sombreada fornecida adicionadas à lista de entradas da ação. Se não houver, use apenas as entradas da ação.
resource_set chamável ou None; o padrão é None
Uma função de callback para estimar o uso de recursos se executada localmente. Consulte ctx.actions.run().
toolchain Rótulo, string ou None. O padrão é unbound
.

Tipo de cadeia de ferramentas do executável ou das ferramentas usadas nesta ação.

Se o executável e as ferramentas não vierem de uma cadeia de ferramentas, defina esse parâmetro como "None".

Se o executável e as ferramentas vierem de uma cadeia de ferramentas, o tipo dela precisará ser definido para que a ação seja executada na plataforma de execução correta.

A regra que cria essa ação precisa definir essa cadeia de ferramentas na função "rule()".

Quando os parâmetros "toolchain" e "exec_group" são definidos, o "exec_group" é usado. Um erro será gerado se o `exec_group` não especificar a mesma cadeia de ferramentas.

 

None actions.symlink(*, output, target_file=None, target_path=None, is_executable=False, progress_message=None)

Cria uma ação que grava um link simbólico no sistema de arquivos.

Essa função precisa ser chamada com exatamente um dos valores target_file ou target_path especificados.

Ao usar target_file, declare output com declare_file() ou declare_directory() e corresponda ao tipo de target_file. Isso faz com que o link simbólico aponte para target_file. O Bazel invalida a saída dessa ação sempre que o destino do link simbólico ou o conteúdo dele muda.

Caso contrário, ao usar target_path, declare output com declare_symlink()). Nesse caso, o link simbólico aponta para target_path. O Bazel nunca resolve o link simbólico, e a saída dessa ação só é invalidada quando o conteúdo de texto do link simbólico (ou seja, o valor de readlink()) muda. Em particular, isso pode ser usado para criar um link simbólico pendente.

Parâmetros

Parâmetro Descrição
output Arquivo; required
A saída desta ação.
target_file File ou None; o padrão é None
. O arquivo a que o symlink de saída vai apontar.
target_path string ou None. O padrão é None
. O caminho exato para onde o link simbólico de saída vai apontar. Nenhuma normalização ou outro processamento é aplicado.
is_executable bool; o padrão é False
Só pode ser usado com target_file, não com target_path. Se for verdadeiro, quando a ação for executada, o caminho do target_file será verificado para confirmar se ele é executável, e um erro será informado se não for. Definir is_executable como "False" não significa que o destino não é executável, apenas que nenhuma verificação é feita.

Esse recurso não faz sentido para target_path porque symlinks pendentes podem não existir no momento da criação.
progress_message string ou None; o padrão é None
Mensagem de progresso a ser mostrada ao usuário durante a build.

template_dict

TemplateDict actions.template_dict()

Retorna um objeto TemplateDict para expansão de modelo com eficiência de memória.

gravação

None actions.write(output, content, is_executable=False, *, mnemonic=None)

Cria uma ação de gravação de arquivo. Quando a ação é executada, ela grava o conteúdo especificado em um arquivo. Usado para gerar arquivos com informações disponíveis na fase de análise. Se o arquivo for grande e tiver muito conteúdo estático, use expand_template.

Parâmetros

Parâmetro Descrição
output Arquivo; required
O arquivo de saída.
content string ou Args; required
o conteúdo do arquivo. Pode ser uma string ou um objeto actions.args().
is_executable bool; o padrão é False
Se o arquivo de saída deve ser executável.
mnemonic string; ou None; o padrão é None
Uma descrição de uma palavra da ação, por exemplo, CppCompile ou GoLink.