Regras para plataformas e conjuntos de ferramentas

Informar um problema Mostrar fonte Por noite · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

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

Conferir origem da regra
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

Atributos
name

Nome; obrigatório

Um nome exclusivo para o destino.

default_constraint_value

Nome; nonconfigurable; o padrão é None

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

Conferir origem da regra
constraint_value(name, constraint_setting, deprecation, distribs, 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

Nome; obrigatório

Um nome exclusivo para o destino.

constraint_setting

Rótulo nonconfigurable; obrigatório

O constraint_setting para o qual esse constraint_value é um possível.

plataforma

Conferir origem da regra
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

Atributos
name

Nome; obrigatório

Um nome exclusivo para o destino.

constraint_values

Lista de rótulos nonconfigurable; o padrão é []

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

Dicionário: String -> String; nonconfigurable; o padrão é {}

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:
flags

Lista de strings nonconfigurable; o padrão é []

Uma lista de sinalizações que serão ativadas quando esta plataforma for usada como plataforma de destino em uma configuração. Somente as flags que podem ser definidas em transições podem ser usadas.
parents

Lista de rótulos nonconfigurable; o padrão é []

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; nonconfigurable; o padrão é ""

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.
required_settings

Lista de rótulos o padrão é []

Uma lista de config_settings que precisam ser atendidas pela configuração de destino. para que essa plataforma seja usada como plataforma de execução durante a resolução do conjunto de ferramentas. As configurações necessárias não são herdadas das plataformas mãe.

conjunto de ferramentas

Conferir origem da regra
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

Atributos
name

Nome; obrigatório

Um nome exclusivo para o destino.

exec_compatible_with

Lista de rótulos nonconfigurable; o padrão é []

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

Lista de rótulos nonconfigurable; o padrão é []

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

Lista de rótulos o padrão é []

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

Nome; obrigatório

O destino que representa as ferramentas ou o conjunto de ferramentas disponibilizado quando essa é selecionado.
toolchain_type

Rótulo nonconfigurable; obrigatório

O rótulo de um destino toolchain_type que representa o papel desse conjunto de ferramentas é veiculado.

toolchain_type

Conferir origem da regra
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

Nome; obrigatório

Um nome exclusivo para o destino.