Regras para plataformas e conjuntos de ferramentas

Esse conjunto de regras existe para permitir que você modele plataformas de hardware específicas para as quais você está criando e especifique 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 um constraint_setting chamado "glibc_version" para representar a capacidade que as plataformas têm 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. Normalmente, eles são definidos no mesmo pacote, mas às vezes um pacote diferente introduz novos valores para 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 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 representa a arquitetura de CPU.

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

Argumentos

platform [plataforma]

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 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 de onde herdarão valores de restrição. Embora o atributo parents use uma lista, no momento não é possível usar 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 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 pai. Dessa forma, os valores definidos diretamente em uma plataforma vão substituir aqueles 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 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 pai. 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 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, a remote_execution_property filha será usada inalterada.

Como remote_execution_properties foi descontinuado e será desativado, 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 será: { "k1": "child", "k2": "v2" }.
• child_c herda o exec_properties do pai e cancela a configuração de k1. O exec_properties será: { "k2": "v2" }.
• child_d herda o exec_properties do pai e adiciona uma nova propriedade. O 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)

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. Consulte a página Conjuntos de ferramentas para mais 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 que têm a mesma função 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