Configuração do conjunto de ferramentas C++

Visão geral

Para invocar o compilador com as opções corretas, o Bazel precisa de algum conhecimento sobre as partes internas do compilador, como diretórios de inclusão e flags importantes. Em outras palavras, o Bazel precisa de um modelo simplificado do compilador para entender o funcionamento dele.

O Bazel precisa saber o seguinte:

• Se o compilador oferece suporte a thinLTO, módulos, vinculação dinâmica ou PIC (código independente de posição).
• Caminhos para as ferramentas necessárias, como gcc, ld, ar, objcopy e assim por diante.
• O sistema integrado inclui diretórios. O Bazel precisa deles para validar que todos os cabeçalhos incluídos no arquivo de origem foram declarados corretamente no arquivo BUILD.
• O sysroot padrão.
• Quais flags usar para compilação, vinculação e arquivamento.
• Quais flags usar para os modos de compilação com suporte (opt, dbg, fastbuild).
• Fazer com que as variáveis sejam especificamente exigidas pelo compilador.

Se o compilador tiver suporte a várias arquiteturas, o Bazel precisará configurá-las separadamente.

CcToolchainConfigInfo é um provedor que fornece o nível necessário de granularidade para configurar o comportamento das regras C++ do Bazel. Por padrão, o Bazel configura automaticamente CcToolchainConfigInfo para o build, mas você pode fazer isso manualmente. Para isso, você precisa de uma regra do Starlark que forneça o CcToolchainConfigInfo e apontar o atributo toolchain_config do cc_toolchain para a regra. É possível criar o CcToolchainConfigInfo chamando cc_common.create_cc_toolchain_config_info(). Você pode encontrar construtores do Starlark para todas as estruturas necessárias no processo em @rules_cc//cc:cc_toolchain_config_lib.bzl.

Quando um destino C++ entra na fase de análise, o Bazel seleciona o destino cc_toolchain apropriado com base no arquivo BUILD e extrai o provedor CcToolchainConfigInfo do destino especificado no atributo cc_toolchain.toolchain_config. O destino cc_toolchain transmite essas informações ao destino C++ por meio de um CcToolchainProvider.

Por exemplo, uma ação de compilação ou vinculação, instanciada por uma regra como cc_binary ou cc_library, precisa das seguintes informações:

• O compilador ou vinculador a ser usado
• Flags de linha de comando para o compilador/linker
• Flags de configuração transmitidas pelas opções --copt/--linkopt
• Variáveis de ambiente
• Artefatos necessários no sandbox em que a ação é executada

Todas as informações acima, exceto os artefatos necessários no sandbox, são especificadas no destino do Starlark para o qual o cc_toolchain aponta.

Os artefatos a serem enviados para o sandbox são declarados no destino cc_toolchain. Por exemplo, com o atributo cc_toolchain.linker_files, é possível especificar as bibliotecas de toolchain e o binário do vinculador para enviar para o sandbox.

Seleção de conjunto de ferramentas

A lógica de seleção da cadeia de ferramentas funciona da seguinte maneira:

1. O usuário especifica um destino cc_toolchain_suite no arquivo BUILD e aponta o Bazel para o destino usando a opção --crosstool_top.

2. O destino cc_toolchain_suite faz referência a várias cadeias de ferramentas. Os valores das flags --cpu e --compiler determinam qual das toolchains é selecionada, seja com base apenas no valor da flag --cpu ou com base em um valor --cpu | --compiler conjunto. O processo de seleção é o seguinte:

   • Se a opção --compiler for especificada, o Bazel vai selecionar a entrada correspondente do atributo cc_toolchain_suite.toolchains com --cpu | --compiler. Se o Bazel não encontrar uma entrada correspondente, ele vai gerar um erro.

   • Se a opção --compiler não for especificada, o Bazel vai selecionar a entrada correspondente do atributo cc_toolchain_suite.toolchains com apenas --cpu.

   • Se nenhuma flag for especificada, o Bazel vai inspecionar o sistema host e selecionar um valor --cpu com base nas descobertas. Consulte o código do mecanismo de inspeção.

Depois que uma cadeia de ferramentas é selecionada, os objetos feature e action_config correspondentes na regra Starlark governam a configuração do build, ou seja, os itens descritos mais adiante. Essas mensagens permitem a implementação de recursos completos do C++ no Bazel sem modificar o binário do Bazel. As regras do C++ oferecem suporte a várias ações exclusivas documentadas em detalhes no código-fonte do Bazel.

