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 uma constraint_setting com o nome "glibc_version" para representar as plataformas têm versões diferentes da biblioteca glibc instaladas. Para mais detalhes, consulte a Plataformas.

Cada constraint_setting tem um conjunto extensível de objetos constraint_value. Normalmente, eles são definidos no mesmo pacote, mas às vezes um um pacote diferente introduzirá novos valores para uma configuração existente. Por exemplo, o modelo predefinido a configuração @platforms//cpu:cpu pode ser estendida com um valor personalizado a fim de definir uma plataforma voltada para uma arquitetura de CPU obscura.

Argumentos

constraint_value

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

Exemplo

O código abaixo cria um novo valor possível para o constraint_value predefinido. que representam a arquitetura da CPU.

constraint_value(
    name = "mips",
    constraint_setting = "@platforms//cpu:cpu",
)

Argumentos

plataforma

platform(name, constraint_values, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, parents, remote_execution_properties, tags, testonly, visibility)

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

Exemplo

Isso define uma plataforma que descreve qualquer ambiente que execute o Linux no 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 à qual serão usadas herdam valores de restrição. Embora o atributo parents use uma lista, nenhum há suporte a mais de um 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 são definidos diretamente (pelo atributo constraint_values) são verificados e os valores de restrição o pai. Isso continua recursivamente na cadeia de plataformas pai. Dessa forma, qualquer os valores definidos diretamente em uma plataforma vão substituir os valores definidos no pai.

As plataformas herdam o atributo exec_properties da plataforma pai. As entradas do dicionário no exec_properties das plataformas mãe e filha serão combinados. Se a mesma chave aparecer nas exec_properties da mãe e da filha, o valor do filho será usado. Se a plataforma filha especificar uma string vazia como valor, o a propriedade correspondente não será definida.

As plataformas também podem herdar o atributo (descontinuado) remote_execution_properties da plataforma principal. Observação: o novo código precisa usar exec_properties. A 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 método remote_execution_properties será usado.
2. Se remote_execution_property estiver definido na plataforma filha e contiver o string literal {PARENT_REMOTE_EXECUTION_PROPERTIES}, essa macro será substituído pelo conteúdo do atributo remote_execution_property do elemento pai.
3. Se remote_execution_property estiver definido na plataforma filha e não contiver a macro, a remote_execution_property filha será usada sem alterações.

Como o uso de remote_execution_properties foi descontinuado e será desativado, a combinação remote_execution_properties e exec_properties na mesma cadeia de herança não permitida. Prefiro usar exec_properties em vez do descontinuado 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 (herdados do pai) e @platforms//cpu:x86_64 (definidos diretamente na plataforma).
• A child_b herda todos os valores de restrição do pai e não define nenhum por conta própria.

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 o próprio.
• O child_b herda o exec_properties do pai e substitui o de k1. A exec_properties será: { "k1": "child", "k2": "v2" }.
• child_c herda o exec_properties do pai e cancela a configuração k1 A exec_properties será: { "k2": "v2" }.
• O child_d herda o exec_properties do pai e adiciona um novo . A exec_properties será: { "k1": "v1", "k2": "v2", "k3": "v3" }.

Argumentos

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)

Esta 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 Conjuntos de ferramentas para mais informações detalhes.

Argumentos

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 desempenham o mesmo papel em plataformas diferentes.

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