Definições comuns

Informar um problema Conferir origem Noite · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

Esta seção define diversos termos e conceitos comuns a muitas funções ou regras de build.

Índice

Tokenização do shell Bourne

Certos atributos de string de algumas regras são divididos em vários palavras de acordo com as regras de tokenização do shell Bourne: espaços sem aspas delimitam palavras separadas, e caracteres simples e caracteres de aspas duplas e barras invertidas são usados para evitar a tokenização.

Os atributos sujeitos a essa tokenização são explicitamente indicado como tal nas suas definições neste documento.

Atributos sujeitos a "Marca" expansão variável e shell Bourne a tokenização costuma ser usada para passar opções arbitrárias compiladores e outras ferramentas. Exemplos desses atributos são cc_library.copts e java_library.javacopts. Juntas, essas substituições permitem que uma variável de string seja expandida para uma lista de palavras de opção específica da configuração.

Expansão de rótulos

Alguns atributos de string de poucas regras estão sujeitos a rótulos, expansão: se essas strings contiverem um rótulo válido como um substring, como //mypkg:target, e esse rótulo é uma declarado como pré-requisito da regra atual, ele é expandido na nome do caminho do arquivo representado target //mypkg:target:

Exemplos de atributos incluem genrule.cmd e cc_binary.linkopts. Os detalhes podem variar significativamente cada caso, sobre problemas como: se os rótulos relativos estão expandido; como os marcadores que se expandem para vários arquivos são tratados etc. Consulte a documentação do atributo de regra para especificidades.

Atributos típicos definidos pela maioria das regras de build

Esta seção descreve os atributos definidos por muitas regras de build, mas não todos.

Atributo Descrição
data

Lista de rótulos o padrão é []

Arquivos necessários para essa regra no momento da execução. Pode listar destinos de arquivos ou regras. Geral permite qualquer destino.

As saídas padrão e os runfiles de destinos no atributo data precisam aparecer na área *.runfiles de qualquer executável que seja saída por ou tenha uma dependência de execução nesse destino. Isso pode incluir dados ou binários usados quando o destino srcs são executadas. Consulte a dependências de dados para mais informações sobre como depender e usar arquivos de dados.

As novas regras precisam definir um atributo data se processarem entradas que podem usar outras entradas no ambiente de execução. Regras funções de implementação também deve preencher o runfiles das saídas e arquivos de execução de qualquer atributo data além de arquivos de execução de qualquer atributo de dependência que forneça dependências de código-fonte ou ambiente de execução.

deps

Lista de rótulos o padrão é []

Dependências deste destino. Em geral, deve listar apenas destinos de regras. (Embora algumas regras permitem que os arquivos sejam listados diretamente em deps, este deve ser evitado sempre que possível.)

As regras específicas de idioma geralmente limitam os destinos listados a aqueles com provedores específicos.

a semântica precisa do que significa um alvo depender de outro usando deps são específicos ao tipo de regra e às regras mais detalhes. Para regras que processam código-fonte, deps geralmente especifica as dependências de código usadas pelo código em srcs.

Na maioria das vezes, uma dependência deps é usada para permitir que um módulo use símbolos definidos em outro módulo escrito na mesma linguagem de programação e compilado separadamente. As dependências entre linguagens também são permitidas em vários casos: por exemplo, um destino java_library pode depender do código C++. em um destino cc_library, listando o último no deps. Veja a definição de dependencies para mais informações.

licenses

Lista de strings nonconfigurable; o padrão é ["none"]

Uma lista de strings do tipo de licença a serem usadas para esse destino específico. Isso faz parte de uma API de licenciamento descontinuada que o Bazel não usa mais. O que não fazer use isso.

srcs

Lista de rótulos; o padrão é []

São os arquivos processados ou incluídos por esta regra. Geralmente, lista os arquivos diretamente, pode listar destinos de regras (como filegroup ou genrule) para incluem as saídas padrão.

As regras específicas de um idioma geralmente exigem que os arquivos listados tenham determinadas extensões de arquivo.

Atributos comuns a todas as regras de build

Esta seção descreve os atributos que são implicitamente adicionados a todos os builds regras de firewall.

Atributo Descrição
compatible_with

Lista de rótulos nonconfigurable; o padrão é []

