Plataformas

7.3 · 7.2 · 7.1 · 7.0 · 6.5

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.

Dica: para instruções detalhadas sobre como migrar seu projeto para plataformas, consulte Migrar para plataformas.

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",
    ],
)

Observação: é um erro uma plataforma especificar mais de um valor da mesma configuração de restrição, como @platforms//cpu:x86_64 e @platforms//cpu:arm para @platforms//cpu:cpu.

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 chamada HOST_CONSTRAINTS, que pode ser usada em outros arquivos BUILD e Starlark.
• --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.

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.

Observação: uma lista de restrições vazia é equivalente a "compatível com tudo".

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:

1. Ao segmentar o macOS, o destino não tem restrições.
2. Ao segmentar o Linux, o destino não tem restrições.
3. 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.