ações

Informar um problema Ver código-fonte

Módulo que fornece funções para criar ações. Acesse este módulo usando ctx.actions.

Participantes

args

Args actions.args()

Retorna um objeto Args que pode ser usado para criar linhas de comando com uso eficiente da memória.

diretório_declarar

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

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

Parâmetros

Parâmetro Descrição
filename required
Se nenhum "sibling" fornecido, o caminho do novo diretório, relativo ao pacote atual. Caso contrário, um nome base para um arquivo ('sibling' define um diretório).
sibling File; or None; default = None
Um arquivo que reside no mesmo diretório do diretório recém-declarado. O arquivo precisa estar no pacote atual.

declarar_arquivo

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

Declara que a regra ou o aspecto cria um arquivo com o nome de arquivo fornecido. 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.

Lembre-se de que, além de declarar um arquivo, você precisa criar separadamente uma ação que emita o arquivo. Para criar essa ação, será necessário transmitir o objeto File retornado para a função de construção da ação.

Os arquivos de saída pré-declarados não precisam ser (e não podem) ser declarados usando essa função. Você pode ver os objetos File de ctx.outputs. Veja um exemplo de uso.

Parâmetros

Parâmetro Descrição
filename required
Se nenhum "sibling" fornecido, o caminho do novo arquivo, em relação ao pacote atual. Caso contrário, um nome base para um arquivo ('sibling' determina um diretório).
sibling File; or None; default = 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)

Este parâmetro é experimental e pode ser alterado a qualquer momento. Ele pode ser desativado ao definir --noexperimental_allow_unresolved_symlinks

Declara que a regra ou o aspecto cria um link simbólico com o nome fornecido no pacote atual. É preciso criar uma ação que gere esse link simbólico. O Bazel nunca faz referência a esse link simbólico e o transfere exatamente para sandboxes ou executores remotos. No momento, links simbólicos dentro de artefatos de árvore não são compatíveis.

Parâmetros

Parâmetro Descrição
filename required
Se nenhum "sibling" fornecido, o caminho do novo symlink, em relação ao pacote atual. Caso contrário, um nome base para um arquivo ('sibling' define um diretório).
sibling File; or None; default = None
Um arquivo que reside no mesmo diretório do symlink recém-declarado.

nada

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

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

Parâmetros

Parâmetro Descrição
mnemonic required
É uma descrição de uma palavra da ação, por exemplo, CppCompile ou GoLink.
inputs sequence of Files; or depset; default = []
Lista dos arquivos de entrada da ação.

expandir_modelo

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 como resultado de uma substituição anterior), ela é substituída pelo valor associado. Não há sintaxe especial para as chaves. Você pode, por exemplo, usar chaves para evitar conflitos (por exemplo, {KEY}). Veja um exemplo de uso.

Parâmetros

Parâmetro Descrição
template required
O arquivo de modelo, que é um arquivo de texto codificado em UTF-8.
output required
O arquivo de saída, que é um arquivo de texto codificado em UTF-8.
substitutions default = {}
Substituições a serem feitas ao expandir o modelo.
is_executable default = False
Se o arquivo de saída precisa ser executável.
computed_substitutions TemplateDict; default = unbound
Experimental. Este parâmetro é experimental e pode ser alterado a qualquer momento. Não dependa dele. Ela pode ser ativada de forma experimental pela configuração de --+experimental_lazy_template_expansion
Experimental: 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. Veja um exemplo de uso.

Parâmetros

Parâmetro Descrição
outputs sequence of Files; obrigatório
Lista dos arquivos de saída da ação.
inputs sequence of Files; or depset; default = []
Lista ou dependência dos arquivos de entrada da ação.
unused_inputs_list File; or None; default = 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 alteração nesses arquivos pode afetar as saídas da ação.