A lista de ambientes para os quais esse destino pode ser criado, além dos ambientes com suporte padrão.

Isso faz parte do sistema de restrições do Bazel, que permite aos usuários declarar quais podem e não podem depender uns dos outros. Por exemplo, implantações externas os binários não devem depender de bibliotecas com código secreto da empresa. Consulte ConstraintSemantics para mais detalhes.

deprecation

String; nonconfigurable; o padrão é None

Uma mensagem de aviso explicativa associada a esse destino. Normalmente, isso é usado para notificar os usuários de que um destino ficou obsoleto, foi substituído por outra regra, é privado para um pacote ou é considerado prejudicial por algum motivo. É uma boa ideia incluir alguma referência (como uma página da Web, um número de bug ou exemplo de CLs de migração) para para que você possa descobrir facilmente quais alterações são necessárias para evitar a mensagem. Se houver um novo destino que possa ser usado como substituição, é recomendado migrar todos os usuários do destino antigo.

Esse atributo não afeta a forma como as coisas são construídas, pode afetar a saída de diagnóstico de uma ferramenta de build. A ferramenta de build emite um aviso quando uma regra com um atributo deprecation for dependem de um alvo em outro pacote.

As dependências dentro do pacote estão isentas desse aviso. Assim, Por exemplo, criar os testes de uma regra descontinuada não encontrar um aviso.

Se um destino descontinuado depender de outro destino descontinuado, nenhuma mensagem de aviso será emitida.

Depois que as pessoas pararem de usá-lo, o alvo poderá ser removido.

distribs

Lista de strings nonconfigurable; o padrão é []

Uma lista de strings do método de distribuição a serem usadas para esse destino específico. Isso faz parte de uma API de licenciamento descontinuada que o Bazel não usa mais. O que não fazer use isso.

exec_compatible_with

Lista de rótulos nonconfigurable; o padrão é []

Uma lista de constraint_values que precisam estar presentes na plataforma de execução para o destino. Isso está em além das restrições já definidas pelo tipo de regra. As restrições são usadas para restringir a lista de plataformas de execução disponíveis. Para mais detalhes, consulte a descrição resolução do conjunto de ferramentas.

exec_properties

Dicionário de strings o padrão é {}

Um dicionário de strings que será adicionado ao exec_properties de uma plataforma selecionada para esse destino. Consulte o exec_properties da regra de platform.

Se uma chave estiver presente nas propriedades no nível da plataforma e no nível do destino, o valor será retirado do destino.

features

Lista de strings de feature: o padrão é []

Um recurso é uma tag de string que pode ser ativada ou desativada em um destino. O significado de um recurso depende da própria regra.

Esse atributo features é combinado com o atributo features no nível do pacote. Por exemplo, se os atributos ["a", "b"] estão ativados no nível do pacote, e o objeto O atributo features contém ["-a", "c"], os recursos ativados para o regra será "b" e "c". Confira um exemplo.

restricted_to

Lista de rótulos nonconfigurable; o padrão é []

A lista de ambientes para os quais o destino pode ser criado, em vez de ambientes com suporte padrão.

Isso faz parte do sistema de restrições do Bazel. Consulte compatible_with para mais detalhes.

tags

Lista de strings nonconfigurable; o padrão é []

As tags podem ser usadas em qualquer regra. Tags no teste e As regras test_suite são úteis para categorizar os testes. Tags em destinos que não são de teste são usadas para controlar a execução no sandbox de genrules e Starlark ações humanas e para análise feita por humanos e/ou por ferramentas externas.

