ações

7.3 · 7.2 · 7.1 · 7.0 · 6.5

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 determinado 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 pelo Starlark, mas pode ser expandido em um comando de ação com o Args.add_all(). Somente arquivos e diretórios normais podem estar no conteúdo expandido de um declare_directory.

Parâmetros

Parâmetro Descrição
filename required
Se nenhum "sibling" for fornecido, o caminho do novo diretório, relativo ao pacote atual. Caso contrário, um nome de base para um arquivo ("sibling" define um diretório).
sibling Arquivo ou None. O padrão é None.
Um arquivo que reside no mesmo diretório do 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 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 separada que emita o arquivo. A criação dessa ação vai exigir a transmissão do objeto File retornado para a função de construção da ação.

Os arquivos de saída predeclarados não precisam ser (e não podem ser) declarados usando essa função. Você pode buscar os objetos File deles em ctx.outputs. Confira um exemplo de uso.

Parâmetros

Parâmetro Descrição
filename required
Se nenhum "sibling" for fornecido, o caminho do novo arquivo, relativo ao pacote atual. Caso contrário, um nome de base para um arquivo ("sibling" determina um diretório).
sibling Arquivo; ou None; o padrão é None.
Um arquivo que reside 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 remover a referência a esse link simbólico e vai transferi-lo literalmente para sandboxes ou executores remotos. No momento, não há suporte para links simbólicos dentro de artefatos de árvore.

Parâmetros

Parâmetro Descrição
filename obrigatório
Se nenhum "sibling" for fornecido, o caminho do novo link simbólico em relação ao pacote atual. Caso contrário, um nome de base para um arquivo ("sibling" define um diretório).
sibling File; ou None; o padrão é None.
Um arquivo que reside no mesmo diretório do link simbólico recém-declarado.

do_nothing

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

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

Parâmetros

Parâmetro Descrição
mnemonic obrigatório
Uma descrição de uma palavra da ação, por exemplo, CppCompile ou GoLink.
inputs Sequência de arquivos 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 for executada, ela vai gerar 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 são especificadas. Sempre que uma chave do dicionário aparece no modelo (ou é o resultado de uma substituição anterior), ela é substituída pelo valor associado. Não há sintaxe especial para as chaves. Por exemplo, você pode usar colchetes para evitar conflitos (por exemplo, {KEY}). Confira um exemplo de uso.

Parâmetros

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

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. Confira um exemplo de uso.

Parâmetros

Parâmetro Descrição
outputs sequência de arquivos; obrigatório
Lista dos arquivos de saída da ação.
inputs Sequência de arquivos 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
O arquivo contém uma 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. Qualquer mudança nesses arquivos não pode afetar as saídas da ação.

executable Arquivo; ou string; ou FilesToRunProvider; obrigatório
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 com outros arquivos de execução disponibilizados automaticamente para a ação. Quando uma lista é fornecida, ela pode ser uma coleção heterogênea de arquivos, instâncias do FilesToRunProvider ou depsets de arquivos. Os arquivos de execução de arquivos que estão diretamente na lista e vêm de ctx.executable são adicionados automaticamente. Quando um depset é fornecido, ele precisa conter apenas arquivos. Em ambos os casos, os arquivos em depsets não são cruzados com ctx.executable para runfiles.
arguments sequência: 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 em uma palavra da ação, por exemplo, CppCompile ou GoLink.
progress_message string ou None; o padrão é None
Mensagem de progresso para mostrar ao usuário durante o build, por exemplo, "Compiling foo.cc to create foo.o". A mensagem pode conter padrões %{label}, %{input} ou %{output}, que são substituídos pelo rótulo, pela primeira entrada ou pelo caminho da saída, respectivamente. Use padrões em vez de strings estáticas, porque os primeiros são mais eficientes.
use_default_shell_env o padrão é False
Se a ação precisa usar o ambiente shell padrão, que consiste em algumas variáveis que dependem do SO, bem como variáveis definidas via --action_env.

Se use_default_shell_env e env forem definidos como True, os valores definidos em env vão substituir o ambiente de shell padrão se --incompatible_merge_fixed_and_default_shell_env estiver ativado (padrão). Se a flag não estiver ativada, env será ignorada.

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

Se use_default_shell_env e env forem definidos como True, os valores definidos em env vão substituir o ambiente de shell padrão se --incompatible_merge_fixed_and_default_shell_env estiver ativado (padrão). Se a flag não estiver ativada, env será ignorada.

execution_requirements dict ou None; o padrão é None
Informações para programar a ação. Consulte tags para conferir chaves úteis.
input_manifests sequência; ou None; o padrão é None;
(experimental) define os metadados dos arquivos de execução de entrada. Eles normalmente são gerados por resolve_command.
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 não houver nenhuma, será usada 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 adicionadas à lista de entradas e ao ambiente da ação. O ambiente da ação pode substituir qualquer uma das variáveis de ambiente da ação oculta. Se não houver, serão usadas apenas as entradas da ação e o ambiente fornecido.
resource_set chamável; ou None; o padrão é None
Uma função de callback que retorna um dicionário de conjunto de recursos, usado para estimar o uso de recursos no momento da execução, se essa ação for executada localmente.

