Arquivos .bzl

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.

Uma lista não aninhada de provedores será convertida automaticamente em uma lista com 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.

Uma lista não aninhada de provedores será convertida automaticamente em uma lista com 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.

É 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.

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".

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 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 chame de forma 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:

• package(), licenses()
• environment_group()
• native.glob(): em vez disso, transmita um glob para a macro usando um atributo de lista de rótulos.
• native.subpackages()
• (permitido apenas em finalizadores de regra, consulte finalizer abaixo) native.existing_rules(), native.existing_rule()
• (para WORKSPACE linhas de execução) workspace(), register_toolchains(), register_execution_platforms(), bind(), instanciação de regra de repositório

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.

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.

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.

• Lista de campos:
  

  provider(fields = ['a', 'b'])

• dictionary field name -> documentation:
  

  provider(
         fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })

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 ocorre.
• 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.

MyInfo = provider()
m = MyInfo(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 = ...)

Os atributos declarados vão converter None para o valor padrão.

Os atributos declarados vão converter None para o valor padrão.

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 correspondidos 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 forma.

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 é a mesma da versão sem lista (attr.label).
• Outros tipos de atributos podem não aparecer em substitutos.
• 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.

É 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.

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.

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.

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

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.

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 que recebem visibilidade para 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".