Arquivos .bzl

Informar um problema Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Métodos globais disponíveis em todos os arquivos .bzl.

Membros

analysis_test_transition

transition analysis_test_transition(settings)

Cria uma transição de configuração a ser aplicada às dependências de uma regra de teste de análise. Essa transição só pode ser aplicada a atributos de regras com analysis_test = True. Essas regras têm recursos restritos (por exemplo, o tamanho da árvore de dependências é limitado). Portanto, as transições criadas com essa função têm um escopo potencial limitado em comparação com as transições criadas usando transition().

Essa função foi projetada principalmente para facilitar a biblioteca principal do Analysis Test Framework. Consulte a documentação ou a implementação dele para conferir as práticas recomendadas.

Parâmetros

Parâmetro Descrição
settings dict; required
Um dicionário que contém informações sobre as configurações que devem ser definidas por essa transição de configuração. As chaves são rótulos de configuração de build, e os valores são os novos valores pós-transição. Todas as outras configurações permanecem inalteradas. Use isso para declarar configurações específicas que um teste de análise precisa ter para ser aprovado.

aspecto

Aspect aspect(implementation, attr_aspects=[], toolchains_aspects=[], attrs={}, required_providers=[], required_aspect_providers=[], provides=[], requires=[], fragments=[], host_fragments=[], toolchains=[], incompatible_use_toolchain_transition=False, doc=None, *, apply_to_generating_rules=False, exec_compatible_with=[], exec_groups=None, subrules=[])

Cria um novo aspecto. O resultado dessa função precisa ser armazenado em um valor global. Consulte a introdução aos aspectos para mais detalhes.

Parâmetros

Parâmetro Descrição
implementation function; required
Uma função do Starlark que implementa esse aspecto, com exatamente dois parâmetros: Target (o destino a que o aspecto é aplicado) e ctx (o contexto da regra em que o destino é criado). Os atributos do destino estão disponíveis no campo ctx.rule. Essa função é avaliada durante a fase de análise para cada aplicação de um aspecto a um destino.
attr_aspects sequence de strings; o padrão é []
Lista de nomes de atributos. O aspecto se propaga ao longo das dependências especificadas nos atributos de um destino com esses nomes. Os valores comuns incluem deps e exports. A lista também pode conter uma única string "*" para propagação em todas as dependências de um destino.
toolchains_aspects sequence; o padrão é []
Lista de tipos de cadeia de ferramentas. O aspecto é propagado para conjuntos de ferramentas de destino que correspondem a esses tipos.
attrs dict; o padrão é {}
Um dicionário que declara todos os atributos do aspecto. Ele mapeia de um nome de atributo para um objeto de atributo, como attr.label ou attr.string (consulte o módulo attr). Os atributos de aspecto estão disponíveis para a função de implementação como campos do parâmetro ctx.

Os atributos implícitos que começam com _ precisam ter valores padrão e ser do tipo label ou label_list.

Os atributos explícitos precisam ser do tipo string e usar a restrição values. Atributos explícitos restringem o aspecto para que ele seja usado apenas com regras que tenham atributos de mesmo nome, tipo e valores válidos de acordo com a restrição.

Os atributos declarados vão converter None para o valor padrão.
required_providers sequence; o padrão é []
Esse atributo permite que o aspecto limite a propagação apenas aos destinos cujas regras anunciam os provedores necessários. O valor precisa ser uma lista que contenha provedores individuais ou listas de provedores, mas não ambos. Por exemplo, [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] é um valor válido, mas [FooInfo, BarInfo, [BazInfo, QuxInfo]] não é.

Uma lista não aninhada de provedores será convertida automaticamente em uma lista que contém uma lista de provedores. Ou seja, [FooInfo, BarInfo] será convertido automaticamente em [[FooInfo, BarInfo]].

Para tornar algumas regras (por exemplo, some_rule) visíveis a um aspecto, some_rule precisa anunciar todos os provedores de pelo menos uma das listas de provedores obrigatórias. Por exemplo, se o required_providers de um aspecto for [[FooInfo], [BarInfo], [BazInfo, QuxInfo]], ele poderá ver destinos some_rule se e somente se some_rule fornecer FooInfo, ou BarInfo, ou ambos BazInfo e QuxInfo.

required_aspect_providers sequence; o padrão é []
Esse atributo permite que o aspecto inspecione outros aspectos. O valor precisa ser uma lista que contenha provedores individuais ou listas de provedores, mas não ambos. Por exemplo, [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] é um valor válido, mas [FooInfo, BarInfo, [BazInfo, QuxInfo]] não é.

Uma lista não aninhada de provedores será convertida automaticamente em uma lista que contém uma lista de provedores. Ou seja, [FooInfo, BarInfo] será convertido automaticamente em [[FooInfo, BarInfo]].

Para tornar outro aspecto (por exemplo, other_aspect) visível para esse aspecto, other_aspect precisa fornecer todos os provedores de pelo menos uma das listas. No exemplo de [[FooInfo], [BarInfo], [BazInfo, QuxInfo]], esse aspecto pode ver other_aspect se e somente se other_aspect fornecer FooInfo, ou BarInfo, ou ambos BazInfo e QuxInfo.

provides sequence; o padrão é []
Uma lista de provedores que a função de implementação precisa retornar.

