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

Atributos
name	Name; required Um nome exclusivo para o destino.
default_constraint_value	Name; optional; nonconfigurable O rótulo do valor padrão dessa configuração, que será usado se nenhum valor for fornecido. Se esse estiver presente, o constraint_value que ele aponta precisa ser definido no mesmo pacote que este constraint_setting. Se uma configuração de restrição tiver um valor padrão, sempre que uma plataforma não incluir qualquer valor de restrição para essa configuração, é o mesmo que se a plataforma tivesse especificado o valor padrão. Caso contrário, se não houver um valor padrão, a configuração de restrição será considerada não especificado por essa plataforma. Nesse caso, a plataforma não corresponderia a nenhum lista de restrições (como para uma config_setting) que exige 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)

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

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

As plataformas podem declarar que têm a arquitetura mips como alternativa x86_64, arm e assim por diante.

Argumentos

Atributos
name	Name; required Um nome exclusivo para o destino.
constraint_setting	Label; required; nonconfigurable O constraint_setting para o qual esse constraint_value é um possível.

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

Atributos
name	Name; required Um nome exclusivo para o destino.
constraint_values	List of labels; optional Combinação de opções de restrição que essa plataforma compreende. Para que uma plataforma para aplicar a um determinado ambiente, ele precisa ter pelo menos os valores da lista. Cada constraint_value nesta lista precisa ser para um constraint_setting. Por exemplo, não é possível definir uma plataforma que exija o arquitetura de CPU como @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 faz nenhuma tentativa para interpretar isso, eles são tratados como dados opacos que são encaminhados por meio do campo Plataforma de o protocolo de execução remota. Isso inclui todos os dados dos atributos exec_properties da plataforma mãe. Se as plataformas mãe e filha definirem as mesmas chaves, os valores da filha serão mantidos. Qualquer um as chaves associadas a um valor que seja uma string vazia são removidas do dicionário. Este atributo é uma substituição completa para o remote_execution_properties:
parents	List of labels; optional O rótulo de um destino platform do qual esta plataforma deve herdar. Embora o atributo recebe uma lista, não deve haver mais de uma plataforma presente. Qualquer um restrição_settings não definida diretamente nesta plataforma será encontrada na plataforma pai. Consulte a seção sobre Herança da plataforma para mais detalhes.
remote_execution_properties	String; optional OBSOLETO. Em vez disso, use o atributo "exec_properties". Uma string usada para configurar uma plataforma de execução remota. Os builds reais não tentam interpretar isso, eles serão tratados como dados opacos que podem ser usados por um SpawnRunner específico. Isso pode incluir dados das "remote_execution_properties" da plataforma pai atributo, usando a macro "{PARENT_REMOTE_EXECUTION_PROPERTIES}". Consulte a seção sobre Herança da plataforma para 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)

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

Atributos
name	Name; required Um nome exclusivo para o destino.
exec_compatible_with	List of labels; optional; nonconfigurable Uma lista de constraint_values que precisa ser satisfeita por uma plataforma de execução em para que esse conjunto de ferramentas seja selecionado para uma compilação 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 em para que esse conjunto de ferramentas seja selecionado para uma compilação de destino dessa 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 as ferramentas ou o conjunto de ferramentas disponibilizado quando essa é selecionado.
toolchain_type	Label; required; nonconfigurable O rótulo de um destino toolchain_type que representa o papel desse conjunto de ferramentas é veiculado.

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

Atributos
name	Name; required Um nome exclusivo para o destino.