Recursos

Um recurso é uma entidade que exige sinalizações de linha de comando, ações, restrições no ambiente de execução ou alterações de dependência. Um recurso pode ser algo tão simples quanto permitir que arquivos BUILD selecionem configurações de flags, como treat_warnings_as_errors, ou interajam com as regras C++ e incluam novas ações de compilação e entradas na compilação, como header_modules ou thin_lto.

O ideal é que CcToolchainConfigInfo contenha uma lista de recursos, em que cada recurso consiste em um ou mais grupos de flags, cada um definindo uma lista de flags que se aplicam a ações específicas do Bazel.

Um recurso é especificado por nome, o que permite o desacoplamento completo da configuração de regra do Starlark das versões do Bazel. Em outras palavras, uma versão do Bazel não afeta o comportamento das configurações CcToolchainConfigInfo, desde que essas configurações não exijam o uso de novos recursos.

Um recurso é ativado de uma das seguintes maneiras:

• O campo enabled do recurso está definido como true.
• O Bazel ou o proprietário da regra precisa ativar a regra explicitamente.
• O usuário ativa essa opção usando a opção --feature do Bazel ou o atributo de regra features.

Os recursos podem ter interdependências, depender de sinalizações de linha de comando, configurações de arquivo BUILD e outras variáveis.

Relações de recursos

As dependências geralmente são gerenciadas diretamente com o Bazel, que simplesmente aplica os requisitos e gerencia conflitos intrínsecos à natureza dos recursos definidos no build. A especificação da cadeia de ferramentas permite restrições mais granulares para uso direto na regra do Starlark que governa o suporte e a expansão do recurso. São eles:

requires = [
   feature_set (features = [
       'feature-name-1',
       'feature-name-2'
   ]),
]

implies = ['feature']

provides = ['feature']

with_features = [
  with_feature_set(
    features = ['feature-1'],
    not_features = ['feature-2'],
  ),
]

Ações

As ações oferecem a flexibilidade para modificar as circunstâncias em que uma ação é executada sem presumir como ela será executada. Um action_config especifica o binário da ferramenta que uma ação invoca, enquanto um feature especifica a configuração (flags) que determina como essa ferramenta se comporta quando a ação é invocada.

Os recursos fazem referência a ações para indicar quais ações do Bazel elas afetam, já que as ações podem modificar o gráfico de ações do Bazel. O provedor CcToolchainConfigInfo contém ações que têm sinalizações e ferramentas associadas, como c++-compile. As flags são atribuídas a cada ação associando-as a um recurso.

Cada nome de ação representa um único tipo de ação realizada pelo Bazel, como a compilação ou o vinculação. No entanto, há uma relação de muitos para um entre ações e tipos de ação do Bazel, em que um tipo de ação do Bazel se refere a uma classe Java que implementa uma ação (como CppCompileAction). Em particular, as "ações do assembler" e "ações do compilador" na tabela abaixo são CppCompileAction, enquanto as ações de link são CppLinkAction.

Ações do assembler

Ações do compilador

Ações do link

Ações de RA

As ações de RA reúnem arquivos de objeto em bibliotecas de arquivos (arquivos .a) usando ar e codificam algumas semânticas no nome.

Ações de LTO

Como usar o action_config

O action_config é uma estrutura Starlark que descreve uma ação do Bazel especificando a ferramenta (binária) a ser invocada durante a ação e os conjuntos de flags, definidos por recursos. Essas flags aplicam restrições à execução da ação.

O construtor action_config() tem os seguintes parâmetros:

Um action_config pode exigir e implicar outros recursos e action_configs, conforme determinado pelas relacionamentos de recursos descritos anteriormente. Esse comportamento é semelhante ao de um recurso.

Os dois últimos atributos são redundantes em relação aos atributos correspondentes nos recursos e são incluídos porque algumas ações do Bazel exigem flags ou variáveis de ambiente específicas. O objetivo é evitar pares action_config+feature desnecessários. Normalmente, é preferível compartilhar um único recurso em várias action_configs.

Não é possível definir mais de um action_config com o mesmo action_name na mesma cadeia de ferramentas. Isso evita ambiguidades nos caminhos de ferramentas e reforça a intenção por trás de action_config, que as propriedades de uma ação sejam claramente descritas em um único lugar na cadeia de ferramentas.

Como usar o construtor de ferramentas