O Bazel modifica o comportamento do código de sandbox se encontrar o seguinte: palavras-chave no atributo tags de qualquer teste ou genrule destino, ou as chaves de execution_requirements para qualquer Starlark à ação.

  • A palavra-chave no-sandbox faz com que a ação ou o teste nunca seja colocado em sandbox. Ela ainda pode ser armazenada em cache ou executada remotamente. Use no-cache ou no-remote para impedir que isso aconteça.
  • no-cache palavra-chave resulta na ação ou teste nunca sendo em cache (remotamente ou localmente)
  • no-remote-cache palavra-chave resulta na ação ou teste nunca sendo armazenados em cache remotamente, mas que podem ser armazenados localmente ou executados remotamente. Observação: para esta tag, o Disk-cache é considerado um cache local, enquanto os caches HTTP e gRPC são considerados remotos. Se uma combinação de cache de disco local e cache remoto for usada (cache combinado), ele é tratado como um cache remoto e totalmente desativado, a menos que --incompatible_remote_results_ignore_disk é definido e, nesse caso, os componentes locais serão usados.
  • A palavra-chave no-remote-exec faz com que a ação ou o teste nunca sejam executados remotamente, mas podem ser armazenados em cache remotamente.
  • A palavra-chave no-remote impede que a ação ou o teste seja executado remotamente ou armazenado em cache remotamente. Isso equivale a usar no-remote-cache e no-remote-exec.
  • A palavra-chave no-remote-cache-upload desativa o upload de parte do armazenamento em cache remoto de um spawn. não desativa a execução remota.
  • A palavra-chave local impede que a ação ou o teste seja armazenada em cache remotamente, executada remotamente ou executada no sandbox. Para regras gerais e testes, a marcação da regra com local = True tem o mesmo efeito.
  • A palavra-chave requires-network permite acesso ao de dentro da sandbox. Esta tag só tem efeito se estiver no sandbox está ativado.
  • A palavra-chave block-network bloqueia o acesso ao de dentro da sandbox. Nesse caso, apenas as comunicações com localhost é permitido. Essa tag só tem efeito se o sandbox estiver ativado.
  • requires-fakeroot executa o teste ou a ação como UID e gid 0 (ou seja, a raiz usuário). Isso só é compatível com Linux. Essa tag tem prioridade Opção de linha de comando --sandbox_fake_username.

As tags em testes geralmente são usadas para anotar a função de um teste na sua o processo de depuração e lançamento. Normalmente, as tags são mais úteis para C++ e Python testes, que não têm a capacidade de anotação de tempo de execução. O uso de tags e tamanhos oferece flexibilidade na montagem de conjuntos de testes baseados na base de código e a política de check-in.

O Bazel modifica o comportamento de execução do teste se encontrar as seguintes palavras-chave no atributo tags da regra de teste:

  • exclusive forçará a execução do teste no "exclusivo" , garantindo que nenhum outro teste esteja sendo executado no ao mesmo tempo. Esses testes serão executados em série após todo o build atividade e testes não exclusivos foram concluídos. A execução remota é desativado para esses testes porque o Bazel não tem controle sobre o que é em execução em uma máquina remota.
  • exclusive-if-local forçará a execução do teste no "exclusivo" se ele for executado localmente, mas executará o teste em paralelo caso seja a execução remota.
  • A palavra-chave manual excluirá o destino da expansão de caracteres curinga de padrão de destino (..., :*, :all etc.) e regras test_suite que não listam o teste explicitamente ao calcular o conjunto de destinos de nível superior para criação/execução para os comandos build, test e coverage. Ele não afetar o caractere curinga de destino ou a expansão do conjunto de testes em outros contextos, incluindo o query. manual não implica que um destino não seja criado/executado automaticamente por sistemas de build/teste contínuos. Por exemplo, pode ser desejável excluir um destino de bazel test ... porque exige configurações Flags do Bazel, mas ainda incluídas em testes contínuos ou de pré-envio configurados corretamente é executado.
  • external palavra-chave forçará o teste a ser incondicionalmente executado (independentemente de --cache_test_results ).
. Consulte Convenções de tags na Enciclopédia de teste para mais convenções sobre tags anexadas a destinos de teste.
target_compatible_with

Lista de rótulos o padrão é []