É um erro se a função de implementação omitir qualquer um dos tipos de provedores listados aqui do valor de retorno. No entanto, a função de implementação pode retornar outros provedores não listados aqui.

Cada elemento da lista é um objeto *Info retornado por provider(), exceto que um provedor legado é representado pelo nome da string.Quando um destino da regra é usado como uma dependência para um destino que declara um provedor obrigatório, não é necessário especificar esse provedor aqui. Basta que a função de implementação o retorne. No entanto, a prática recomendada é especificar esse valor, mesmo que não seja obrigatório. No entanto, o campo required_providers de um aspect exige que os provedores sejam especificados aqui.

requires sequence de Aspects; o padrão é []
Lista de aspectos que precisam ser propagados antes deste aspecto.
fragments sequence de strings; o padrão é []
Lista de nomes de fragmentos de configuração que o aspecto exige na configuração de destino.
host_fragments sequence de strings; o padrão é []
Lista de nomes de fragmentos de configuração que o aspecto exige na configuração do host.
toolchains sequence; o padrão é []
Se definido, o conjunto de toolchains que esse aspecto exige. A lista pode conter objetos String, Label ou StarlarkToolchainTypeApi, em qualquer combinação. As toolchains são encontradas verificando a plataforma atual e fornecidas à implementação do aspecto via ctx.toolchain.
incompatible_use_toolchain_transition bool; o padrão é False
Descontinuado. Não está mais em uso e deve ser removido.
doc string ou None; o padrão é None
Uma descrição do aspecto que pode ser extraído por ferramentas de geração de documentação.
apply_to_generating_rules bool; o padrão é False
Se for "true", o aspecto, quando aplicado a um arquivo de saída, será aplicado à regra de geração do arquivo de saída.

Por exemplo, suponha que um aspecto se propague de maneira transitiva pelo atributo "deps" e seja aplicado ao destino "alpha". Suponha que "alpha" tenha "deps = [':beta_output']", em que "beta_output" é uma saída declarada de um destino "beta". Suponha que "beta" tenha um destino "charlie" como uma das "deps". Se "apply_to_generating_rules=True" para o aspecto, ele será propagado por "alpha", "beta" e "charlie". Se for "False", o aspecto será propagado apenas para "alpha".

O padrão é "falso".
exec_compatible_with sequência de strings; o padrão é []
. Uma lista de restrições na plataforma de execução que se aplicam a todas as instâncias desse aspecto.
exec_groups dict ou None. O padrão é None
. Dicionário do nome do grupo de execução (string) para exec_groups. Se definido, permite que os aspectos executem ações em várias plataformas de execução em uma única instância. Consulte a documentação sobre grupos de execução para mais informações.
subrules sequência de Subrules; o padrão é []
Experimental: lista de subregras usadas por esse aspecto.

configuration_field

LateBoundDefault configuration_field(fragment, name)

Faz referência a um valor padrão de vinculação tardia para um atributo do tipo rótulo. Um valor é "vinculado tardiamente" se exigir que a configuração seja criada antes de determinar o valor. Qualquer atributo que use isso como um valor precisa ser privado.

Exemplo de uso:

Definir um atributo de regra: 

'_foo': attr.label(default=configuration_field(fragment='java', name='toolchain'))

Acessar na implementação da regra: 

  def _rule_impl(ctx):
    foo_info = ctx.attr._foo
    ...

Parâmetros

Parâmetro Descrição
fragment string; required
O nome de um fragmento de configuração que contém o valor de vinculação tardia.
name string; required
O nome do valor a ser obtido do fragmento de configuração.

depset

depset depset(direct=None, order="default", *, transitive=None)

Cria um depset. O parâmetro direct é uma lista de elementos diretos do conjunto de dependências, e o parâmetro transitive é uma lista de conjuntos de dependências cujos elementos se tornam elementos indiretos do conjunto de dependências criado. A ordem em que os elementos são retornados quando o conjunto de dependências é convertido em uma lista é especificada pelo parâmetro order. Consulte a Visão geral dos depsets para mais informações.

Todos os elementos (diretos e indiretos) de um conjunto de dependências precisam ser do mesmo tipo, conforme obtido pela expressão type(x).

Como um conjunto baseado em hash é usado para eliminar duplicatas durante a iteração, todos os elementos de um conjunto de dependências precisam ser hasháveis. No entanto, essa invariante não é verificada de forma consistente em todos os construtores. Use a flag --incompatible_always_check_depset_elements para ativar a verificação consistente. Esse será o comportamento padrão em versões futuras. Consulte Problema 10313.

Além disso, os elementos precisam ser imutáveis, mas essa restrição será reduzida no futuro.

A ordem do conjunto de dependências criado precisa ser compatível com a ordem dos conjuntos de dependências transitive. A ordem "default" é compatível com qualquer outra ordem, e todas as outras são compatíveis apenas entre si.

Parâmetros

Parâmetro Descrição
direct sequence ou None; o padrão é None
. Uma lista de elementos diretos de um conjunto de dependências.
order string; o padrão é "default"
A estratégia de travessia para o novo conjunto de dependências. Consulte aqui os valores possíveis.
transitive sequência de depsets ou None; o padrão é None
. Uma lista de depsets cujos elementos se tornarão elementos indiretos do depset.

exec_group

exec_group exec_group(toolchains=[], exec_compatible_with=[])

