Reglas de plataformas y cadenas de herramientas

Este conjunto de reglas existe para permitirte modelar plataformas de hardware específicas para las que estás creando y especificar las herramientas específicas que puedes necesitar para compilar código para esas plataformas. El usuario debe conocer los conceptos que se explican aquí.

Reglas

• constraint_setting
• constraint_value
• platform
• cadena de herramientas
• toolchain_type

constraint_setting

constraint_setting(name, default_constraint_value, deprecation, distribs, features, licenses, tags, testonly, visibility)

Esta regla se usa para introducir un nuevo tipo de restricción para el que una plataforma puede especificar un valor. Por ejemplo, puedes definir un constraint_setting llamado "glibc_version" para representar la capacidad de las plataformas de tener instaladas diferentes versiones de la biblioteca glibc. Para obtener más detalles, consulta la página Plataformas.

Cada constraint_setting tiene un conjunto extensible de constraint_values asociados. Por lo general, se definen en el mismo paquete, pero, a veces, un paquete diferente introduce valores nuevos para un parámetro de configuración existente. Por ejemplo, el parámetro de configuración predefinido @platforms//cpu:cpu se puede extender con un valor personalizado para definir una plataforma que segmenta una arquitectura de CPU poco conocida.

Argumentos

constraint_value

constraint_value(name, constraint_setting, deprecation, distribs, features, licenses, tags, testonly, visibility)

Ejemplo

El siguiente comando crea un nuevo valor posible para el constraint_value predefinido que representa la arquitectura de CPU.

constraint_value(
    name = "mips",
    constraint_setting = "@platforms//cpu:cpu",
)

Argumentos

plataforma

platform(name, constraint_values, deprecation, distribs, exec_properties, features, flags, licenses, parents, remote_execution_properties, required_settings, tags, testonly, visibility)

Esta regla define una nueva plataforma, es decir, una colección con nombre de opciones de restricción (como la arquitectura de CPU o la versión del compilador) que describe un entorno en el que se puede ejecutar parte de la compilación. Para obtener más detalles, consulta la página Plataformas.

Ejemplo

Esto define una plataforma que describe cualquier entorno que ejecute Linux en ARM.

platform(
    name = "linux_arm",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)

Banderas de plataforma

Las plataformas pueden usar el atributo flags para especificar una lista de marcas que se agregarán a la configuración cada vez que la plataforma se use como plataforma de destino (es decir, como el valor de la marca --platforms).

Las marcas establecidas desde la plataforma tienen la mayor prioridad y reemplazan cualquier valor anterior de esa marca, ya sea desde la línea de comandos, el archivo .rc o la transición.

Ejemplo

platform(
    name = "foo",
    flags = [
        "--dynamic_mode=fully",
        "--//bool_flag",
        "--no//package:other_bool_flag",
    ],
)

