Arquivos .bzl

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

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

Uma lista de provedores não aninhada é 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 para um aspecto, some_rule precisa anunciar todos os provedores de pelo menos uma das listas obrigatórias. Por exemplo, se o required_providers de um aspecto for [[FooInfo], [BarInfo], [BazInfo, QuxInfo]], ele poderá ver destinos some_rule somente se some_rule fornecer FooInfo, ou BarInfo ou BazInfo e QuxInfo.

Uma lista de provedores não aninhada é convertida automaticamente em uma lista que contém uma lista de provedores. Ou seja, [FooInfo, BarInfo] será automaticamente convertido 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 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 provedores adicionais 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 dependência de um destino que declara um provedor obrigatório, não é necessário especificar o provedor aqui. Basta que a função de implementação o retorne. No entanto, especificar isso é uma prática recomendada, mesmo que isso não seja obrigatório. No entanto, o campo required_providers de um aspecto exige que os provedores sejam especificados aqui.

Por exemplo, suponha que um aspecto seja propagado transitivamente pelo atributo `deps` e 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 `charlie` de destino como um de seus `deps`. Suponha que `alpha` tenha `deps = [':beta_output']`, em que `beta_output` é uma saída declarada de um destino `beta`. Suponha que `beta` tenha um `charlie` de destino como um de seus `deps`. Se `apply_to_generated_rules=True será propagado com `apply_to_generated_rules=True.

O padrão é "falso".

• lista de campos:
  

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

• dictionary field name -> documentation:
  

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

A seguir, há uma descrição precisa. Consulte Regras (inicialização personalizada de provedores) para ter uma discussão intuitiva e casos de uso.

Deixe P ser 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 for especificado quando provider() for chamado e kwargs contiver alguma chave que não esteja listada em fields, ocorrerá um erro.
• Caso contrário, c retorna uma nova instância que tem, para cada entrada k: v em kwargs, um campo chamado k com valor v.

MyInfo = provider()
m = MyInfo(foo = 1)

No entanto, no caso em que init for especificado, a chamada P(*args, **kwargs) realizará as seguintes etapas:

1. O callback é invocado como init(*args, **kwargs), ou seja, com 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, com chaves que 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 chamar o 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. Isso não permite contornar 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 de construtor padrão c discutida acima. Normalmente, r está vinculado a uma variável cujo nome é prefixado com um sublinhado, para que apenas o arquivo .bzl atual tenha acesso direto a ela:

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

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

O valor desse argumento é um dicionário ou uma função de callback que produz um dicionário. O callback funciona de forma semelhante aos atributos de dependência computados: os nomes de parâmetro da função são comparados com os 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. Independentemente de o dicionário ser especificado diretamente ou por meio de uma função, ele é 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 no ctx.outputs. O rótulo da saída tem o mesmo pacote que a regra, e a parte após o pacote é produzida substituindo cada marcador de posição do formulário "%{ATTR}" por uma string formada a partir do 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 rótulo "//pkg:a/b.c" se torna "a/b".
• Os atributos do tipo de saída se tornam parte do rótulo após o pacote, incluindo a extensão do arquivo ("a/b.c" no exemplo acima).
• Todos os atributos do tipo lista (por exemplo, attr.label_list) usados em marcadores de posição precisam ter apenas um elemento. A conversão é a mesma da versão não listada (attr.label).
• Outros tipos de atributos podem não aparecer nos marcadores de posição.
• Os marcadores de posição que não são atributos especiais %{dirname} e %{basename} se expandem para essas partes do rótulo da regra, exceto 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 dict 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 provedores adicionais 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, é considerada uma prática recomendada especificar o valor, mesmo que isso não seja obrigatório. No entanto, o campo required_providers de um aspect exige que 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 ver orientações.

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

• As metas dessa regra são limitadas no número de dependências transitivas que podem ter.
• A regra é considerada de teste (como se test=True estivesse definida). Isso substitui o valor de test.
• A função de implementação de regras pode não registrar ações. Em vez disso, é necessário registrar um resultado de aprovação/reprovação fornecendo AnalysisTestResultInfo.

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

Ele precisa retornar um dicionário dos nomes dos atributos para os valores desejados. Os atributos não retornados não são afetados. Retornar None como um 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 contiver um valor padrão, ele 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. Nesses casos, é recomendável omitir as configurações padrão/obrigatórias em uma definição de atributo.

É uma prática recomendada usar **kwargs para atributos que não são processados.

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

As subregras só podem ter atributos particulares do tipo rótulo (ou seja, rótulo ou lista de rótulos). Os valores resolvidos correspondentes a esses rótulos são transmitidos automaticamente pelo Bazel para a função de implementação da subregrinha como argumentos nomeados. Portanto, a função de implementação é necessária para aceitar parâmetros nomeados que correspondem 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

As especificações de pacote seguem o mesmo formato de package_group, exceto que especificações de pacote negativas não são permitidas. Isto é, uma especificação pode ter os seguintes formatos:

• "//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 para este 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 vai ser tratada como se fosse a lista de 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".