Cria um grupo de execução que pode ser usado para criar ações para uma plataforma de execução específica durante a implementação da regra.

Parâmetros

Parâmetro Descrição
toolchains sequence; o padrão é []
O conjunto de cadeias de ferramentas que esse grupo de execução exige. A lista pode conter objetos String, Label ou StarlarkToolchainTypeApi, em qualquer combinação.
exec_compatible_with sequence de strings; o padrão é []
Uma lista de restrições na plataforma de execução.

exec_transition

transition exec_transition(implementation, inputs, outputs)

Uma versão especializada de transition() usada para definir a transição de execução. Consulte a documentação ou a implementação dele para conferir as práticas recomendadas. Só pode ser usado nos builtins do Bazel.

Parâmetros

Parâmetro Descrição
implementation callable; required
inputs sequência de strings; obrigatório
outputs sequência de strings; obrigatório

macro

macro macro(implementation, attrs={}, inherit_attrs=None, finalizer=False, doc=None)

Define uma macro simbólica, que pode ser chamada em arquivos ou macros BUILD (legadas ou simbólicas) para definir destinos, possivelmente vários.

O valor retornado por macro(...) precisa ser atribuído a uma variável global em um arquivo .bzl. O nome da variável global será o nome do símbolo da macro.

Consulte Macros para um guia completo sobre como usar macros simbólicas.

Parâmetros

Parâmetro Descrição
implementation function; required
A função do Starlark que implementa essa macro. Os valores dos atributos da macro são transmitidos para a função de implementação como argumentos de palavra-chave. A função de implementação precisa ter pelo menos dois parâmetros nomeados, name e visibility, e, se a macro herdar atributos (consulte inherit_attrs abaixo), ela precisará ter um parâmetro de palavra-chave residual **kwargs.

Por convenção, a função de implementação precisa ter um parâmetro nomeado para qualquer atributo que a macro precise examinar, modificar ou transmitir para destinos que não sejam "principais". Já os atributos "em massa" herdados que serão transmitidos ao destino "principal" sem alterações são transmitidos como **kwargs.

A função de implementação não pode retornar um valor. Em vez disso, a função de implementação declara destinos chamando símbolos de regra ou macro.

O nome de qualquer macro simbólica de destino ou interna declarada por uma macro simbólica (incluindo por qualquer função do Starlark que a função de implementação da macro chame de forma transitiva) precisa ser igual a name (esse é o destino "principal") ou começar com name, seguido por um caractere separador ("_", "-" ou ".") e um sufixo de string. É permitido declarar destinos que violam esse esquema de nomenclatura, mas eles não podem ser criados, configurados ou usados como dependências.

Por padrão, os destinos declarados por uma macro simbólica (incluindo qualquer função do Starlark que a função de implementação da macro chama de maneira transitiva) ficam visíveis apenas no pacote que contém o arquivo .bzl que define a macro. Para declarar destinos visíveis externamente, inclusive para o chamador da macro simbólica, a função de implementação precisa definir visibility adequadamente, geralmente transmitindo visibility = visibility para a regra ou o símbolo de macro que está sendo chamado.

As APIs a seguir não estão disponíveis em uma função de implementação de macro e em qualquer função do Starlark que ela chama de maneira transitiva:

attrs dict; o padrão é {}
Um dicionário dos atributos compatíveis com essa macro, análogo a rule.attrs. As chaves são nomes de atributos, e os valores são objetos de atributo, como attr.label_list(...) (consulte o módulo attr), ou None. Uma entrada None significa que a macro não tem um atributo com esse nome, mesmo que ela tenha herdado um por inherit_attrs (veja abaixo).

O atributo especial name é pré-declarado e não pode ser incluído no dicionário. O nome do atributo visibility é reservado e não pode ser incluído no dicionário.

Atributos com nomes que começam com _ são particulares e não podem ser transmitidos no site de chamada da regra. Esses atributos podem receber um valor padrão (como em attr.label(default="//pkg:foo")) para criar uma dependência implícita de um rótulo.

Para limitar o uso de memória, há um limite no número de atributos que podem ser declarados.

inherit_attrs rule; ou macro; ou string; ou None; o padrão é None
Um símbolo de regra, um símbolo de macro ou o nome de uma lista de atributos comuns integrada (veja abaixo) de que a macro deve herdar atributos.

Se inherit_attrs for definido como a string "common", a macro vai herdar as definições de atributos de regra comuns usadas por todas as regras do Starlark.

Se o valor de retorno de rule() ou macro() não tiver sido atribuído a uma variável global em um arquivo .bzl, ele não será registrado como um símbolo de regra ou macro e, portanto, não poderá ser usado para inherit_attrs.

O mecanismo de herança funciona da seguinte maneira:

  1. Os atributos especiais name e visibility nunca são herdados.
  2. Atributos ocultos (aqueles com nomes que começam com "_") nunca são herdados.
  3. Atributos com nomes já definidos no dicionário attrs nunca são herdados. A entrada em attrs tem precedência. Uma entrada pode ser definida como None para garantir que nenhum atributo com esse nome seja definido na macro.
  4. Todos os outros atributos são herdados da regra ou macro e efetivamente mesclados no dicionário attrs.

