Reglas de plataformas y cadenas de herramientas

Este conjunto de reglas existe con el fin de permitirte modelar plataformas de hardware específicas que estés compilando y especificar las herramientas específicas que podrías necesitar a fin de compilar código para esas plataformas. El usuario debe estar familiarizado con los conceptos que se explican aquí.

Reglas

• constraint_setting
• constraint_value
• plataforma
• 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 ingresar un nuevo tipo de restricción para el cual una plataforma puede especificar un valor. Por ejemplo, puedes definir una constraint_setting llamada "glibc_version" para representar la capacidad de las plataformas de tener instaladas diferentes versiones de la biblioteca glibc. Para obtener más información, consulta la página Plataformas.

Cada constraint_setting tiene un conjunto extensible de constraint_value asociados. Por lo general, estos se definen en el mismo paquete, pero a veces un paquete diferente ingresará valores nuevos para una configuración existente. Por ejemplo, la configuración predefinida @platforms//cpu:cpu se puede extender con un valor personalizado para definir una plataforma que se oriente a una arquitectura de CPU desconocida.

Argumentos

constraint_value

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

Ejemplo

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

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

Argumentos

plataforma

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

Esta regla define una plataforma nueva: una colección de opciones de restricciones con nombre (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 información, 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",
    ],
)

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 verificas el valor de una configuración de restricciones 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 superior. Esto continúa de forma recurrente en la cadena de plataformas superiores. De esta manera, cualquier valor configurado directamente en una plataforma anulará los valores establecidos en la plataforma superior.

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

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

1. Si remote_execution_property no está configurado en la plataforma secundaria, se usará el remote_execution_properties del superior.
2. Si remote_execution_property se configura en la plataforma secundaria y contiene la string literal {PARENT_REMOTE_EXECUTION_PROPERTIES}, esa macro se reemplazará con el contenido del atributo remote_execution_property del elemento superior.
3. Si remote_execution_property se configura en la plataforma secundaria y no contiene la macro, el remote_execution_property del secundario se usará sin cambios.

Dado que remote_execution_properties dejó de estar disponible y se eliminará de forma gradual, no se permite mezclar remote_execution_properties y exec_properties en la misma cadena de herencia. Es preferible usar exec_properties en lugar de remote_execution_properties, que dejó de estar disponible.

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 superior) y @platforms//cpu:x86_64 (configurados 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 una propia.
• child_b hereda el exec_properties del elemento superior 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 la configuración k1. Su exec_properties será: { "k2": "v2" }.
• child_d hereda el exec_properties del elemento superior y agrega una propiedad nueva. 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 Cadenas de herramientas 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 objetivo simple que representa una clase de herramientas que cumplen la misma función en diferentes plataformas.

Consulta la página Cadenas de herramientas para obtener más detalles.

Ejemplo

Esto define un tipo de cadena de herramientas para una regla personalizada.

toolchain_type(
    name = "bar_toolchain_type",
)

Se puede utilizar 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