Regras para plataformas e conjuntos de ferramentas

Nightly · 9.1 · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 8.1

Esse conjunto de regras existe para permitir que você modele plataformas de hardware específicas para as quais está criando e especifique as ferramentas específicas necessárias para compilar o código dessas plataformas. O usuário precisa estar familiarizado com os conceitos explicados aqui.

Regras

constraint_setting

Ver origem da regra 
constraint_setting(name, default_constraint_value, deprecation, distribs, features, licenses, tags, testonly, visibility)

Essa regra é usada para introduzir um novo tipo de restrição para o qual uma plataforma pode especificar um valor. Por exemplo, é possível definir um constraint_setting chamado "glibc_version" para representar a capacidade das plataformas de ter diferentes versões da biblioteca glibc instaladas. Para mais detalhes, consulte a página Plataformas.

Cada constraint_setting tem um conjunto extensível de constraint_values associados. Geralmente, eles são definidos no mesmo pacote, mas, às vezes, um pacote diferente introduz novos valores para uma configuração existente. Por exemplo, a configuração predefinida @platforms//cpu:cpu pode ser estendida com um valor personalizado para definir uma plataforma que segmenta uma arquitetura de CPU obscura.

Argumentos

Atributos
name

Nome; obrigatório

Um nome exclusivo para esse destino.
default_constraint_value

Nome; não configurável; o padrão é None

O rótulo do valor padrão para essa configuração, a ser usado se nenhum valor for fornecido. Se este atributo estiver presente, o constraint_value a que ele aponta precisa ser definido no mesmo pacote que este constraint_setting.

Se uma configuração de restrição tiver um valor padrão, sempre que uma plataforma não incluir nenhum valor de restrição para essa configuração, será o mesmo que se a plataforma tivesse especificado o valor padrão. Caso contrário, se não houver um valor padrão, a configuração de restrição será considerada não especificada por essa plataforma. Nesse caso, a plataforma não corresponderia a nenhuma lista de restrições (como para um config_setting) que exige um valor específico para essa configuração.

constraint_value

Ver origem da regra 
constraint_value(name, constraint_setting, deprecation, distribs, features, licenses, tags, testonly, visibility)
 Essa regra introduz um novo valor para um determinado tipo de restrição. Para mais detalhes, consulte a página Plataformas.

Exemplo

O exemplo a seguir cria um novo valor possível para o constraint_value predefinido que representa a arquitetura da CPU. 

constraint_value(
    name = "mips",
    constraint_setting = "@platforms//cpu:cpu",
)
As plataformas podem declarar que têm a arquitetura mips como uma alternativa a x86_64, arm e assim por diante.

Argumentos

Atributos
name

Nome; obrigatório

Um nome exclusivo para esse destino.
constraint_setting

Rótulo; não configurável; obrigatório

O constraint_setting para o qual esse constraint_value é uma opção possível.

platform

Ver origem da regra 
platform(name, constraint_values, deprecation, distribs, exec_properties, features, licenses, parents, remote_execution_properties, tags, testonly, visibility)

Essa regra define uma nova plataforma: uma coleção nomeada de opções de restrição (como arquitetura de CPU ou versão do compilador) que descreve um ambiente em que parte do build pode ser executada. Para mais detalhes, consulte a página Plataformas.

Exemplo

Isso define uma plataforma que descreve qualquer ambiente que executa o Linux no ARM. 

platform(
    name = "linux_arm",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)

Herança de plataforma

As plataformas podem usar o atributo parents para especificar outra plataforma da qual herdarão valores de restrição. Embora o atributo parents receba uma lista, no momento, apenas um único valor é compatível, e especificar vários pais é um erro.

Ao verificar o valor de uma configuração de restrição em uma plataforma, primeiro os valores definidos diretamente (pelo atributo constraint_values) são verificados e, em seguida, os valores de restrição no pai. Isso continua recursivamente na cadeia de plataformas mãe. Dessa forma, todos os valores definidos diretamente em uma plataforma vão substituir os valores definidos no pai.

As plataformas herdam o atributo exec_properties da plataforma mãe. As entradas de dicionário em exec_properties das plataformas mãe e filha serão combinadas. Se a mesma chave aparecer nas exec_properties da mãe e da filha, o valor da filha será usado. Se a plataforma filha especificar uma string vazia como um valor, a propriedade correspondente será desdefinida.

As plataformas também podem herdar o atributo (obsoleto) remote_execution_properties da plataforma mãe. Observação: o novo código precisa usar exec_properties. A lógica descrita abaixo é mantida para ser compatível com o comportamento legado, mas será removida no futuro. A lógica para definir remote_execution_platform é a seguinte quando há uma plataforma mãe:

  1. Se remote_execution_property não estiver definido na plataforma filha, as remote_execution_properties da mãe serão usadas.
  2. Se remote_execution_property estiver definido na plataforma filha e contiver a string literal {PARENT_REMOTE_EXECUTION_PROPERTIES}, essa macro será substituída pelo conteúdo do atributo remote_execution_property da mãe.
  3. Se remote_execution_property estiver definido na plataforma filha e não contiver a macro, o remote_execution_property da filha será usado sem alterações.

Como remote_execution_properties está obsoleta e será descontinuada, não é permitido misturar remote_execution_properties e exec_properties na mesma cadeia de herança. Prefira usar exec_properties em vez de obsoletas remote_execution_properties.

Exemplo: valores de restrição

platform(
    name = "parent",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)
platform(
    name = "child_a",
    parents = [":parent"],
    constraint_values = [
        "@platforms//cpu:x86_64",
    ],
)
platform(
    name = "child_b",
    parents = [":parent"],
)