Um action_config pode especificar um conjunto de ferramentas pelo parâmetro tools. O criador de tool() usa os seguintes parâmetros:

Para um determinado action_config, apenas um tool aplica o caminho da ferramenta e os requisitos de execução à ação do Bazel. Uma ferramenta é selecionada iterando pelo atributo tools em um action_config até que uma ferramenta com um conjunto with_feature correspondente à configuração do recurso seja encontrada. Consulte Relacionamentos de recursos no início desta página para mais informações. Termine as listas de ferramentas com uma ferramenta padrão que corresponda a uma configuração de recurso vazia.

Exemplo de uso

Os recursos e as ações podem ser usados juntos para implementar ações do Bazel com várias semânticas multiplataforma. Por exemplo, a geração de símbolos de depuração no macOS requer a geração de símbolos na ação de compilação, a invocação de uma ferramenta especializada durante a ação de vinculação para criar um arquivo dsym comprimido e, em seguida, descompactar esse arquivo para produzir o pacote de aplicativo e os arquivos .plist que podem ser consumidos pelo Xcode.

Com o Bazel, esse processo pode ser implementado da seguinte maneira, com unbundle-debuginfo sendo uma ação do Bazel:

load("@rules_cc//cc:defs.bzl", "ACTION_NAMES")

action_configs = [
    action_config (
        config_name = ACTION_NAMES.cpp_link_executable,
        action_name = ACTION_NAMES.cpp_link_executable,
        tools = [
            tool(
                with_features = [
                    with_feature(features=["generate-debug-symbols"]),
                ],
                tool_path = "toolchain/mac/ld-with-dsym-packaging",
            ),
            tool (tool_path = "toolchain/mac/ld"),
        ],
    ),
]

features = [
    feature(
        name = "generate-debug-symbols",
        flag_sets = [
            flag_set (
                actions = [
                    ACTION_NAMES.c_compile,
                    ACTION_NAMES.cpp_compile
                ],
                flag_groups = [
                    flag_group(
                        flags = ["-g"],
                    ),
                ],
            )
        ],
        implies = ["unbundle-debuginfo"],
   ),
]

Esse mesmo recurso pode ser implementado de maneira totalmente diferente no Linux, que usa fission, ou no Windows, que produz arquivos .pdb. Por exemplo, a implementação para a geração de símbolos de depuração baseada em fission pode ter a seguinte aparência:

load("@rules_cc//cc:defs.bzl", "ACTION_NAMES")

action_configs = [
    action_config (
        name = ACTION_NAMES.cpp_compile,
        tools = [
            tool(
                tool_path = "toolchain/bin/gcc",
            ),
        ],
    ),
]

features = [
    feature (
        name = "generate-debug-symbols",
        requires = [with_feature_set(features = ["dbg"])],
        flag_sets = [
            flag_set(
                actions = [ACTION_NAMES.cpp_compile],
                flag_groups = [
                    flag_group(
                        flags = ["-gsplit-dwarf"],
                    ),
                ],
            ),
            flag_set(
                actions = [ACTION_NAMES.cpp_link_executable],
                flag_groups = [
                    flag_group(
                        flags = ["-Wl", "--gdb-index"],
                    ),
                ],
            ),
      ],
    ),
]

Grupos de sinalização

O CcToolchainConfigInfo permite agrupar flags em grupos com uma finalidade específica. É possível especificar uma flag usando variáveis predefinidas no valor da flag, que o compilador expande ao adicionar a flag ao comando de build. Exemplo:

flag_group (
    flags = ["%{output_file_path}"],
)

Nesse caso, o conteúdo da flag será substituído pelo caminho do arquivo de saída da ação.

Os grupos de sinalizadores são expandidos para o comando de build na ordem em que aparecem na lista, de cima para baixo, da esquerda para a direita.

Para flags que precisam ser repetidas com valores diferentes quando adicionadas ao comando de build, o grupo de flags pode iterar variáveis do tipo list. Por exemplo, a variável include_path do tipo list:

flag_group (
    iterate_over = "include_paths",
    flags = ["-I%{include_paths}"],
)

se expande para -I<path> para cada elemento de caminho na lista include_paths. Todas as flags (ou flag_groups) no corpo de uma declaração de grupo de flags são expandidas como uma unidade. Exemplo:

flag_group (
    iterate_over = "include_paths",
    flags = ["-I", "%{include_paths}"],
)

se expande para -I <path> para cada elemento de caminho na lista include_paths.

Uma variável pode ser repetida várias vezes. Exemplo:

