Regras para plataformas e conjuntos de ferramentas

Esse conjunto de regras existe para permitir que você modele plataformas de hardware específicas às quais criar e especificar as ferramentas específicas que podem ser necessárias para compilar código para essas plataformas. O usuário precisa estar familiarizado com os conceitos explicados aqui.

Regras

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

constraint_setting

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, 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, 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_properties, features, flags, licenses, parents, remote_execution_properties, required_settings, 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 página 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",
    ],
)

Sinalizações da plataforma

As plataformas podem usar o atributo flags para especificar uma lista de sinalizações que serão adicionadas. à configuração sempre que a plataforma for usada como a plataforma de destino (ou seja, como o valor de a sinalização --platforms).

As flags definidas da plataforma têm precedência e substituem as sinalizações anteriores para essa sinalização, na linha de comando, no arquivo rc ou na transição.

Exemplo

platform(
    name = "foo",
    flags = [
        "--dynamic_mode=fully",
        "--//bool_flag",
        "--no//package:other_bool_flag",
    ],
)

Isso define uma plataforma chamada foo. Quando esta é a plataforma de destino (porque o usuário especificou --platforms//:foo, porque uma transição definiu o //command_line_option:platforms para ["//:foo"] ou porque //:foo foi usada como plataforma de execução), então as sinalizações fornecidas serão definidas no configuração do Terraform.

Plataformas e sinalizações repetíveis

Algumas sinalizações acumulam valores quando são repetidas, como --features, --copt, qualquer flag Starlark criada como config.string(repeatable = True). Essas sinalizações não são compatíveis com a configuração das sinalizações da plataforma. Em vez disso, todas as sinalizações anteriores serão removidos e substituídos pelos valores da plataforma.

Por exemplo, considerando a plataforma a seguir, a invocação build --platforms=//:repeat_demo --features feature_a --features feature_b terminará com o valor do Sinalização --feature sendo ["feature_c", "feature_d"], removendo os recursos é definido na linha de comando.

platform(
    name = "repeat_demo",
    flags = [
        "--features=feature_c",
        "--features=feature_d",
    ],
)

Por esse motivo, não é recomendável usar sinalizações repetíveis no atributo flags.

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, 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