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 regraconstraint_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 é 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 |
constraint_value
Conferir origem da regraconstraint_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 Oconstraint_setting para o qual esse constraint_value é um
possível.
|
plataforma
Conferir origem da regraplatform(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
. O
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étodoremote_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 atributoremote_execution_property
do elemento pai. -
Se
remote_execution_property
estiver definido na plataforma filha e não contiver a macro, aremote_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 oexec_properties
do pai e substitui o dek1
. Aexec_properties
será:{ "k1": "child", "k2": "v2" }
. -
child_c
herda oexec_properties
do pai e cancela a configuraçãok1
Aexec_properties
será:{ "k2": "v2" }
. -
O
child_d
herda oexec_properties
do pai e adiciona um novo . Aexec_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 é Cada |
exec_properties
|
Dicionário: String -> String; nonconfigurable; o padrão é 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 é |
parents
|
Lista de rótulos nonconfigurable; o padrão é 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 é |
required_settings
|
Lista de rótulos o padrão é config_setting s 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 regratoolchain(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 é 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 é 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 é 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 destinotoolchain_type que representa o papel desse
conjunto de ferramentas é veiculado.
|
toolchain_type
Conferir origem da regratoolchain_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. |