flag_group (
    iterate_over = "include_paths",
    flags = ["-iprefix=%{include_paths}", "-isystem=%{include_paths}"],
)

é expandido para:

-iprefix=<inc0> -isystem=<inc0> -iprefix=<inc1> -isystem=<inc1>

As variáveis podem corresponder a estruturas acessíveis usando a notação de ponto. Por exemplo:

flag_group (
    flags = ["-l%{libraries_to_link.name}"],
)

As estruturas podem ser aninhadas e também podem conter sequências. Para evitar conflitos de nome e ser explícito, especifique o caminho completo pelos campos. Por exemplo:

flag_group (
    iterate_over = "libraries_to_link",
    flag_groups = [
        flag_group (
            iterate_over = "libraries_to_link.shared_libraries",
            flags = ["-l%{libraries_to_link.shared_libraries.name}"],
        ),
    ],
)

Expansão condicional

Os grupos de flags oferecem suporte à expansão condicional com base na presença de uma variável específica ou no campo dela usando os atributos expand_if_available, expand_if_not_available, expand_if_true, expand_if_false ou expand_if_equal. Exemplo:

flag_group (
    iterate_over = "libraries_to_link",
    flag_groups = [
        flag_group (
            iterate_over = "libraries_to_link.shared_libraries",
            flag_groups = [
                flag_group (
                    expand_if_available = "libraries_to_link.shared_libraries.is_whole_archive",
                    flags = ["--whole_archive"],
                ),
                flag_group (
                    flags = ["-l%{libraries_to_link.shared_libraries.name}"],
                ),
                flag_group (
                    expand_if_available = "libraries_to_link.shared_libraries.is_whole_archive",
                    flags = ["--no_whole_archive"],
                ),
            ],
        ),
    ],
)

Referência de CcToolchainConfigInfo

Esta seção fornece uma referência de variáveis de build, recursos e outras informações necessárias para configurar regras C++.

Variáveis de build de CcToolchainConfigInfo

Confira a seguir uma referência das variáveis de build CcToolchainConfigInfo.

Recursos conhecidos

Confira a seguir uma referência de recursos e as condições de ativação deles.

Lógica de correção de recursos legados

O Bazel aplica as seguintes mudanças aos recursos da cadeia de ferramentas para compatibilidade com versões anteriores:

• Move o recurso legacy_compile_flags para o topo da cadeia de ferramentas
• Move o recurso default_compile_flags para o topo da cadeia de ferramentas
• Adiciona o recurso dependency_file (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso pic (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso per_object_debug_info (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso preprocessor_defines (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso includes (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso include_paths (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso fdo_instrument (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso fdo_optimize (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso cs_fdo_instrument (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso cs_fdo_optimize (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso fdo_prefetch_hints (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso autofdo (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso build_interface_libraries (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso dynamic_library_linker_tool (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso symbol_counts (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso shared_flag (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso linkstamps (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso output_execpath_flags (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso runtime_library_search_directories (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso library_search_directories (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso archiver_flags (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso libraries_to_link (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso force_pic_flags (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso user_link_flags (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso legacy_link_flags (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso static_libgcc (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso fission_support (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso strip_debug_symbols (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso coverage (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso llvm_coverage_map_format (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso gcc_coverage_map_format (se não estiver presente) à parte de cima da cadeia de ferramentas
• Adiciona o recurso fully_static_link (se não estiver presente) à parte de baixo do conjunto de ferramentas
• Adiciona o recurso user_compile_flags (se não estiver presente) à parte de baixo do conjunto de ferramentas
• Adiciona o recurso sysroot (se não estiver presente) à parte de baixo do conjunto de ferramentas
• Adiciona o recurso unfiltered_compile_flags (se não estiver presente) à parte de baixo do conjunto de ferramentas
• Adiciona o recurso linker_param_file (se não estiver presente) à parte de baixo do conjunto de ferramentas
• Adiciona o recurso compiler_input_flags (se não estiver presente) à parte de baixo do conjunto de ferramentas
• Adiciona o recurso compiler_output_flags (se não estiver presente) à parte de baixo do conjunto de ferramentas

Esta é uma lista longa de recursos. O plano é se livrar deles quando o Crosstool no Starlark for concluído. Para os leitores curiosos, consulte a implementação em CppActionConfigs e, para cadeias de ferramentas de produção, considere adicionar no_legacy_features para tornar a cadeia de ferramentas mais independente.