Esto define una plataforma llamada foo. Cuando esta es la plataforma de destino (ya sea porque el usuario especificó --platforms//:foo, porque una transición estableció la marca //command_line_option:platforms en ["//:foo"] o porque se usó //:foo como plataforma de ejecución), las marcas proporcionadas se establecerán en la configuración.

Plataformas y marcas repetibles

Algunas marcas acumularán valores cuando se repitan, como --features, --copt y cualquier marca de Starlark creada como config.string(repeatable = True). Estas marcas no son compatibles con la configuración de marcas desde la plataforma. En cambio, se quitarán todos los valores anteriores y se reemplazarán por los valores de la plataforma.

Por ejemplo, dada la siguiente plataforma, la invocación build --platforms=//:repeat_demo --features feature_a --features feature_b terminará con el valor de la marca --feature como ["feature_c", "feature_d"], lo que quitará el conjunto de funciones establecido en la línea de comandos.

platform(
    name = "repeat_demo",
    flags = [
        "--features=feature_c",
        "--features=feature_d",
    ],
)

Por este motivo, no se recomienda usar marcas repetibles en el atributo flags.

Herencia de la plataforma

Las plataformas pueden usar el atributo parents para especificar otra plataforma de la que heredarán los valores de restricción. Si bien el atributo parents toma una lista, actualmente no se admite más de un valor, y especificar varios elementos superiores es un error.

Cuando se verifica el valor de un parámetro de configuración de restricción en una plataforma, primero se verifican los valores establecidos directamente (a través del atributo constraint_values) y, luego, los valores de restricción en el elemento principal. Esto continúa de forma recursiva en la cadena de plataformas principales. De esta manera, cualquier valor establecido directamente en una plataforma anulará los valores establecidos en la plataforma principal.

Las plataformas heredan el atributo exec_properties de la plataforma principal. Se combinarán las entradas del diccionario en exec_properties de las plataformas principal y secundaria. Si la misma clave aparece en el exec_properties del elemento principal y del secundario, se usará el valor del elemento secundario. Si la plataforma secundaria especifica una cadena vacía como valor, no se establecerá la propiedad correspondiente.

Las plataformas también pueden heredar el atributo remote_execution_properties (obsoleto) de la plataforma principal. Nota: El código nuevo debe usar exec_properties en su lugar. La lógica que se describe a continuación se mantiene para que sea compatible con el comportamiento heredado, pero se quitará en el futuro. La lógica para establecer el remote_execution_platform es la siguiente cuando hay una plataforma principal:

1. Si no se establece remote_execution_property en la plataforma secundaria, se usará el remote_execution_properties de la plataforma principal.
2. Si remote_execution_property se configura en la plataforma secundaria y contiene la cadena literal {PARENT_REMOTE_EXECUTION_PROPERTIES}, esa macro se reemplazará por el contenido del atributo remote_execution_property de la plataforma principal.
3. Si remote_execution_property se configura en la plataforma secundaria y no contiene la macro, se usará el remote_execution_property de la plataforma secundaria sin cambios.

Dado que remote_execution_properties dejó de estar disponible y se descontinuará, no se permite combinar remote_execution_properties y exec_properties en la misma cadena de herencia. Es preferible usar exec_properties en lugar de remote_execution_properties, que es obsoleto.

Ejemplo: Valores de restricción

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

En este ejemplo, las plataformas secundarias tienen las siguientes propiedades:

• child_a tiene los valores de restricción @platforms//os:linux (heredados del elemento principal) y @platforms//cpu:x86_64 (establecidos directamente en la plataforma).
• child_b hereda todos los valores de restricción del elemento superior y no establece ninguno propio.

Ejemplo: Propiedades de ejecución

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

En este ejemplo, las plataformas secundarias tienen las siguientes propiedades:

• child_a hereda las "exec_properties" del elemento superior y no establece las suyas propias.
• child_b hereda el exec_properties principal y anula el valor de k1. Su exec_properties será: { "k1": "child", "k2": "v2" }.
• child_c hereda el exec_properties del elemento superior y anula k1. Su exec_properties será: { "k2": "v2" }.
• child_d hereda el exec_properties de su elemento superior y agrega una nueva propiedad. Su exec_properties será: { "k1": "v1", "k2": "v2", "k3": "v3" }.

Argumentos

cadena de herramientas

toolchain(name, deprecation, distribs, exec_compatible_with, features, licenses, tags, target_compatible_with, target_settings, testonly, toolchain, toolchain_type, visibility)

Esta regla declara el tipo y las restricciones de una cadena de herramientas específica para que se pueda seleccionar durante la resolución de la cadena de herramientas. Consulta la página Toolchains para obtener más detalles.

Argumentos

toolchain_type

toolchain_type(name, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

Esta regla define un nuevo tipo de cadena de herramientas: un destino simple que representa una clase de herramientas que cumplen el mismo rol para diferentes plataformas.

Consulta la página Toolchains para obtener más detalles.

Ejemplo

Define un tipo de cadena de herramientas para una regla personalizada.

toolchain_type(
    name = "bar_toolchain_type",
)

Se puede usar en un archivo .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