As inscrições para a BazelCon 2024 já estão abertas.

Esta página foi traduzida pela API Cloud Translation.

Regras para plataformas e conjuntos de ferramentas

Report an issue View source Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Esse conjunto de regras permite que você modele plataformas de hardware específicas que está criando e especifique as ferramentas específicas que pode precisar para compilar o código para essas plataformas. O usuário precisa conhecer os conceitos explicados aqui.

constraint_setting

Acessar a 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 em que uma plataforma pode especificar um valor. Por exemplo, é possível definir um constraint_setting com o nome "glibc_version" para representar a capacidade de plataformas terem 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, elas são definidas no mesmo pacote, mas às vezes um pacote diferente introduz 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 com foco em uma arquitetura de CPU obscura.

Argumentos

Atributos

name

Nome: obrigatório

Um nome exclusivo para essa segmentação.

default_constraint_value

Nome: não configurável; o padrão é None

O rótulo do valor padrão para essa configuração, que será usado se nenhum valor for fornecido. Se esse atributo estiver presente, o constraint_value para o qual 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 nenhum valor de restrição para essa configuração, será como 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 como não especificada por essa plataforma. Nesse caso, a plataforma não corresponderia a nenhuma lista de restrições (como para um config_setting) que exige um valor específico para essa configuração.

constraint_value

Conferir a 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 página Plataformas.

Exemplo

O código 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",
)

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

Argumentos

Atributos

name

Nome: obrigatório

Um nome exclusivo para essa segmentação.

constraint_setting

Rótulo: não configurável; obrigatório

O constraint_setting para o qual este constraint_value é uma opção possível.

plataforma

Acessar a origem da regra

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, uma coleção nomeada de escolhas 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 de 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 pela plataforma têm a maior precedência e substituem qualquer valor anterior da flag, seja 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 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 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 configuração das flags da plataforma. Em vez disso, todos os valores anteriores serão removidos e substituídos pelos valores da plataforma.

Como exemplo, considerando a plataforma a seguir, a invocação build --platforms=//:repeat_demo --features feature_a --features feature_b vai resultar em ["feature_c", "feature_d"] como o valor da flag --feature, removendo os recursos definidos na linha de comando.

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

Por esse motivo, 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 elas vão herdar os valores de restrição. Embora o atributo parents receba uma lista, atualmente só é possível usar um único 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 elemento pai. Isso continua de maneira recursiva na cadeia de plataformas principais. Dessa forma, todos os valores definidos diretamente em uma plataforma vão substituir os valores definidos na plataforma pai.

As plataformas herdam o atributo exec_properties da plataforma mãe. As entradas do dicionário em exec_properties das plataformas pai e filho serão combinadas. Se a mesma chave aparecer na exec_properties da entidade pai e da filha, o valor da filha será usado. Se a plataforma filha especificar uma string vazia como um valor, a propriedade correspondente será redefinida.

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

Se remote_execution_property não estiver definido na plataforma filha, o remote_execution_properties da plataforma mãe será usado.
Se remote_execution_property estiver 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 da plataforma mãe.
Se remote_execution_property estiver definido na plataforma filha e não contiver a macro, o remote_execution_property da filha será usado sem alterações.

Como remote_execution_properties foi descontinuado e será removido, 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 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 (herdado do elemento pai) e @platforms//cpu:x86_64 (definido diretamente na plataforma).
child_b herda todos os valores de restrição do elemento 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 o "exec_properties" do elemento pai e não define o próprio.
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 define k1 como "unset". 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

Atributos
`name`	Nome: obrigatório Um nome exclusivo para essa segmentação.
`constraint_values`	Lista de rótulos; não configurável; o padrão é `[]` A combinação de opções de restrição que essa plataforma inclui. Para que uma plataforma seja aplicada a um determinado ambiente, ele precisa ter pelo menos os valores desta lista. Cada `constraint_value` na lista precisa ser para um `constraint_setting` diferente. Por exemplo, não é possível definir uma plataforma que exija que a arquitetura da CPU seja `@platforms//cpu:x86_64` e `@platforms//cpu:arm`.
`exec_properties`	Dicionário: String -> String; não configurável; o padrão é `{}` Um mapa de strings que afetam a forma como as ações são executadas remotamente. O Bazel não tenta interpretar isso. Ele é tratado como dados opacos que são encaminhados pelo campo Platform do protocolo de execução remota. Isso inclui todos os dados dos atributos `exec_properties` da plataforma mãe. Se a plataforma filha e a plataforma pai definirem as mesmas chaves, os valores da plataforma filha serão mantidos. Todas as chaves associadas a um valor que é uma string vazia são removidas do dicionário. Esse atributo substitui totalmente o `remote_execution_properties` descontinuado.
`flags`	Lista de strings não configuráveis; o padrão é `[]` Uma lista de flags que serão ativadas quando essa plataforma for usada como a plataforma de destino em uma configuração. Somente sinalizações que podem ser definidas em transições podem ser usadas.
`parents`	Lista de rótulos; não configurável; o padrão é `[]` O rótulo de um destino `platform` que essa plataforma precisa herdar. Embora o atributo receba uma lista, não pode haver mais de uma plataforma. Todas as constraint_settings que não forem definidas diretamente nesta plataforma serão encontradas na plataforma pai. Consulte a seção sobre Herança de plataforma para mais detalhes.
`remote_execution_properties`	String; não configurável; o padrão é `""` OBSOLETO. Use o atributo exec_properties. Uma string usada para configurar uma plataforma de execução remota. Os builds reais não tentam interpretar isso. Ele é tratado como dados opacos que podem ser usados por um SpawnRunner específico. Isso pode incluir dados do atributo "remote_execution_properties" da plataforma pai, usando a macro "{PARENT_REMOTE_EXECUTION_PROPERTIES}". Consulte a seção sobre Herança de plataforma para saber mais.
`required_settings`	Lista de rótulos; o padrão é `[]` Uma lista de `config_setting`s que precisam ser atendidos pela configuração de destino para que essa plataforma seja usada como uma plataforma de execução durante a resolução do conjunto de ferramentas. As configurações obrigatórias não são herdadas das plataformas mãe.

conjunto de ferramentas

Acessar a origem da regra

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

Atributos
`name`	Nome: obrigatório Um nome exclusivo para essa segmentação.
`exec_compatible_with`	Lista de rótulos; não configurável; o padrão é `[]` Uma lista de `constraint_value`s que precisam ser atendidos por uma plataforma de execução para que esse conjunto de ferramentas seja selecionado para um edifício de destino nessa plataforma.
`target_compatible_with`	Lista de rótulos; não configurável; o padrão é `[]` Uma lista de `constraint_value`s que precisam ser atendidos pela plataforma de destino para que esse conjunto de ferramentas seja selecionado para um build de destino para essa plataforma.
`target_settings`	Lista de rótulos; o padrão é `[]` Uma lista de `config_setting`s que precisam ser atendidos pela configuração de destino para que esse conjunto de ferramentas seja selecionado durante a resolução.
`toolchain`	Nome: obrigatório O destino que representa a ferramenta ou o conjunto de ferramentas real que é disponibilizado quando esse conjunto de ferramentas é selecionado.
`toolchain_type`	Rótulo: não configurável; obrigatório O rótulo de um destino `toolchain_type` que representa o papel que esse conjunto de ferramentas atende.

toolchain_type

Acessar a 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 toolchain, um destino simples que representa uma classe de ferramentas que desempenham a mesma função para diferentes plataformas.

Consulte a página Toolchains 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 essa segmentação.