Configuración de la cadena de herramientas de C++

Descripción general

Para invocar el compilador con las opciones correctas, Bazel necesita conocer algunos detalles internos del compilador, como los directorios de inclusión y las marcas importantes. En otras palabras, Bazel necesita un modelo simplificado del compilador para comprender su funcionamiento.

Bazel necesita saber lo siguiente:

• Indica si el compilador admite thinLTO, módulos, vinculación dinámica o PIC (código independiente de la posición).
• Son las rutas de acceso a las herramientas requeridas, como gcc, ld, ar, objcopy, etcétera.
• Son los directorios de inclusión del sistema integrados. Bazel necesita estos datos para validar que todos los encabezados incluidos en el archivo fuente se hayan declarado correctamente en el archivo BUILD.
• Es el sysroot predeterminado.
• Marcas que se usarán para la compilación, la vinculación y el archivado.
• Marcas para usar en los modos de compilación admitidos (opt, dbg, fastbuild).
• Crear variables que el compilador requiera específicamente

Si el compilador admite varias arquitecturas, Bazel debe configurarlas por separado.

CcToolchainConfigInfo es un proveedor que proporciona el nivel de granularidad necesario para configurar el comportamiento de las reglas de C++ de Bazel. De forma predeterminada, Bazel configura automáticamente CcToolchainConfigInfo para tu compilación, pero tienes la opción de configurarlo de forma manual. Para ello, necesitas una regla de Starlark que proporcione el CcToolchainConfigInfo y debes dirigir el atributo toolchain_config del cc_toolchain a tu regla. Puedes crear el CcToolchainConfigInfo llamando a cc_common.create_cc_toolchain_config_info(). Puedes encontrar los constructores de Starlark para todos los structs que necesitarás en el proceso en @rules_cc//cc:cc_toolchain_config_lib.bzl.

Cuando un destino de C++ ingresa en la fase de análisis, Bazel selecciona el destino cc_toolchain adecuado según el archivo BUILD y obtiene el proveedor CcToolchainConfigInfo del destino especificado en el atributo cc_toolchain.toolchain_config. El destino cc_toolchain pasa esta información al destino de C++ a través de un CcToolchainProvider.

Por ejemplo, una acción de compilación o vinculación, creada por una regla como cc_binary o cc_library, necesita la siguiente información:

• El compilador o vinculador que se usará
• Marcas de línea de comandos para el compilador o el vinculador
• Marcas de configuración que se pasan a través de las opciones de --copt/--linkopt
• Variables de entorno
• Son los artefactos necesarios en la zona de pruebas en la que se ejecuta la acción.

Toda la información anterior, excepto los artefactos requeridos en el entorno de pruebas, se especifica en el destino de Starlark al que apunta cc_toolchain.

Los artefactos que se enviarán al entorno de pruebas se declaran en el destino cc_toolchain. Por ejemplo, con el atributo cc_toolchain.linker_files, puedes especificar el vinculador binario y las bibliotecas de la cadena de herramientas que se enviarán al sandbox.

Selección de la cadena de herramientas

La lógica de selección de la cadena de herramientas funciona de la siguiente manera:

1. El usuario especifica un destino cc_toolchain_suite en el archivo BUILD y dirige Bazel al destino con la opción --crosstool_top.

2. El destino cc_toolchain_suite hace referencia a varias cadenas de herramientas. Los valores de las marcas --cpu y --compiler determinan cuál de esas cadenas de herramientas se selecciona, ya sea solo en función del valor de la marca --cpu o en función de un valor conjunto --cpu | --compiler. El proceso de selección es el siguiente:

   • Si se especifica la opción --compiler, Bazel selecciona la entrada correspondiente del atributo cc_toolchain_suite.toolchains con --cpu | --compiler. Si Bazel no encuentra una entrada correspondiente, genera un error.

   • Si no se especifica la opción --compiler, Bazel selecciona la entrada correspondiente del atributo cc_toolchain_suite.toolchains solo con --cpu.

   • Si no se especifican marcas, Bazel inspecciona el sistema host y selecciona un valor de --cpu según sus hallazgos. Consulta el código del mecanismo de inspección.

Una vez que se selecciona una cadena de herramientas, los objetos feature y action_config correspondientes en la regla de Starlark rigen la configuración de la compilación (es decir, los elementos que se describen más adelante). Estos mensajes permiten implementar funciones de C++ completas en Bazel sin modificar el binario de Bazel. Las reglas de C++ admiten varias acciones únicas que se documentan en detalle en el código fuente de Bazel.

Funciones

Una función es una entidad que requiere marcas de línea de comandos, acciones, restricciones en el entorno de ejecución o alteraciones de dependencias. Una función puede ser tan simple como permitir que los archivos BUILD seleccionen configuraciones de marcas, como treat_warnings_as_errors, o interactúen con las reglas de C++ y, además, incluir nuevas acciones de compilación y entradas en la compilación, como header_modules o thin_lto.

