Regras para plataformas e conjuntos de ferramentas

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

Regras

• constraint_setting
• constraint_value
• plataforma
• toolchain
• 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, é 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. Normalmente, eles são definidos no mesmo pacote, mas às vezes um pacote diferente vai introduzir 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 segmentando uma arquitetura de CPU obscura.

Argumentos

constraint_value

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

Exemplo

O comando 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",
)

Argumentos

plataforma

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

Essa regra define uma nova plataforma, que é 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",
    ],
)

Flags da plataforma

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

As flags definidas na plataforma têm a maior precedência e substituem qualquer valor anterior para essa flag, seja da linha de comando, do arquivo rc ou da transição.

Exemplo

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

Isso define uma plataforma chamada foo. Quando essa é a plataforma de destino (porque o usuário especificou --platforms//:foo, porque uma transição definiu a flag //command_line_option:platforms como ["//:foo"] ou porque //:foo foi usado como uma plataforma de execução), as flags fornecidas serão definidas na configuração.

Plataformas e flags repetíveis

Algumas flags acumulam valores quando são repetidas, como --features, --copt e qualquer flag do Starlark criada como config.string(repeatable = True). Essas flags não são compatíveis com a definição de flags da plataforma. Em vez disso, todos os valores 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 vai resultar no valor da flag --feature sendo ["feature_c", "feature_d"], removendo os recursos definidos na linha de comando.

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

Por isso, não é recomendável usar flags repetíveis no atributo flags.

Herança de plataforma

As plataformas podem usar o atributo parents para especificar outra plataforma de que vão herdar valores de restrição. Embora o atributo parents receba uma lista, no momento, apenas um valor é aceito, e especificar vários elementos principais é 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 elemento pai. Isso continua de forma recursiva na cadeia de plataformas principais. Dessa forma, todos os valores definidos diretamente em uma plataforma vão substituir os valores definidos no elemento 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 no exec_properties do pai e do filho, o valor do filho será usado. Se a plataforma secundária especificar uma string vazia como valor, a propriedade correspondente será desdefinida.

As plataformas também podem herdar o atributo remote_execution_properties (descontinuado) da plataforma principal. Observação: o novo código deve 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 principal:

1. Se remote_execution_property não estiver definido na plataforma secundária, o remote_execution_properties da plataforma principal será usado.
2. Se remote_execution_property estiver definido na plataforma infantil 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 estiver definido na plataforma infantil e não contiver a macro, o remote_execution_property da criança será usado sem alterações.

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 de remote_execution_properties, que está 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 secundárias têm as seguintes propriedades:

• child_a tem os valores de restrição @platforms//os:linux (herdados do elemento pai) e @platforms//cpu:x86_64 (definidos diretamente na plataforma).
• child_b herda todos os valores de restrição do elemento pai e não define nenhum dos próprios.

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 secundárias têm as seguintes propriedades:

• child_a herda as "exec_properties" do elemento principal e não define as próprias.
• child_b herda o exec_properties do elemento pai e substitui o valor de k1. O exec_properties será: { "k1": "child", "k2": "v2" }.
• child_c herda o exec_properties do elemento pai e desativa k1. O exec_properties será: { "k2": "v2" }.
• child_d herda o exec_properties do elemento 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 do conjunto de ferramentas. Consulte a página Toolchains 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 cadeia de ferramentas: um destino simples que representa uma classe de ferramentas que desempenham a mesma função em diferentes plataformas.

Consulte a página Toolchains para mais detalhes.

Exemplo

Isso define um tipo de cadeia 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