Neste exemplo, as plataformas filhas têm as seguintes propriedades:

  • child_a tem os valores de restrição @platforms//os:linux (herdado da mãe) e @platforms//cpu:x86_64 (definido diretamente na plataforma).
  • child_b herda todos os valores de restrição da mãe e não define nenhum próprio.

Exemplo: propriedades de execução

platform(
    name = "parent",
    exec_properties = {
      "k1": "v1",
      "k2": "v2",
    },
)
platform(
    name = "child_a",
    parents = [":parent"],
)
platform(
    name = "child_b",
    parents = [":parent"],
    exec_properties = {
      "k1": "child"
    }
)
platform(
    name = "child_c",
    parents = [":parent"],
    exec_properties = {
      "k1": ""
    }
)
platform(
    name = "child_d",
    parents = [":parent"],
    exec_properties = {
      "k3": "v3"
    }
)

Neste exemplo, as plataformas filhas têm as seguintes propriedades:

  • child_a herda as "exec_properties" da mãe e não define as próprias.
  • child_b herda o exec_properties da mãe e substitui o valor de k1. Seu exec_properties será: { "k1": "child", "k2": "v2" }.
  • child_c herda o exec_properties da mãe e desdefine k1. Seu exec_properties será: { "k2": "v2" }.
  • child_d herda o exec_properties da mãe e adiciona uma nova propriedade. Seu exec_properties será: { "k1": "v1", "k2": "v2", "k3": "v3" }.

Argumentos

Atributos
name

Nome; obrigatório

Um nome exclusivo para esse destino.
constraint_values

Lista de rótulos; não configurável; o padrão é []

A combinação de opções de restrição que essa plataforma compreende. Para que uma plataforma seja aplicada a um determinado ambiente, ele precisa ter pelo menos os valores nessa lista.

Cada constraint_value nessa lista precisa ser para um diferente constraint_setting. Por exemplo, não é possível definir uma plataforma que exige que a arquitetura da CPU seja @platforms//cpu:x86_64 e @platforms//cpu:arm.

exec_properties

Dicionário: string -> string; não configurável; o padrão é {}

Um mapa de strings que afetam a maneira como as ações são executadas remotamente. O Bazel não tenta interpretar isso. Ele é tratado como dados opacos encaminhados pelo campo "Platform" do protocolo de execução remota. Isso inclui todos os dados dos atributos exec_properties da plataforma mãe. Se a plataforma filha e mãe definirem as mesmas chaves, os valores da filha serão mantidos. Todas as chaves associadas a um valor que é uma string vazia são removidas do dicionário. Esse atributo é uma substituição completa para o obsoleto remote_execution_properties.
parents

Lista de rótulos; não configurável; o padrão é []

O rótulo de um destino platform do qual essa plataforma precisa herdar. Embora o atributo receba uma lista, não pode haver mais de uma plataforma presente. Todas as constraint_settings não definidas diretamente nessa plataforma serão encontradas na plataforma mãe. Consulte a seção sobre herança de plataforma para mais detalhes.
remote_execution_properties

String; não configurável; o padrão é ""

OBSOLETO. Use o atributo exec_properties. Uma string usada para configurar uma plataforma de execução remota. Os builds reais não tentam interpretar isso. Ele é tratado como dados opacos que podem ser usados por um SpawnRunner específico. Isso pode incluir dados do atributo "remote_execution_properties" da plataforma mãe, usando a macro "{PARENT_REMOTE_EXECUTION_PROPERTIES}". Consulte a seção sobre herança de plataforma para mais detalhes.

toolchain

Ver origem da regra 
toolchain(name, deprecation, distribs, exec_compatible_with, features, licenses, tags, target_compatible_with, target_settings, testonly, toolchain, toolchain_type, visibility)

Essa regra declara o tipo e as restrições de um conjunto de ferramentas específico para que ele possa ser selecionado durante a resolução do conjunto de ferramentas. Consulte a página Conjuntos de ferramentas para mais detalhes.

Argumentos

Atributos
name

Nome; obrigatório

Um nome exclusivo para esse destino.
exec_compatible_with

Lista de rótulos; não configurável; o padrão é []

Uma lista de constraint_values que precisam ser atendidas por uma plataforma de execução para que esse conjunto de ferramentas seja selecionado para um build de destino nessa plataforma.
target_compatible_with

Lista de rótulos; não configurável; o padrão é []

Uma lista de constraint_values que precisam ser atendidas pela plataforma segmentada para que esse conjunto de ferramentas seja selecionado para um build de destino para essa plataforma.
target_settings

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

Uma lista de config_settings que precisam ser atendidas pela configuração de destino para que esse conjunto de ferramentas seja selecionado durante a resolução do conjunto de ferramentas.
toolchain

Nome; obrigatório

O destino que representa a ferramenta ou o conjunto de ferramentas real disponibilizado quando esse conjunto de ferramentas é selecionado.
toolchain_type

Rótulo; não configurável; obrigatório

O rótulo de um destino toolchain_type que representa o papel que esse conjunto de ferramentas serve.

toolchain_type

Ver origem da regra 
toolchain_type(name, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

Essa regra define um novo tipo de conjunto de ferramentas: um destino simples que representa uma classe de ferramentas que servem a mesma função para diferentes plataformas.

Consulte a página Conjuntos de ferramentas para mais detalhes.

Exemplo

Isso define um tipo de conjunto de ferramentas para uma regra personalizada. 

toolchain_type(
    name = "bar_toolchain_type",
)

Isso pode ser usado em um arquivo bzl. 

bar_binary = rule(
    implementation = _bar_binary_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = True),
        ...
        # No `_compiler` attribute anymore.
    },
    toolchains = ["//bar_tools:toolchain_type"]
)

Argumentos

Atributos
name

Nome; obrigatório

Um nome exclusivo para esse destino.