A função aceita dois argumentos posicionais: uma string que representa o nome do 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 pode ser um float ou um int:

  • "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 ou se --experimental_action_resource_set for falso, os valores padrão serão usados.

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

toolchain Rótulo; ou string; ou None; o padrão é unbound

Tipo de cadeia de ferramentas do executável ou ferramentas usadas nesta ação. O parâmetro precisa ser definido para que a ação seja executada na plataforma de execução correta.

No momento, ele não faz nada, mas recomendamos que você o defina quando um conjunto de ferramentas for usado, porque ele será necessário nas próximas versões do Bazel.

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" estiverem definidos, o "exec_group" será usado. Um erro é gerado caso o "exec_group" não especifique o mesmo.

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 do shell. Confira um exemplo de uso.

Parâmetros

Parâmetro Descrição
outputs sequência de Files; obrigatório
Lista dos arquivos de saída da ação.
inputs Sequência de arquivos ou depset. O padrão é []
. Lista ou depset dos arquivos de entrada da ação.
tools sequência de arquivos ou depset; o padrão é unbound
Lista ou depset de todas as ferramentas necessárias para a ação. As ferramentas são entradas com outros arquivos de execução disponibilizados automaticamente para a ação. A lista pode conter instâncias de Files ou FilesToRunProvider.
arguments sequência; 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. Observe que, como os objetos Args são nivelados antes da indexação, se houver um objeto Args de tamanho desconhecido, todas as strings subsequentes terão índices imprevisíveis. Pode ser útil usar $@ (para extrair todos os argumentos) em conjunto com objetos Args de tamanho indeterminado.

No caso em que command é uma lista de strings, esse parâmetro pode não 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; comando
do shell necessário para execução. Pode ser uma string (preferencial) ou uma sequência de strings (descontinuado).

Se command for uma string, ela será executada como se fosse por sh -c <command> "" <arguments>. Ou seja, os elementos em arguments são disponibilizados para o comando como $1, $2 (ou %1, %2 se 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 vão estar 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 demais serão os argumentos. Se esse formulário for usado, o parâmetro arguments não poderá ser fornecido. Este formulário foi descontinuado e será removido em breve. Ela é desativada 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 que ele usa para genrules.

progress_message string ou None; o padrão é None
Mensagem de progresso para mostrar ao usuário durante o build, por exemplo, "Compiling foo.cc to create foo.o". A mensagem pode conter padrões %{label}, %{input} ou %{output}, que são substituídos pelo rótulo, 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 o padrão é False
Se a ação precisa usar o ambiente shell padrão, que consiste em algumas variáveis que dependem do SO, bem como variáveis definidas via --action_env.

Se use_default_shell_env e env forem definidos como True, os valores definidos em env vão substituir o ambiente de shell padrão se --incompatible_merge_fixed_and_default_shell_env estiver ativado (padrão). Se a sinalização não estiver ativada, env será ignorado.

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

Se use_default_shell_env e env forem definidos como True, os valores definidos em env vão substituir o ambiente de shell padrão se --incompatible_merge_fixed_and_default_shell_env estiver ativado (padrão). Se a flag não estiver ativada, env será ignorada.

execution_requirements dict ou None; o padrão é None
Informações para programar a ação. Consulte tags para conferir chaves úteis.
input_manifests sequence ou None; o padrão é None
(Experimental) define os metadados de runfiles de entrada, que geralmente são gerados por resolve_command.
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 não houver nenhuma, será usada a plataforma de execução padrão do destino.
shadowed_action Ação: o padrão é None
. Executa a ação usando as entradas descobertas da ação sombreada adicionadas à lista de entradas da ação. Se nenhuma, usa 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 for executado localmente. Consulte ctx.actions.run().
toolchain Rótulo ou string ou None. O padrão é unbound
.

Tipo de conjunto de ferramentas do executável ou das ferramentas usadas nesta ação. O parâmetro precisa ser definido para que a ação seja executada na plataforma de execução correta.

No momento, ele não faz nada, mas recomendamos que você o defina quando um conjunto de ferramentas for usado, porque ele será necessário nas próximas versões do Bazel.

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" estiverem definidos, o "exec_group" será usado. Um erro é gerado caso o "exec_group" não especifique o mesmo conjunto 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 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, quando você 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 é invalidada apenas 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 required
O resultado dessa ação.
target_file Arquivo ou None; o padrão é None
O arquivo para o qual o link simbólico de saída vai apontar.
target_path string ou None; o padrão é None
O caminho exato para o qual o link simbólico de saída vai apontar. Nenhuma normalização ou outro processamento é aplicado.
is_executable O padrão é False
Só pode ser usado com target_file, não target_path. Se verdadeiro, quando a ação for executada, o caminho do target_file será verificado para confirmar se ele é executável. Caso contrário, um erro será informado. 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 links simbólicos soltos podem não existir no momento da criação.
progress_message string ou None. O padrão é None
. Mensagem de progresso a ser exibida ao usuário durante a compilação.

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)

Cria uma ação de gravação de arquivo. Quando a ação é executada, ela grava o conteúdo em um arquivo. Ele é usado para gerar arquivos com as 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 obrigatório
O arquivo de saída.
content string ou Args; obrigatório
o conteúdo do arquivo. Pode ser uma string ou um objeto actions.args().
is_executable O padrão é False
Se o arquivo de saída precisa ser executável.