Quando um atributo não obrigatório é herdado, o valor padrão dele é substituído por None, independente do que foi especificado na regra ou macro original. Isso garante que, quando a macro encaminha o valor do atributo para uma instância da regra ou macro encapsulada, como ao transmitir o **kwargs não modificado, um valor que estava ausente na chamada da macro externa também estará ausente na chamada da regra ou macro interna. Isso acontece porque transmitir None para um atributo é tratado da mesma forma que omitir o atributo. Isso é importante porque omitir um atributo tem semântica sutilmente diferente de transmitir o valor padrão aparente dele. Em particular, os atributos omitidos não são mostrados em alguns formatos de saída bazel query, e os padrões calculados só são executados quando o valor é omitido. Se a macro precisar examinar ou modificar um atributo herdado, por exemplo, para adicionar um valor a um atributo tags herdado, processe o caso None na função de implementação da macro.

Por exemplo, a macro a seguir herda todos os atributos de native.cc_library, exceto cxxopts (que é removido da lista de atributos) e copts (que recebe uma nova definição). Ele também verifica o valor None padrão do atributo tags herdado antes de anexar uma tag adicional. 

def _my_cc_library_impl(name, visibility, tags, **kwargs):
    # Append a tag; tags attr was inherited from native.cc_library, and
    # therefore is None unless explicitly set by the caller of my_cc_library()
    my_tags = (tags or []) + ["my_custom_tag"]
    native.cc_library(
        name = name,
        visibility = visibility,
        tags = my_tags,
        **kwargs
    )

my_cc_library = macro(
    implementation = _my_cc_library_impl,
    inherit_attrs = native.cc_library,
    attrs = {
        "cxxopts": None,
        "copts": attr.string_list(default = ["-D_FOO"]),
    },
)

Se inherit_attrs estiver definido, a função de implementação da macro precisa ter um parâmetro de palavra-chave residual **kwargs.

Por convenção, uma macro precisa transmitir atributos herdados e não substituídos sem alterações para o símbolo de regra ou macro "principal" que ela está encapsulando. Normalmente, a maioria dos atributos herdados não tem um parâmetro na lista de parâmetros da função de implementação e é transmitida simplesmente por **kwargs. Pode ser conveniente que a função de implementação tenha parâmetros explícitos para alguns atributos herdados (mais comumente, tags e testonly) se a macro precisar transmitir esses atributos para destinos "principais" e não "principais". No entanto, se a macro também precisar examinar ou manipular esses atributos, tome cuidado para processar o valor padrão None de atributos herdados não obrigatórios.

finalizer bool; o padrão é False
Indica se essa macro é um finalizador de regra, ou seja, uma macro que, independente da posição em um arquivo BUILD, é avaliada no final do carregamento do pacote, depois que todos os destinos não finalizadores são definidos.

Ao contrário das macros simbólicas comuns, os finalizadores de regras podem chamar native.existing_rule() e native.existing_rules() para consultar o conjunto de destinos de regras não finalizadores definidos no pacote atual. Observe que native.existing_rule() e native.existing_rules() não podem acessar os destinos definidos por nenhum finalizador de regra, incluindo este.

doc string; ou None; o padrão é None
Uma descrição da macro que pode ser extraída por ferramentas de geração de documentação.

module_extension

unknown module_extension(implementation, *, tag_classes={}, doc=None, environ=[], os_dependent=False, arch_dependent=False)

Cria uma nova extensão de módulo. Armazene-o em um valor global para que possa ser exportado e usado em um arquivo MODULE.bazel com use_extension.

Parâmetros

Parâmetro Descrição
implementation callable; required
A função que implementa essa extensão de módulo. Precisa usar um único parâmetro, module_ctx. A função é chamada uma vez no início de um build para determinar o conjunto de repositórios disponíveis.
tag_classes dict; o padrão é {}
Um dicionário para declarar todas as classes de tag usadas pela extensão. Ele mapeia do nome da classe de tag para um objeto tag_class.
doc string ou None; o padrão é None
Uma descrição da extensão do módulo que pode ser extraída por ferramentas de geração de documentação.
environ sequência de strings; o padrão é []
. Fornece uma lista de variáveis de ambiente de que essa extensão de módulo depende. Se uma variável de ambiente nessa lista mudar, a extensão será reavaliada.
os_dependent bool; o padrão é False
Indica se a extensão depende do SO ou não.
arch_dependent bool; o padrão é False
Indica se a extensão depende da arquitetura ou não

provedor

unknown provider(doc=None, *, fields=None, init=None)

Define um símbolo de provedor. O resultado dessa função precisa ser armazenado em um valor global. O provedor pode ser instanciado chamando-o ou usado diretamente como uma chave para recuperar uma instância desse provedor de um destino. Exemplo:
MyInfo = provider()
...
def _my_library_impl(ctx):
    ...
    my_info = MyInfo(x = 2, y = 3)
    # my_info.x == 2
    # my_info.y == 3
    ...

Consulte Regras (provedores) para um guia completo sobre como usar provedores.

Retorna um valor de chamada Provider se init não for especificado.

Se init for especificado, vai retornar uma tupla de dois elementos: um valor de chamada Provider e um valor de chamada construtor bruto. Consulte Regras (inicialização personalizada de provedores personalizados) e a discussão do parâmetro init abaixo para mais detalhes.

Parâmetros

