O Bazel pode criar e testar códigos em vários hardwares, sistemas operacionais e configurações do sistema, usando muitas versões diferentes de ferramentas de build, como linkers e compiladores. Para ajudar a gerenciar essa complexidade, o Bazel tem um conceito de restrições e plataformas. Uma restrição é uma dimensão em que os ambientes de criação ou produção podem ser diferentes, como arquitetura da CPU, a presença ou ausência de uma GPU ou a versão de um compilador instalado pelo sistema. Uma plataforma é uma coleção nomeada de escolhas para essas restrições, representando os recursos específicos disponíveis em algum ambiente.
A modelagem do ambiente como uma plataforma ajuda o Bazel a selecionar automaticamente os conjuntos de ferramentas adequados para ações de build. As plataformas também podem ser usadas em combinação com a regra config_setting para gravar atributos configuráveis.
O Bazel reconhece três papéis que uma plataforma pode ter:
- Host: a plataforma em que o Bazel é executado.
- Execution: uma plataforma em que as ferramentas de build executam ações de build para produzir saídas intermediárias e finais.
- Destino: uma plataforma em que uma saída final reside e é executada.
O Bazel oferece suporte aos seguintes cenários de build relacionados a plataformas:
Builds de plataforma única (padrão): as plataformas de execução, de destino e host são as mesmas. Por exemplo, criar um executável Linux no Ubuntu em execução em uma CPU Intel x64.
Builds de compilação cruzada: as plataformas host e de execução são as mesmas, mas a plataforma de destino é diferente. Por exemplo, criar um app iOS no macOS executando em um MacBook Pro.
Builds multiplataforma: as plataformas de host, de execução e de destino são diferentes.
Como definir restrições e plataformas
O espaço de opções possíveis para plataformas é definido usando as regras
constraint_setting
e
constraint_value
nos arquivos BUILD
.
constraint_setting
cria uma nova dimensão, enquanto
constraint_value
cria um novo valor para uma determinada dimensão. Juntos, eles
definem efetivamente um tipo enumerado e os valores possíveis. Por exemplo, o snippet
abaixo de um arquivo BUILD
introduz uma restrição para a versão glibc do sistema
com dois valores possíveis.
constraint_setting(name = "glibc_version")
constraint_value(
name = "glibc_2_25",
constraint_setting = ":glibc_version",
)
constraint_value(
name = "glibc_2_26",
constraint_setting = ":glibc_version",
)
As restrições e os valores delas podem ser definidos em diferentes pacotes no ambiente de trabalho. Eles são referenciados por rótulo e estão sujeitos aos controles de visibilidade comuns. Se a visibilidade permitir, você poderá estender uma configuração de restrição existente definindo seu próprio valor para ela.
A regra platform
apresenta uma nova plataforma com
certas opções de valores de restrição. O exemplo
a seguir cria uma plataforma chamada linux_x86
e diz que ela descreve qualquer
ambiente que executa um sistema operacional Linux em uma arquitetura x86_64 com uma
versão da glibc de 2.25. Confira abaixo mais informações sobre as restrições integradas do Bazel.
platform(
name = "linux_x86",
constraint_values = [
"@platforms//os:linux",
"@platforms//cpu:x86_64",
":glibc_2_25",
],
)
Restrições e plataformas geralmente úteis
Para manter a consistência do ecossistema, a equipe do Bazel mantém um repositório com definições de restrição para as arquiteturas de CPU e os sistemas operacionais mais conhecidos. Eles estão todos localizados em https://github.com/bazelbuild/platforms.
O Bazel é enviado com a seguinte definição de plataforma especial:
@platforms//host
(com alias como @bazel_tools//tools:host_platform
). Esse é o
valor da plataforma host detectado automaticamente e
representa a plataforma detectada automaticamente no sistema em que o Bazel está sendo executado.
Como especificar uma plataforma para um build
É possível especificar as plataformas de destino e de host para um build usando as seguintes sinalizações de linha de comando:
--host_platform
: padrão@bazel_tools//tools:host_platform
- Esse destino tem o alias
@platforms//host
, que é apoiado por uma regra de repositório que detecta o SO e a CPU do host e grava o destino da plataforma. - Há também
@platforms//host:constraints.bzl
, que expõe uma matriz chamadaHOST_CONSTRAINTS
, que pode ser usada em outros arquivos BUILD e Starlark.
- Esse destino tem o alias
--platforms
: padrão da plataforma host- Isso significa que, quando nenhuma outra flag é definida,
@platforms//host
é a plataforma de destino. - Se
--host_platform
for definido e não--platforms
, o valor de--host_platform
será a plataforma de destino e de origem.
- Isso significa que, quando nenhuma outra flag é definida,
Ignorar destinos incompatíveis
Ao criar para uma plataforma de destino específica, muitas vezes é desejável pular destinos que nunca funcionarão nessa plataforma. Por exemplo, o driver do dispositivo
Windows provavelmente vai gerar muitos erros de compilador ao criar em uma
máquina Linux com //...
. Use o atributo
target_compatible_with
para informar ao Bazel quais restrições de plataforma de destino seu código tem.
O uso mais simples desse atributo restringe uma segmentação a uma única plataforma.
O destino não será criado para nenhuma plataforma que não atenda a todas as
restrições. O exemplo a seguir restringe o win_driver_lib.cc
ao Windows de
64 bits.
cc_library(
name = "win_driver_lib",
srcs = ["win_driver_lib.cc"],
target_compatible_with = [
"@platforms//cpu:x86_64",
"@platforms//os:windows",
],
)
:win_driver_lib
é compatível apenas para criação com o Windows de 64 bits e
incompatível com todo o restante. A incompatibilidade é transitiva. Qualquer destino
que dependa transitivamente de um destino incompatível é considerado
incompatível.
Quando as segmentações são puladas?
Os destinos são ignorados quando são considerados incompatíveis e incluídos no build como parte de uma expansão de padrão de destino. Por exemplo, as duas invocações a seguir pulam todos os destinos incompatíveis encontrados em uma expansão de padrão de destino.
$ bazel build --platforms=//:myplatform //...
$ bazel build --platforms=//:myplatform //:all
Testes incompatíveis em um test_suite
são
ignorados da mesma forma se o test_suite
for especificado na linha de comando com
--expand_test_suites
.
Em outras palavras, os destinos test_suite
na linha de comando se comportam como :all
e
...
. O uso de --noexpand_test_suites
impede a expansão e faz com que
alvos test_suite
com testes incompatíveis também sejam incompatíveis.
Especificar explicitamente um destino incompatível na linha de comando resulta em uma mensagem de erro e uma criação com falha.
$ bazel build --platforms=//:myplatform //:target_incompatible_with_myplatform
...
ERROR: Target //:target_incompatible_with_myplatform is incompatible and cannot be built, but was explicitly requested.
...
FAILED: Build did NOT complete successfully
Destinos explícitos incompatíveis são ignorados silenciosamente se
--skip_incompatible_explicit_targets
estiver ativado.
Restrições mais expressivas
Para mais flexibilidade na expressão de restrições, use o
@platforms//:incompatible
constraint_value
que nenhuma plataforma atende.
Use select()
em combinação com
@platforms//:incompatible
para expressar restrições mais complicadas. Por
exemplo, use-o para implementar a lógica OR básica. O exemplo a seguir marca uma biblioteca
compatível com macOS e Linux, mas não com outras plataformas.
cc_library(
name = "unixish_lib",
srcs = ["unixish_lib.cc"],
target_compatible_with = select({
"@platforms//os:osx": [],
"@platforms//os:linux": [],
"//conditions:default": ["@platforms//:incompatible"],
}),
)
O exemplo acima pode ser interpretado da seguinte forma:
- Ao segmentar o macOS, o destino não tem restrições.
- Ao segmentar o Linux, o destino não tem restrições.
- Caso contrário, o destino terá a restrição
@platforms//:incompatible
. Como@platforms//:incompatible
não faz parte de nenhuma plataforma, o destino é considerado incompatível.
Para tornar as restrições mais legíveis, use
selects.with_or()
da
skylib.
A compatibilidade inversa pode ser expressa de maneira semelhante. O exemplo a seguir descreve uma biblioteca compatível com tudo, exceto para ARM.
cc_library(
name = "non_arm_lib",
srcs = ["non_arm_lib.cc"],
target_compatible_with = select({
"@platforms//cpu:arm": ["@platforms//:incompatible"],
"//conditions:default": [],
}),
)
Como detectar segmentos incompatíveis usando bazel cquery
É possível usar o
IncompatiblePlatformProvider
no formato de saída
Starlark do bazel cquery
para distinguir
destinos incompatíveis dos compatíveis.
Isso pode ser usado para filtrar segmentos incompatíveis. O exemplo abaixo imprime apenas os rótulos de destinos compatíveis. Destinos incompatíveis não são impressos.
$ cat example.cquery
def format(target):
if "IncompatiblePlatformProvider" not in providers(target):
return target.label
return ""
$ bazel cquery //... --output=starlark --starlark:file=example.cquery
Problemas conhecidos
Os segmentos incompatíveis ignoram as restrições de visibilidade.