Regras da plataforma

Regras

• constraint_setting
• constraint_value
• plataforma
• conjunto de ferramentas
• toolchain_type

constraint_setting

constraint_setting(name, default_constraint_value, deprecation, distribs, exec_compatible_with, exec_properties, 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, defina 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. Em geral, eles são definidos no mesmo pacote, mas, às vezes, um pacote diferente introduz novos valores em uma configuração atual. Por exemplo, a configuração predefinida @platforms//cpu:cpu pode ser estendida com um valor personalizado para definir uma plataforma direcionada a uma arquitetura de CPU pouco conhecida.

Argumentos

Atributos
name	Name; required Um nome exclusivo para o destino.
default_constraint_value	Name; optional; nonconfigurable O rótulo do valor padrão desta configuração, a ser usado se nenhum valor for atribuído. Se este atributo estiver presente, o constraint_value para o qual ele aponta precisa ser definido no mesmo pacote que esse constraint_setting. Se uma configuração de restrição tiver um valor padrão, sempre que uma plataforma não incluir um valor de restrição para essa configuração, será como se a plataforma tivesse especificado o valor padrão. Caso contrário, se não houver 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 exija um valor específico para essa configuração.

constraint_value

constraint_value(name, constraint_setting, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, tags, testonly, visibility)

Esta regra introduz um novo valor para um determinado tipo de restrição. Para mais detalhes, consulte a página Plataformas.

Exemplo

O código 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	Name; required Um nome exclusivo para o destino.
constraint_setting	Label; required; nonconfigurable A constraint_setting para a qual esse constraint_value é uma opção possível.

plataforma

platform(name, constraint_values, deprecation, distribs, exec_compatible_with, 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

Define uma plataforma que descreve qualquer ambiente que executa Linux em ARM.

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

Herança da plataforma

As plataformas podem usar o atributo parents para especificar outra plataforma da qual herdarão valores de restrição. Embora o atributo parents use uma lista, no momento não há suporte para mais do que um único valor, 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 (por meio do atributo constraint_values) são verificados e, em seguida, os valores de restrição no pai. Isso continua sendo recorrente 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 do dicionário em exec_properties das plataformas pai e filho serão combinadas. Se a mesma chave aparecer no exec_properties do pai e do filho, o valor do filho será usado. Se a plataforma filha especificar uma string vazia como valor, a propriedade correspondente não será definida.

As plataformas também podem herdar o atributo remote_execution_properties (descontinuado) 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 o remote_execution_platform é a seguinte quando há uma plataforma mãe:

1. Se remote_execution_property não estiver definido na plataforma filha, o remote_execution_properties do pai vai ser usado.
2. Se remote_execution_property for 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 do pai.
3. Se remote_execution_property for definido na plataforma filha e não contiver a macro, o remote_execution_property do filho será usado sem mudanças.

Como remote_execution_properties foi descontinuado e será descontinuado, não é permitido misturar remote_execution_properties e exec_properties na mesma cadeia de herança. Prefira usar exec_properties em vez do remote_execution_properties descontinuado

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 (herdados do pai) e @platforms//cpu:x86_64 (definidos diretamente na plataforma).
• child_b herda todos os valores de restrição do pai 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" do pai e não define as próprias.
• child_b herda o exec_properties do pai e substitui o valor de k1. O exec_properties vai ser: { "k1": "child", "k2": "v2" }.
• child_c herda a exec_properties do pai e cancela a definição de k1. O exec_properties vai ser: { "k2": "v2" }.
• child_d herda a exec_properties do pai e adiciona uma nova propriedade. O exec_properties vai ser: { "k1": "v1", "k2": "v2", "k3": "v3" }.

Argumentos

Atributos
name	Name; required Um nome exclusivo para o destino.
constraint_values	List of labels; optional A combinação de opções de restrição abrangida por esta plataforma. Para que uma plataforma seja aplicada a um determinado ambiente, o ambiente precisa ter pelo menos os valores desta lista. Cada constraint_value nesta lista precisa ser para um constraint_setting diferente. Por exemplo, não é possível definir uma plataforma que exija que a arquitetura da CPU seja @platforms//cpu:x86_64 e @platforms//cpu:arm.
exec_properties	Dictionary: String -> String; optional Um mapa de strings que afetam a forma 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 a plataforma pai definirem as mesmas chaves, os valores do filho 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 do remote_execution_properties descontinuado.
parents	List of labels; optional O rótulo de um destino platform de que a plataforma precisa herdar. Embora o atributo ocupe uma lista, não pode haver mais de uma plataforma presente. Todas as constraints_settings não definidas diretamente nesta plataforma serão encontradas na plataforma pai. Consulte a seção Herança de plataformas para saber mais.
remote_execution_properties	String; optional OBSOLETO. Use o atributo exec_properties. Uma string usada para configurar uma plataforma de execução remota. Builds reais não tentam interpretar isso. Eles são tratados como dados opacos que podem ser usados por um SpawnRunner específico. Isso pode incluir dados do atributo "remote_execution_properties" da plataforma pai, usando a macro "{PARENT_REMOTE_EXECUTION_PROPERTIES}". Consulte a seção sobre Herança de plataformas para saber mais detalhes.

conjunto de ferramentas

toolchain(name, deprecation, distribs, exec_compatible_with, exec_properties, 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 ver mais detalhes.

Argumentos

Atributos
name	Name; required Um nome exclusivo para o destino.
exec_compatible_with	List of labels; optional; nonconfigurable 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	List of labels; optional; nonconfigurable Uma lista de constraint_values que precisam ser atendidas pela plataforma de destino para que esse conjunto de ferramentas seja selecionado para uma compilação de destino para essa plataforma.
target_settings	List of labels; optional 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 dele.
toolchain	Name; required O destino que representa a ferramenta ou o conjunto de ferramentas real disponibilizado quando esse conjunto de ferramentas é selecionado.
toolchain_type	Label; required; nonconfigurable O rótulo de um destino toolchain_type que representa o papel que esse conjunto de ferramentas atende.

toolchain_type

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 atendem ao mesmo papel em diferentes plataformas.

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

Exemplo

Define um tipo de conjunto de ferramentas para uma regra personalizada.

toolchain_type(
    name = "bar_toolchain_type",
)

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	Name; required Um nome exclusivo para o destino.