Uma lista de constraint_values que devem estar presentes na plataforma de destino para que o destino seja considerado compatíveis. Isso é um complemento às restrições já definidas pelo tipo de regra. Se a plataforma de destino não atender a todas as restrições listadas, o destino é considerado incompatível. Destinos incompatíveis são pulada para criação e teste quando o padrão de destino é expandido (por exemplo, //..., :all). Quando explicitamente especificado no linha de comando, destinos incompatíveis fazem com que o Bazel imprima um erro e cause uma falha no build ou teste.

Os destinos que dependem transitivamente de destinos incompatíveis são eles mesmos considerados incompatíveis. Eles também são pulados na criação e nos testes.

Uma lista vazia (que é o padrão) significa que o destino é compatível com todas as plataformas.

Todas as regras, exceto as regras do Workspace, são compatíveis com esse atributo. Para algumas regras, esse atributo não tem efeito. Por exemplo, especificar target_compatible_with para um cc_toolchain não é útil.

Consulte a página Plataformas para mais informações sobre a omissão de destino incompatível.

testonly

Booleano; nonconfigurable; o padrão é False exceto para destinos dos conjuntos de testes

Se for True, somente destinos somente para teste (como testes) poderão depender dele.

Da mesma forma, uma regra que não é testonly não pode depender de nenhuma regra que seja testonly.

Testes (*_test regras) e pacotes de teste (regras test_suite) são testonly por padrão.

Esse atributo significa que o destino não deve ser em binários lançados para produção.

Como testonly é aplicado no tempo de build, não no ambiente de execução, e se propaga viralmente pela árvore de dependências, ela deve ser aplicada criteriosamente. Para exemplo, stubs e falsificações que são úteis para testes de unidade também podem ser úteis para testes de integração envolvendo os mesmos binários que serão lançados para produção portanto, provavelmente não deve ser marcado como testonly. Por outro lado, regras que é perigoso até mesmo vincular, talvez porque eles incondicionalmente substituem o comportamento normal, precisam ser marcadas como somente teste.

toolchains

Lista de rótulos nonconfigurable; o padrão é []

O conjunto de destinos cujas Make variables esse destino está. tem permissão de acesso. Essas metas são instâncias de regras que fornecem TemplateVariableInfo ou destinos especiais para tipos de conjunto de ferramentas criados no Bazel. Eles incluem:

  • @bazel_tools//tools/cpp:current_cc_toolchain
  • @bazel_tools//tools/jdk:current_java_runtime

Observe que isso é diferente do conceito de resolução do conjunto de ferramentas usado por implementações de regras para configuração dependente da plataforma. Não é possível usar para determinar quais cc_toolchain ou java_toolchain específicas destino usará.

visibility

Lista de rótulos nonconfigurable; o padrão é default_visibility de package, se especificado, ou "//visibility:private" caso contrário

O atributo visibility em um destino controla se ele pode ser usado em outros pacotes. Consulte a documentação visibilidade.

Atributos comuns a todas as regras de teste (*_test)

Nesta seção, descrevemos os atributos comuns a todas as regras de teste.

Atributo Descrição
args

Lista de strings sujeito a $(location) e Substituição "Make variables", e Tokenização de shell Bourne o padrão é []

Argumentos de linha de comando que o Bazel transmite para o destino quando é executado com bazel test.

Esses argumentos são transmitidos antes de qualquer valor --test_arg especificado na linha de comando bazel test.

env

Dicionário de strings valores estão sujeitos a $(location) e Substituição "Make variables". o padrão é []

Especifica as variáveis de ambiente adicionais a serem definidas quando o teste é executado pelo bazel test:

Esse atributo só se aplica a regras nativas, como cc_test, py_test e sh_test. Isso não se aplica a Regras de teste definidas pelo Starlark. Para suas próprias regras do Starlark, adicione um "env" e usá-lo para preencher um TestEnvironment Provedor.

env_inherit

Lista de strings o padrão é []

Especifica variáveis de ambiente adicionais para herdar do ambiente externo quando o teste é executado por bazel test.

Esse atributo só se aplica a regras nativas, como cc_test, py_test, e sh_test. Isso não se aplica às regras de teste definidas pelo Starlark.

size

String "enormous", "large", "medium" ou "small"; não configurável; o padrão é "medium"

Especifica o "peso" de um destino de teste: por quanto tempo/recursos ele precisa para ser executado.

Os testes de unidade são considerados "pequenos", os testes de integração são "médios" e os testes completos são "grandes". ou "enorme". O Bazel usa o tamanho para determinar um tempo limite padrão, que pode ser substituído usando o timeout. O tempo limite é para todos os testes no destino BUILD, não para cada para teste individual. Quando o teste é executado localmente, o size também é usado para fins de programação: o Bazel tenta respeitar --local_{ram,cpu}_resources e não sobrecarregar a máquina local com a execução de vários testes pesados ao mesmo tempo.

Os tamanhos dos testes correspondem aos seguintes tempos limite padrão e recursos locais de pico presumidos de uso:

Tamanho RAM (em MB) CPU (em núcleos de CPU) Tempo limite padrão
pequeno 20 1 curto (1 minuto)
médio 100 1 moderada (5 minutos)
grande 300 1 longo (15 minutos)
enorme 800 1 eterno (60 minutos)

A variável de ambiente TEST_SIZE será definida como o valor desse atributo ao gerar o teste.

timeout

String "short", "moderate", "long" ou "eternal"; não configurável; o padrão é derivado do atributo size do teste

Tempo de execução esperado do teste antes do retorno.

Enquanto o atributo de tamanho de um teste controla a estimativa de recursos, o tempo limite pode ser definido de forma independente. Se não for especificado explicitamente, o tempo limite será baseado no tamanho do teste. O teste tempo limite pode ser substituído pela sinalização --test_timeout, por exemplo: para que funcionam sob certas condições lentas. Testar valores de tempo limite correspondem aos seguintes períodos:

Valor de tempo limite Período
short 1 minuto
moderada 5 minutos
long 15 minutos
eterno 60 minutos

Para horas diferentes dos acima, o tempo limite do teste pode ser substituído pelo valor-chave Flag --test_timeout do Bazel, por exemplo para execução manual que são consideradas lentas. Os valores --test_timeout em segundos. Por exemplo, --test_timeout=120 define o tempo limite do teste como dois minutos.

A variável de ambiente TEST_TIMEOUT será definida como o tempo limite do teste (em segundos) ao gerar o teste.

flaky

Booleano; nonconfigurable; o padrão é False

Marca o teste como instável.

Se definido, executa o teste até três vezes, marcando-o como falhado apenas se ele falha todas as vezes. Por padrão, esse atributo é definido como falso, e o teste é executada apenas uma vez. O uso deste atributo geralmente não é recomendado. os testes devem passar de maneira confiável quando as declarações forem mantidas.

shard_count

Número inteiro não negativo menor ou igual a 50 o padrão é -1

Especifica o número de fragmentos paralelos usar para executar o teste.

Se definido, esse valor substituirá qualquer heurística usada para determinar o número de os fragmentos paralelos com os quais executar o teste. Para alguns testes esse parâmetro pode ser necessário para ativar a fragmentação em primeiro lugar. Consulte também --test_sharding_strategy.

Se o sharding de teste estiver ativado, a variável de ambiente TEST_TOTAL_SHARDS será definida como esse valor ao gerar o teste.

A fragmentação exige que o executor de testes ofereça suporte ao protocolo de fragmentação de testes. Caso contrário, provavelmente ele vai executar todos os testes em todos os fragmentos, o que não é o que você quer.

Consulte Fragmentação de testes na Enciclopédia de teste para obter detalhes sobre fragmentação.

local

Booleano; nonconfigurable; o padrão é False

Força o teste a ser executado localmente, sem sandbox.

Definir esse valor como "True" equivale a fornecer "local" como uma tag (tags=["local"]).

Atributos comuns a todas as regras binárias (*_binário)

Esta seção descreve os atributos comuns a todas as regras binárias.

Atributo Descrição
args

Lista de strings sujeito a $(location) e Substituição "Make variables", e Tokenização de shell Bourne não configurável o padrão é []

Argumentos de linha de comando que o Bazel passa para o destino quando é executado. seja pelo comando run ou como teste. Esses argumentos são transmitidos antes dos especificados na bazel run ou linha de comando bazel test.

OBSERVAÇÃO: os argumentos não são passados quando você executa o comando fora do Bazel (por exemplo, executando manualmente o binário bazel-bin/).

env

Dicionário de strings valores estão sujeitos a $(location) e Substituição "Make variables". o padrão é {}

Especifica as variáveis de ambiente adicionais a serem definidas quando o destino for executado por bazel run.

Esse atributo só se aplica a regras nativas, como cc_binary, py_binary, e sh_binary. Ele não se aplica a regras executáveis definidas pelo Starlark.

OBSERVAÇÃO: as variáveis de ambiente não são definidas quando você executa o destino fora do Bazel (por exemplo, executando manualmente o binário bazel-bin/).

output_licenses

Lista de strings o padrão é []

As licenças dos arquivos de saída que esse binário gera. Isso faz parte de uma API de licenciamento descontinuada que o Bazel não usa mais. O que não fazer use isso.

Atributos configuráveis

A maioria dos atributos é "configurável", o que significa que os valores deles podem mudar quando o destino é criado de maneiras diferentes. Especificamente, atributos configuráveis podem variar de acordo com as flags passadas para a linha de comando do Bazel ou qual dependência downstream está solicitando o destino. Isso pode ser usado para exemplo, para personalizar o destino para várias plataformas ou modos de compilação.

O exemplo a seguir declara origens diferentes para cada destino arquitetônicas. Executando bazel build :multiplatform_lib --cpu x86 vai criar o destino usando x86_impl.cc, substituindo --cpu arm fará com que ele use arm_impl.cc.

cc_library(
    name = "multiplatform_lib",
    srcs = select({
        ":x86_mode": ["x86_impl.cc"],
        ":arm_mode": ["arm_impl.cc"]
    })
)
config_setting(
    name = "x86_mode",
    values = { "cpu": "x86" }
)
config_setting(
    name = "arm_mode",
    values = { "cpu": "arm" }
)

A função select() escolhe entre diferentes valores alternativos para um atributo configurável com base em que config_setting ou constraint_value que a configuração do destino satisfaz.

O Bazel avalia os atributos configuráveis após processar macros e antes de processar regras (tecnicamente, entre as fases de carregamento e análise). Qualquer processamento anterior à avaliação de select() não sabe qual ramificação escolhida pelo select(). Macros, por exemplo, não podem mudar o comportamento com base na ramificação escolhida, e bazel query pode só faz suposições conservadoras sobre as dependências configuráveis de um destino. Consulte estas perguntas frequentes para saber mais sobre como usar o select() com regras e macros.

Atributos marcados como nonconfigurable na documentação não podem usar esse recurso. Em geral, um atributo não é configurável porque o Bazel internamente precisa saber seu valor antes de determinar como resolver um select():

Consulte Atributos de build configuráveis para uma visão geral detalhada.

Destinos de saída implícitos

As saídas implícitas em C++ foram descontinuadas. Evite usá-la em outros idiomas sempre que possível. Ainda não temos um caminho de descontinuação mas, no futuro, elas também serão descontinuadas.

Quando você define uma regra de build em um arquivo BUILD, você é explicitamente declarar um novo destino de regra nomeado em um pacote. Muitas regras de build também implicam implicitamente um ou mais arquivos de saída com conteúdos e significados específicos para cada regra. Por exemplo, quando você declara explicitamente java_binary(name='foo', ...) regra, você também declarar implicitamente um arquivo de saída segmente foo_deploy.jar como membro do mesmo pacote. Esse destino específico é um arquivo Java independente adequado para implantação.

Os destinos de saída implícitos são membros de primeira classe do gráfico de destino global. Assim como outros destinos, eles são criados sob demanda, quando especificados no comando de build de nível superior ou quando são pré-requisitos necessários para outros destinos de build. Eles podem ser referenciadas como dependências em arquivos BUILD e podem ser observadas em o resultado de ferramentas de análise, como bazel query.

Para cada tipo de regra de compilação, a documentação da regra contém um seção especial, detalhando os nomes e conteúdos de quaisquer resultados resultantes de uma declaração desse tipo de regra.

Uma distinção importante, mas um pouco sutil, entre os dois namespaces usados pelo sistema de build: rótulos identificam destinos, que podem ser regras ou arquivos, e os destinos dos arquivos podem ser divididos em destinos de arquivo de origem (ou de entrada) e arquivo derivado (ou de saída) de destino. Estes são os itens que podem ser mencionados nos arquivos BUILD, criar na linha de comando ou examinar usando bazel query; este é o namespace de destino. Cada destino de arquivo corresponde para um arquivo real no disco (o "namespace do sistema de arquivos"); cada regra target pode corresponder a zero, um ou mais arquivos reais no disco. Pode haver arquivos no disco que não tenham destino correspondente. para exemplo, arquivos de objeto .o produzidos durante a compilação em C++ não podem ser referenciados dentro de arquivos BUILD ou na linha de comando. Dessa forma, a ferramenta de build pode ocultar certos detalhes de implementação de como ele faz seu trabalho. Isso é explicado com mais detalhes a Referência do conceito BUILD.