Parâmetro Descrição
doc string ou None; o padrão é None
Uma descrição do provedor que pode ser extraída por ferramentas de geração de documentação.
fields sequência de strings, dicionário ou None. O padrão é None
. Se especificado, restringe o conjunto de campos permitidos.
Os valores possíveis são:
  • Lista de campos:
    provider(fields = ['a', 'b'])

  • nome do campo do dicionário -> documentação:
    provider(
       fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })
Todos os campos são opcionais.
init chamável ou None; o padrão é None
. Um callback opcional para pré-processar e validar os valores de campo do provedor durante a instanciação. Se init for especificado, provider() vai retornar uma tupla de dois elementos: o símbolo do provedor normal e um construtor bruto.

Confira uma descrição precisa em Regras (inicialização personalizada de provedores) para uma discussão intuitiva e casos de uso.

Seja P o símbolo do provedor criado chamando provider(). Conceitualmente, uma instância de P é gerada chamando uma função de construtor padrão c(*args, **kwargs), que faz o seguinte:

  • Se args não estiver vazio, ocorrerá um erro.
  • Se o parâmetro fields foi especificado quando provider() foi chamado e se kwargs contém alguma chave que não foi listada em fields, um erro vai ocorrer.
  • Caso contrário, c vai retornar uma nova instância que tem, para cada entrada k: v em kwargs, um campo chamado k com o valor v.
No caso em que um callback init não é fornecido, uma chamada ao símbolo P em si atua como uma chamada à função construtora padrão c. Em outras palavras, P(*args, **kwargs) retorna c(*args, **kwargs). Por exemplo,
MyInfo = provider()
m = MyInfo(foo = 1)
 vai fazer com que m seja uma instância MyInfo com m.foo == 1.

Mas, no caso em que init é especificado, a chamada P(*args, **kwargs) executa as seguintes etapas:

  1. O callback é invocado como init(*args, **kwargs), ou seja, com exatamente os mesmos argumentos posicionais e de palavra-chave que foram transmitidos para P.
  2. O valor de retorno de init precisa ser um dicionário, d, cujas chaves são strings de nome de campo. Caso contrário, um erro vai ocorrer.
  3. Uma nova instância de P é gerada como se fosse uma chamada do construtor padrão com as entradas de d como argumentos de palavra-chave, como em c(**d).

Observação: as etapas acima implicam que um erro ocorre se *args ou **kwargs não corresponder à assinatura de init ou se a avaliação do corpo de init falhar (talvez intencionalmente por uma chamada para fail()) ou se o valor de retorno de init não for um dicionário com o esquema esperado.

Dessa forma, o callback init generaliza a construção normal do provedor, permitindo argumentos posicionais e lógica arbitrária para pré-processamento e validação. Ela não permite burlar a lista de fields permitidos.

Quando init é especificado, o valor de retorno de provider() se torna uma tupla (P, r), em que r é o construtor bruto. Na verdade, o comportamento de r é exatamente o da função construtora padrão c discutida acima. Normalmente, r é vinculado a uma variável cujo nome é prefixado com um sublinhado para que apenas o arquivo .bzl atual tenha acesso direto a ele:

MyInfo, _new_myinfo = provider(init = ...)

repository_rule

callable repository_rule(implementation, *, attrs=None, local=False, environ=[], configure=False, remotable=False, doc=None)

Cria uma regra de repositório. Armazene em um valor global para que possa ser carregado e chamado de uma função de implementação module_extension() ou usado por use_repo_rule().

Parâmetros

Parâmetro Descrição
implementation callable; required
a função que implementa essa regra. Precisa ter um único parâmetro, repository_ctx. A função é chamada durante a fase de carregamento para cada instância da regra.
attrs dict ou None. O padrão é None
. Um dicionário para declarar todos os atributos da regra do repositório. Ele mapeia de um nome de atributo para um objeto de atributo (consulte o módulo attr). Atributos que começam com _ são particulares e podem ser usados para adicionar uma dependência implícita de um rótulo a um arquivo. Uma regra de repositório não pode depender de um artefato gerado. O atributo name é adicionado implicitamente e não pode ser especificado.

Os atributos declarados vão converter None para o valor padrão.
local bool; o padrão é False
Indica que essa regra busca tudo do sistema local e precisa ser reavaliada a cada busca.
environ sequência de strings. O padrão é []
. Suspenso. Este parâmetro foi suspenso. Migre para repository_ctx.getenv.
Fornece uma lista de variáveis de ambiente de que essa regra de repositório depende. Se uma variável de ambiente nessa lista mudar, o repositório será buscado novamente.
configure bool; o padrão é False
Indica que o repositório inspeciona o sistema para fins de configuração.
remotable bool; o padrão é False
Experimental. Esse parâmetro é experimental e pode mudar a qualquer momento. Não dependa dele. Ele pode ser ativado experimentalmente definindo --experimental_repo_remote_exec
Compatível com execução remota
doc string ou None; o padrão é None
Uma descrição da regra do repositório que pode ser extraída por ferramentas de geração de documentação.

regra

callable rule(implementation, *, test=unbound, attrs={}, outputs=None, executable=unbound, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], incompatible_use_toolchain_transition=False, doc=None, provides=[], dependency_resolution_rule=False, exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, initializer=None, parent=None, extendable=None, subrules=[])

