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

Informar um problema Conferir origem 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 de que você pode precisar para compilar código para essas plataformas. O usuário precisa estar familiarizado com os conceitos explicados aqui.

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 uma 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, 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 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 à 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:

Se remote_execution_property não estiver definido na plataforma filha, o método remote_execution_properties será usado.
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.
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`:
`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.

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_value`s 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_value`s 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_setting`s 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.