Idealmente, CcToolchainConfigInfo contiene una lista de funciones, en la que cada función consta de uno o más grupos de marcas, y cada uno define una lista de marcas que se aplican a acciones específicas de Bazel.

Una función se especifica por su nombre, lo que permite un desacoplamiento completo de la configuración de la regla de Starlark de las versiones de Bazel. En otras palabras, una versión de Bazel no afecta el comportamiento de las configuraciones de CcToolchainConfigInfo, siempre y cuando esas configuraciones no requieran el uso de funciones nuevas.

Una función se habilita de una de las siguientes maneras:

• El campo enabled de la función está configurado como true.
• Bazel o el propietario de la regla lo habilitan de forma explícita.
• El usuario lo habilita a través de la opción --feature de Bazel o el atributo de regla features.

Las funciones pueden tener interdependencias, depender de marcas de línea de comandos, parámetros de configuración de archivos BUILD y otras variables.

Relaciones entre funciones

Por lo general, las dependencias se administran directamente con Bazel, que simplemente aplica los requisitos y administra los conflictos intrínsecos a la naturaleza de las funciones definidas en la compilación. La especificación de la cadena de herramientas permite restricciones más detalladas para su uso directo dentro de la regla de Starlark que rige la compatibilidad y la expansión de funciones. Debes realizar las siguientes acciones:

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

Acciones

Las acciones brindan la flexibilidad necesaria para modificar las circunstancias en las que se ejecuta una acción sin suponer cómo se ejecutará. Un action_config especifica el archivo binario de la herramienta que invoca una acción, mientras que un feature especifica la configuración (marcas) que determina cómo se comporta esa herramienta cuando se invoca la acción.

Las funciones hacen referencia a las acciones para indicar qué acciones de Bazel afectan, ya que las acciones pueden modificar el gráfico de acciones de Bazel. El proveedor CcToolchainConfigInfo contiene acciones que tienen marcas y herramientas asociadas, como c++-compile. Las marcas se asignan a cada acción asociándolas con una función.

Cada nombre de acción representa un solo tipo de acción que realiza Bazel, como compilar o vincular. Sin embargo, existe una relación de muchos a uno entre las acciones y los tipos de acciones de Bazel, en la que un tipo de acción de Bazel hace referencia a una clase de Java que implementa una acción (como CppCompileAction). En particular, las "acciones de ensamblador" y las "acciones de compilador" de la siguiente tabla son CppCompileAction, mientras que las acciones de vínculo son CppLinkAction.

Acciones del ensamblador

Acciones del compilador

Acciones de vínculos

Acciones de RA

Las acciones de AR ensamblan archivos de objetos en bibliotecas de archivos (archivos .a) a través de ar y codifican cierta semántica en el nombre.

Acciones de LTO

Cómo usar action_config

action_config es una estructura de Starlark que describe una acción de Bazel especificando la herramienta (binaria) que se invocará durante la acción y los conjuntos de marcas, definidos por las funciones. Estas marcas aplican restricciones a la ejecución de la acción.

El constructor action_config() tiene los siguientes parámetros:

Un action_config puede requerir e implicar otros atributos y action_configs según lo dictan las relaciones de atributos descritas anteriormente. Este comportamiento es similar al de una función.

Los últimos dos atributos son redundantes en comparación con los atributos correspondientes de las funciones y se incluyen porque algunas acciones de Bazel requieren ciertas marcas o variables de entorno, y el objetivo es evitar pares innecesarios de action_config+feature. Por lo general, se prefiere compartir un solo atributo en varios action_configs.

No puedes definir más de un action_config con el mismo action_name dentro de la misma cadena de herramientas. Esto evita la ambigüedad en las rutas de herramientas y refuerza la intención detrás de action_config: que las propiedades de una acción se describan claramente en un solo lugar de la cadena de herramientas.

Cómo usar el constructor de herramientas

Un action_config puede especificar un conjunto de herramientas a través de su parámetro tools. El constructor tool() toma los siguientes parámetros:

Para un action_config determinado, solo un tool aplica la ruta de su herramienta y los requisitos de ejecución a la acción de Bazel. Se selecciona una herramienta iterando el atributo tools en un action_config hasta que se encuentra una herramienta con un conjunto de with_feature que coincide con la configuración de la función (consulta Relaciones entre funciones más arriba en esta página para obtener más información). Debes finalizar tus listas de herramientas con una herramienta predeterminada que corresponda a una configuración de función vacía.

Ejemplo de uso

Las funciones y las acciones se pueden usar juntas para implementar acciones de Bazel con diversas semánticas multiplataforma. Por ejemplo, la generación de símbolos de depuración en macOS requiere generar símbolos en la acción de compilación, luego invocar una herramienta especializada durante la acción de vinculación para crear un archivo dsym comprimido y, luego, descomprimir ese archivo para producir el paquete de aplicación y los archivos .plist que Xcode puede consumir.

Con Bazel, este proceso se puede implementar de la siguiente manera, con unbundle-debuginfo como una acción de Bazel:

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