Cria uma regra que pode ser chamada de um arquivo BUILD ou uma macro para criar destinos.

As regras precisam ser atribuídas a variáveis globais em um arquivo .bzl. O nome da variável global é o nome da regra.

As regras de teste precisam ter um nome que termine em _test, enquanto todas as outras regras não podem ter esse sufixo. Essa restrição se aplica apenas a regras, não aos destinos delas.

Parâmetros

Parâmetro Descrição
implementation function; required
a função Starlark que implementa essa regra precisa ter exatamente um parâmetro: ctx. A função é chamada durante a fase de análise para cada instância da regra. Ele pode acessar os atributos fornecidos pelo usuário. Ele precisa criar ações para gerar todas as saídas declaradas.
test bool; o padrão é unbound
Indica se a regra é de teste, ou seja, se ela pode ser o assunto de um comando blaze test. Todas as regras de teste são consideradas executáveis automaticamente. Não é necessário (e nem recomendado) definir explicitamente executable = True para uma regra de teste. O valor padrão é False. Consulte a página "Regras" para mais informações.
attrs dict; o padrão é {}
Um dicionário para declarar todos os atributos da regra. Ele mapeia de um nome de atributo para um objeto de atributo (consulte o módulo attr). Atributos que começam com _ são particulares e podem ser usados para adicionar uma dependência implícita a um rótulo. O atributo name é adicionado implicitamente e não pode ser especificado. Os atributos visibility, deprecation, tags, testonly e features são adicionados implicitamente e não podem ser substituídos. A maioria das regras precisa apenas de alguns atributos. Para limitar o uso de memória, há um limite no número de atributos que podem ser declarados.

Os atributos declarados vão converter None para o valor padrão.
outputs dict; ou None; ou function; o padrão é None
Descontinuado. Esse parâmetro foi descontinuado e será removido em breve. Não dependa dele. Ele está desativado com --incompatible_no_rule_outputs_param. Use essa flag para verificar se seu código é compatível com a remoção iminente.
Esse parâmetro foi descontinuado. Migre as regras para usar OutputGroupInfo ou attr.output.

Um esquema para definir saídas pré-declaradas. Ao contrário dos atributos output e output_list, o usuário não especifica os rótulos desses arquivos. Consulte a página "Regras" para mais informações sobre saídas pré-declaradas.

O valor desse argumento é um dicionário ou uma função de callback que produz um dicionário. O callback funciona de maneira semelhante aos atributos de dependência calculados: os nomes dos parâmetros da função são comparados aos atributos da regra. Por exemplo, se você transmitir outputs = _my_func com a definição def _my_func(srcs, deps): ..., a função terá acesso aos atributos srcs e deps. Seja especificado diretamente ou por uma função, o dicionário é interpretado da seguinte maneira.

Cada entrada no dicionário cria uma saída pré-declarada em que a chave é um identificador e o valor é um modelo de string que determina o rótulo da saída. Na função de implementação da regra, o identificador se torna o nome do campo usado para acessar o File da saída em ctx.outputs. O rótulo da saída tem o mesmo pacote da regra, e a parte depois do pacote é produzida substituindo cada marcador de posição do formulário "%{ATTR}" por uma string formada pelo valor do atributo ATTR:

  • Os atributos do tipo string são substituídos literalmente.
  • Os atributos do tipo rótulo se tornam parte do rótulo após o pacote, menos a extensão do arquivo. Por exemplo, o marcador "//pkg:a/b.c" se torna "a/b".
  • Os atributos com tipo de saída se tornam parte do rótulo após o pacote, incluindo a extensão do arquivo (no exemplo acima, "a/b.c").
  • Todos os atributos do tipo lista (por exemplo, attr.label_list) usados em espaços reservados precisam ter exatamente um elemento. A conversão é igual à versão sem lista (attr.label).
  • Outros tipos de atributos podem não aparecer em marcadores de posição.
  • Os marcadores de posição especiais sem atributo %{dirname} e %{basename} são expandidos para essas partes do rótulo da regra, excluindo o pacote. Por exemplo, em "//pkg:a/b.c", o dirname é a e o basename é b.c.

Na prática, o marcador de posição de substituição mais comum é "%{name}". Por exemplo, para um destino chamado "foo", o dicionário de saídas {"bin": "%{name}.exe"} pré-declara uma saída chamada foo.exe, que pode ser acessada na função de implementação como ctx.outputs.bin.

executable bool; o padrão é unbound
Indica se essa regra é considerada executável, ou seja, se ela pode ser o assunto de um comando blaze run. O padrão é False. Consulte a página "Regras" para mais informações.
output_to_genfiles bool; o padrão é False
Se for "true", os arquivos serão gerados no diretório "genfiles" em vez de "bin". A menos que você precise dela para compatibilidade com regras atuais (por exemplo, ao gerar arquivos de cabeçalho para C++), não defina essa flag.
fragments sequence de strings; o padrão é []
Lista de nomes de fragmentos de configuração que a regra exige na configuração de destino.
host_fragments sequência de strings; o padrão é []
. Lista de nomes de fragmentos de configuração que a regra exige na configuração do host.
_skylark_testable bool; o padrão é False
(Experimental)

Se for "true", essa regra vai expor as ações dela para inspeção por regras que dependem dela usando um provedor Actions. O provedor também está disponível para a própria regra chamando ctx.created_actions().