executable File; or string; or FilesToRunProvider; obrigatório
O arquivo executável a ser chamado pela ação.
tools sequence; or depset; default = unbound
Lista ou dependência de todas as ferramentas necessárias para a ação. Ferramentas são entradas com arquivos de execução adicionais disponibilizados automaticamente para a ação. Quando uma lista é fornecida, ela pode ser uma coleção heterogênea de arquivos, instâncias de FilesToRunProvider ou depsets de arquivos. Arquivos que estão diretamente na lista e são provenientes de ctx.executable têm seus arquivos de execução adicionados automaticamente. Quando um depset é fornecido, ele precisa conter apenas arquivos. Em ambos os casos, os arquivos dentro de dependências não têm referência cruzada com ctx.executable para runfiles.
arguments sequence; default = []
Argumentos da linha de comando da ação. Precisa ser uma lista de strings ou objetos actions.args().
mnemonic string; or None; default = None
Uma descrição de uma palavra da ação, por exemplo, CppCompile ou GoLink.
progress_message string; or None; default = None
Mensagem de progresso exibida ao usuário durante a compilação, por exemplo, "Compilação de foo.cc para criar foo.o". A mensagem pode conter padrões %{label}, %{input} ou %{output}, que são substituídos por string de rótulo, primeira entrada ou caminho de saída, respectivamente. Use padrões em vez de strings estáticas porque elas são mais eficientes.
use_default_shell_env default = False
Se a ação deve ou não usar o ambiente de shell integrado.
env dict; or None; default = None
Define o dicionário de variáveis de ambiente.
execution_requirements dict; or None; default = None
Informações para programar a ação. Consulte tags para chaves úteis.
input_manifests sequence; or None; default = None
(Experimental) define os metadados dos arquivos de execução de entrada. Normalmente, eles são gerados por resolve_command.
exec_group string; or None; default = None
Executa a ação na plataforma de execução do grupo de executivos fornecido. Se não houver, usa a plataforma de execução padrão do destino.
shadowed_action Action; default = None
Executa a ação usando as entradas e o ambiente da ação oculta determinada adicionados à lista de entradas e ao ambiente da ação. O ambiente de ação pode substituir qualquer variável de ambiente da ação oculta. Se não houver, usa apenas as entradas e o ambiente especificado da ação.
resource_set callable; or None; default = 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 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 flutuante 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 (funções lambda e aninhadas não são permitidas).

toolchain Label; or string; or None; padrão = não vinculado

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

Ela é um ambiente autônomo no momento, mas recomendamos defini-la quando um conjunto de ferramentas é usado, porque ele será necessário nas versões futuras do Bazel.

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

Quando os parâmetros `toolchain` e `exec_group` são definidos, o "exec_group" é usado. Um erro será 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 de shell. Veja um exemplo de uso.

Parâmetros

Parâmetro Descrição
outputs sequence of Files; obrigatório
Lista dos arquivos de saída da ação.
inputs sequence of Files; or depset; default = []
Lista ou dependência dos arquivos de entrada da ação.
tools sequence of Files; or depset; default = unbound
Lista ou dependência de todas as ferramentas necessárias para a ação. Ferramentas são entradas com arquivos de execução adicionais disponibilizados automaticamente para a ação. A lista pode conter instâncias de Files ou FilesToRunProvider.
arguments sequence; default = []
Argumentos da 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 do shell, como $1, $2 etc. Como os objetos Args são achatados 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 recuperar todos os argumentos) em conjunto com objetos Args de tamanho indeterminado.

Se command for uma lista de strings, esse parâmetro não poderá ser usado.

mnemonic string; or None; default = None
Uma descrição de uma palavra da ação, por exemplo, CppCompile ou GoLink.
command string; or sequence of strings; obrigatório
comando do shell a ser executado. Pode ser uma string (de preferência) ou uma sequência de strings (obsoleta).

Se command for uma string, ela será executada como se fosse sh -c <command> "" <arguments>, ou seja, os elementos em arguments forem disponibilizados para o comando como $1, $2 (ou %1, %2 se você estiver usando o lote do Windows) etc. Se arguments contiver qualquer objeto actions.args(), o conteúdo será anexado um a um à linha de comando para que $i possa 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 do shell $@ (recuperar todos os argumentos) pode ser útil.