action_configs = [
    action_config (
        action_name = ACTION_NAMES.cpp_link_executable,
        tools = [
            tool(
                with_features = [
                    with_feature(features=["generate-debug-symbols"]),
                ],
                path = "toolchain/mac/ld-with-dsym-packaging",
            ),
            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"],
   ),
]

Esta misma función se puede implementar de forma completamente diferente para Linux, que usa fission, o para Windows, que produce archivos .pdb. Por ejemplo, la implementación para la generación de símbolos de depuración basados en fission podría verse de la siguiente manera:

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

action_configs = [
    action_config (
        name = ACTION_NAMES.cpp_compile,
        tools = [
            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 marcas

CcToolchainConfigInfo te permite agrupar marcas en grupos que cumplen un propósito específico. Puedes especificar una marca con variables predefinidas dentro del valor de la marca, que el compilador expande cuando agrega la marca al comando de compilación. Por ejemplo:

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

En este caso, el contenido de la marca se reemplazará por la ruta de acceso del archivo de salida de la acción.

Los grupos de marcas se expanden al comando de compilación en el orden en que aparecen en la lista, de arriba hacia abajo y de izquierda a derecha.

En el caso de las marcas que deben repetirse con diferentes valores cuando se agregan al comando de compilación, el grupo de marcas puede iterar variables de tipo list. Por ejemplo, la variable include_path de tipo list:

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

se expande a -I<path> para cada elemento de ruta de acceso en la lista include_paths. Todas las marcas (o flag_group) del cuerpo de una declaración de grupo de marcas se expanden como una unidad. Por ejemplo:

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

se expande a -I <path> para cada elemento de ruta de acceso en la lista include_paths.

Una variable se puede repetir varias veces. Por ejemplo:

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

Se expande a lo siguiente:

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

Las variables pueden corresponder a estructuras a las que se puede acceder con la notación de puntos. Por ejemplo:

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

Las estructuras pueden anidarse y también pueden contener secuencias. Para evitar conflictos de nombres y ser explícito, debes especificar la ruta de acceso completa a través de los campos. Por ejemplo:

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

Expansión condicional

Los grupos de marcas admiten la expansión condicional según la presencia de una variable en particular o su campo con los atributos expand_if_available, expand_if_not_available, expand_if_true, expand_if_false o expand_if_equal. Por ejemplo:

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

Referencia de CcToolchainConfigInfo

En esta sección, se proporciona una referencia de las variables de compilación, las funciones y otra información necesaria para configurar correctamente las reglas de C++.

Variables de compilación de CcToolchainConfigInfo

A continuación, se incluye una referencia de las variables de compilación CcToolchainConfigInfo.

Funciones conocidas

A continuación, se incluye una referencia de las funciones y sus condiciones de activación.

Lógica de aplicación de parches a funciones heredadas

Bazel aplica los siguientes cambios a las funciones de la cadena de herramientas para garantizar la retrocompatibilidad:

• Se mueve la función legacy_compile_flags a la parte superior de la cadena de herramientas.
• Se mueve la función default_compile_flags a la parte superior de la cadena de herramientas.
• Agrega la función dependency_file (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función pic (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función per_object_debug_info (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función preprocessor_defines (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función includes (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función include_paths (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función fdo_instrument (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función fdo_optimize (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función cs_fdo_instrument (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función cs_fdo_optimize (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función fdo_prefetch_hints (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función autofdo (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función build_interface_libraries (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función dynamic_library_linker_tool (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función shared_flag (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función linkstamps (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función output_execpath_flags (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función runtime_library_search_directories (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función library_search_directories (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función archiver_flags (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función libraries_to_link (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función force_pic_flags (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función user_link_flags (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función legacy_link_flags (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función static_libgcc (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función fission_support (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función strip_debug_symbols (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función coverage (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función llvm_coverage_map_format (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función gcc_coverage_map_format (si no está presente) en la parte superior de la cadena de herramientas.
• Agrega la función fully_static_link (si no está presente) en la parte inferior de la cadena de herramientas.
• Agrega la función user_compile_flags (si no está presente) en la parte inferior de la cadena de herramientas.
• Agrega la función sysroot (si no está presente) en la parte inferior de la cadena de herramientas.
• Agrega la función unfiltered_compile_flags (si no está presente) en la parte inferior de la cadena de herramientas.
• Agrega la función linker_param_file (si no está presente) en la parte inferior de la cadena de herramientas.
• Agrega la función compiler_input_flags (si no está presente) en la parte inferior de la cadena de herramientas.
• Agrega la función compiler_output_flags (si no está presente) en la parte inferior de la cadena de herramientas.

Esta es una larga lista de funciones. El plan es deshacerse de ellos una vez que se complete Crosstool en Starlark. Para el lector curioso, consulta la implementación en CppActionConfigs y, para las cadenas de herramientas de producción, considera agregar no_legacy_features para que la cadena de herramientas sea más independiente.