Isso só deve ser usado para testar o comportamento no momento da análise das regras do Starlark. Essa flag pode ser removida no futuro.
toolchains sequence; o padrão é []
Se definido, o conjunto de cadeias de ferramentas exigido por essa regra. A lista pode conter objetos String, Label ou StarlarkToolchainTypeApi, em qualquer combinação. Para encontrar as toolchains, verifique a plataforma atual e forneça-as à implementação da regra usando ctx.toolchain.
incompatible_use_toolchain_transition bool; o padrão é False
Descontinuado. Não está mais em uso e deve ser removido.
doc string ou None. O padrão é None
. Uma descrição da regra que pode ser extraída por ferramentas de geração de documentação.
provides sequence; o padrão é []
Uma lista de provedores que a função de implementação precisa retornar.

É um erro se a função de implementação omitir qualquer um dos tipos de provedores listados aqui do valor de retorno. No entanto, a função de implementação pode retornar outros provedores não listados aqui.

Cada elemento da lista é um objeto *Info retornado por provider(), exceto que um provedor legado é representado pelo nome da string.Quando um destino da regra é usado como uma dependência para um destino que declara um provedor obrigatório, não é necessário especificar esse provedor aqui. Basta que a função de implementação o retorne. No entanto, a prática recomendada é especificar esse valor, mesmo que não seja obrigatório. No entanto, o campo required_providers de um aspect exige que os provedores sejam especificados aqui.

dependency_resolution_rule bool; o padrão é False
Se definido, a regra poderá ser uma dependência por atributos também marcados como disponíveis em materializadores. Todos os atributos de regras com essa flag definida também precisam ser marcados como disponíveis em materializadores. Assim, as regras marcadas não podem depender de regras que não foram marcadas.
exec_compatible_with sequence de strings; o padrão é []
Uma lista de restrições na plataforma de execução que se aplicam a todos os destinos desse tipo de regra.
analysis_test bool; o padrão é False
Se for "true", essa regra será tratada como um teste de análise.

Observação: as regras de teste de análise são definidas principalmente usando a infraestrutura fornecida nas bibliotecas principais do Starlark. Consulte Testes para orientações.

Se uma regra for definida como uma regra de teste de análise, ela poderá usar transições de configuração definidas com analysis_test_transition nos atributos, mas terá algumas restrições:

  • Os destinos dessa regra são limitados no número de dependências transitivas que podem ter.
  • A regra é considerada uma regra de teste (como se test=True estivesse definido). Isso substitui o valor de test.
  • A função de implementação da regra pode não registrar ações. Em vez disso, ele precisa registrar um resultado de aprovação/reprovação fornecendo AnalysisTestResultInfo.
build_setting BuildSetting ou None. O padrão é None
. Se definido, descreve que tipo de build setting essa regra é. Consulte o módulo config. Se essa opção estiver definida, um atributo obrigatório chamado "build_setting_default" será adicionado automaticamente a essa regra, com um tipo correspondente ao valor transmitido aqui.
cfg O padrão é None
. Se definido, aponta para a transição de configuração que a regra vai aplicar à própria configuração antes da análise.
exec_groups dict ou None. O padrão é None
. Dicionário do nome do grupo de execução (string) para exec_groups. Se definido, permite que as regras executem ações em várias plataformas de execução em um único destino. Consulte a documentação sobre grupos de execução para mais informações.
initializer O padrão é None
. Experimental: a função Stalark que inicializa os atributos da regra.

A função é chamada no momento do carregamento para cada instância da regra. Ele é chamado com name e os valores de atributos públicos definidos pela regra (não com atributos genéricos, por exemplo, tags).

Ele precisa retornar um dicionário dos nomes de atributos para os valores desejados. Os atributos que não são retornados não são afetados. Retornar None como valor resulta no uso do valor padrão especificado na definição do atributo.

Os inicializadores são avaliados antes dos valores padrão especificados em uma definição de atributo. Consequentemente, se um parâmetro na assinatura do inicializador tiver um valor padrão, ele vai substituir o padrão da definição do atributo, exceto se retornar None.

Da mesma forma, se um parâmetro na assinatura do inicializador não tiver um padrão, ele se tornará obrigatório. É recomendável omitir configurações padrão/obrigatórias em uma definição de atributo nesses casos.

É recomendável usar **kwargs para atributos que não são processados.

No caso de regras estendidas, todos os inicializadores são chamados do filho para os ancestrais. Cada inicializador recebe apenas os atributos públicos que conhece.

parent O padrão é None
Experimental: a regra do Stalark que é estendida. Quando definido, os atributos públicos e os provedores anunciados são mesclados. A regra corresponde a executable e test do elemento principal. Os valores de fragments, toolchains, exec_compatible_with e exec_groups são mesclados. Parâmetros legados ou obsoletos não podem ser definidos. A transição de configuração de entrada cfg do elemento pai é aplicada depois da configuração de entrada desta regra.
extendable bool; ou Label; ou string; ou None; o padrão é None
Experimental: um rótulo de uma lista de permissão que define quais regras podem estender essa regra. Também pode ser definido como True/False para sempre permitir/proibir a extensão. Por padrão, o Bazel sempre permite extensões.
subrules sequência de Subrules; o padrão é []
Experimental: List of subrules used by this rule.

selecionar