(Obsoleto) 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. Se este formulário for usado, o parâmetro arguments não poderá ser fornecido. Este formulário está obsoleto e será removido em breve. Ela está desativada com `--compatible_run_shell_command_string`. Use esta sinalização para verificar se seu código é compatível.

O Bazel usa o mesmo shell para executar o comando das regras gerais.

progress_message string; or None; default = None
Mensagem de progresso exibida ao usuário durante a compilação, por exemplo, "Compilação de foo.cc para criar foo.o". A mensagem pode conter padrões %{label}, %{input} ou %{output}, que são substituídos por string de rótulo, primeira entrada ou caminho de saída, respectivamente. Use padrões em vez de strings estáticas porque elas são mais eficientes.
use_default_shell_env default = False
Se a ação deve ou não usar o ambiente de shell integrado.
env dict; or None; default = None
Define o dicionário de variáveis de ambiente.
execution_requirements dict; or None; default = None
Informações para programar a ação. Consulte tags para chaves úteis.
input_manifests sequence; or None; default = None
(Experimental) define os metadados dos arquivos de execução de entrada. Normalmente, eles são gerados por resolve_command.
exec_group string; or None; default = None
Executa a ação na plataforma de execução do grupo de executivos fornecido. Se não houver, usa a plataforma de execução padrão do destino.
shadowed_action Action; default = None
Executa a ação usando as entradas descobertas da ação oculta determinada que foram adicionadas à lista de entradas da ação. Se não houver, usa apenas as entradas da ação.
resource_set callable; or None; default = None
Uma função de callback para estimar o uso de recursos se executada localmente. Consulte ctx.actions.run().
toolchain Label; or string; or None; padrão = não vinculado

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

Ela é um ambiente autônomo no momento, mas recomendamos defini-la quando um conjunto de ferramentas é usado, porque ele será necessário nas versões futuras do Bazel.

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

Quando os parâmetros `toolchain` e `exec_group` são definidos, o "exec_group" é usado. Um erro será gerado caso "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.

Esta função precisa ser chamada com exatamente uma das target_file ou target_path especificadas.

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 é alterado.

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 é invalidada apenas quando o conteúdo de texto do link simbólico (ou seja, o valor de readlink()) é alterado. Em particular, isso pode ser usado para criar um link simbólico suspenso.

Parâmetros

Parâmetro Descrição
output required
A saída dessa ação.
target_file File; or None; default = None
O arquivo a que o symlink de saída apontará.
target_path string; or None; default = None
O caminho exato para o qual o symlink de saída apontará. Nenhuma normalização ou outro processamento é aplicado.
is_executable default = False
Pode ser usado apenas com target_file, não target_path. Se verdadeiro, quando a ação for executada, o caminho do target_file será verificado para confirmar que é executável, e um erro será informado se não for. Definir is_executable como falso não significa que o destino não é executável, apenas que nenhuma verificação foi feita.

Esse recurso não faz sentido para target_path, porque os links simbólicos podem não existir no tempo de compilação.
progress_message string; or None; default = None
Mensagem de progresso a ser exibida para o usuário durante a build.

modelo_dict

TemplateDict actions.template_dict()

Experimental. Esta API é experimental e pode ser alterada a qualquer momento. Não dependa dele. Ele pode ser ativado em uma experiência experimental, definindo --+experimental_lazy_template_expansion
Experimental: retorna um objeto TemplateDict para expansão de modelo com eficiência de memória.

write

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 fornecido 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, considere usar expand_template.

Parâmetros

Parâmetro Descrição
output required
O arquivo de saída.
content string; or Args; obrigatório
o conteúdo do arquivo. Pode ser uma string ou um objeto actions.args().
is_executable default = False
Se o arquivo de saída precisa ser executável.