unknown select(x, no_match_error='')

select() é a função auxiliar que torna um atributo de regra configurável. Consulte a enciclopédia de builds para mais detalhes.

Parâmetros

Parâmetro Descrição
x dict; required
Um dicionário que mapeia condições de configuração para valores. Cada chave é um rótulo ou uma string de rótulo que identifica uma instância de config_setting ou constraint_value. Consulte a documentação sobre macros para saber quando usar um rótulo em vez de uma string.
no_match_error string; o padrão é ''
Erro personalizado opcional a ser informado se nenhuma condição corresponder.

subrule

Subrule subrule(implementation, attrs={}, toolchains=[], fragments=[], subrules=[])

Cria uma nova instância de uma subregra. O resultado dessa função precisa ser armazenado em uma variável global antes de ser usado.

Parâmetros

Parâmetro Descrição
implementation function; required
A função Starlark que implementa essa subregra.
attrs dict; o padrão é {}
Um dicionário para declarar todos os atributos (particulares) da subregra.

As subregras só podem ter atributos particulares do tipo marcador (ou seja, marcador ou lista de marcadores). Os valores resolvidos correspondentes a esses rótulos são transmitidos automaticamente pelo Bazel para a função de implementação da subregra como argumentos nomeados. Portanto, a função de implementação precisa aceitar parâmetros nomeados que correspondam aos nomes dos atributos. Os tipos desses valores serão:

  • FilesToRunProvider para atributos de rótulo com executable=True
  • File para atributos de rótulo com allow_single_file=True
  • Target para todos os outros atributos de rótulo
  • [Target] para todos os atributos de lista de rótulos
toolchains sequence; o padrão é []
Se definido, o conjunto de toolchains exigido por essa subregra. A lista pode conter objetos String, Label ou StarlarkToolchainTypeApi, em qualquer combinação. Para encontrar as toolchains, basta verificar a plataforma atual e fornecer à implementação da subregra usando ctx.toolchains. As AEGs precisam ser ativadas nas regras de consumo se esse parâmetro estiver definido. Se você ainda não migrou para AEGs, consulte https://bazel.build/extending/auto-exec-groups#migration-aegs.
fragments sequence de strings; o padrão é []
Lista de nomes de fragmentos de configuração que a subregra exige na configuração de destino.
subrules sequence de Subrules; o padrão é []
Lista de outras subregras necessárias para esta subregra.

tag_class

tag_class tag_class(attrs={}, *, doc=None)

Cria um objeto tag_class, que define um esquema de atributo para uma classe de tags, que são objetos de dados utilizáveis por uma extensão de módulo.

Parâmetros

Parâmetro Descrição
attrs dict; o padrão é {}
Um dicionário para declarar todos os atributos dessa classe de tag. Ele mapeia de um nome de atributo para um objeto de atributo (consulte o módulo attr).

Ao contrário de rule(), aspect() e repository_rule(), os atributos declarados não convertem None para o valor padrão. Para que o padrão seja usado, o atributo precisa ser omitido completamente pelo caller.
doc string ou None. O padrão é None
. Uma descrição da classe de tag que pode ser extraída por ferramentas de geração de documentação.

visibilidade

None visibility(value)

Define a visibilidade de carregamento do módulo .bzl que está sendo inicializado.

A visibilidade de carga de um módulo determina se outros arquivos BUILD e .bzl podem carregá-lo. Isso é diferente da visibilidade de destino do arquivo de origem .bzl subjacente, que determina se o arquivo pode aparecer como uma dependência de outros destinos. A visibilidade de carregamento funciona no nível dos pacotes: para carregar um módulo, o arquivo que faz o carregamento precisa estar em um pacote que recebeu visibilidade para o módulo. Um módulo sempre pode ser carregado no próprio pacote, independente da visibilidade.

visibility() só pode ser chamado uma vez por arquivo .bzl e apenas no nível superior, não dentro de uma função. O estilo preferido é colocar essa chamada imediatamente abaixo das instruções load() e de qualquer lógica breve necessária para determinar o argumento.

Se a flag --check_bzl_visibility estiver definida como "false", as violações de visibilidade de carregamento vão emitir avisos, mas não vão falhar na build.

Parâmetros

Parâmetro Descrição
value obrigatório
Uma lista de strings de especificação de pacote ou uma única string de especificação de pacote.

As especificações de pacote seguem o mesmo formato de package_group, exceto que especificações negativas não são permitidas. Ou seja, uma especificação pode ter as formas:

  • "//foo": o pacote //foo
  • "//foo/...": o pacote //foo e todos os subpacotes dele.
  • "public" ou "private": todos os pacotes ou nenhum pacote, respectivamente

A sintaxe "@" não é permitida. Todas as especificações são interpretadas em relação ao repositório do módulo atual.

Se value for uma lista de strings, o conjunto de pacotes com visibilidade concedida a esse módulo será a união dos pacotes representados por cada especificação. Uma lista vazia tem o mesmo efeito que private. Se value for uma única string, ela será tratada como se fosse a lista singleton [value].

As flags --incompatible_package_group_has_public_syntax e --incompatible_fix_package_group_reporoot_syntax não têm efeito nesse argumento. Os valores "public" e "private" estão sempre disponíveis, e "//..." é sempre interpretado como "todos os pacotes no repositório atual".