Ya comenzó el registro para BazelCon 2024

Se usó la API de Cloud Translation para traducir esta página.

Reglas de plataformas y cadenas de herramientas

7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

constraint_setting

Ver el origen de la regla

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 detalles, consulta la página Plataformas.

Cada constraint_setting tiene un conjunto extensible de constraint_value 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 orientada a una arquitectura de CPU poco conocida.

Argumentos

Atributos

name

Nombre: Obligatorio

Un nombre único para este objetivo.

default_constraint_value

Nombre; no configurable; el valor predeterminado es None

Es la etiqueta del valor predeterminado para esta configuración, que se usará si no se proporciona ningún valor. Si este atributo está presente, el constraint_value al que apunta debe definirse en el mismo paquete que este constraint_setting.

Si un parámetro de configuración de restricción tiene un valor predeterminado, cada vez que una plataforma no incluye ningún valor de restricción para ese parámetro, es lo mismo que si la plataforma hubiera especificado el valor predeterminado. De lo contrario, si no hay un valor predeterminado, se considera que esa plataforma no especificó la configuración de restricción. En ese caso, la plataforma no coincidiría con ninguna lista de restricciones (como para un config_setting) que requiera un valor particular para ese parámetro de configuración.

constraint_value

Ver el origen de la regla

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

Esta regla introduce un valor nuevo para un tipo de restricción determinado. Para obtener más información, consulta la página Plataformas.

Ejemplo

A continuación, se 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",
)

Luego, las plataformas pueden declarar que tienen la arquitectura mips como alternativa a x86_64, arm, etcétera.

Argumentos

Atributos

Atributos
`name`	Name; obligatorio Un nombre único para este objetivo.
`constraint_setting`	Etiqueta; no configurable; obligatorio El `constraint_setting` para el cual este `constraint_value` es una opción posible.

name

Name; obligatorio

Un nombre único para este objetivo.

constraint_setting

Etiqueta; no configurable; obligatorio

El constraint_setting para el cual este constraint_value es una opción posible.

plataforma

Ver la fuente de la regla

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 plataformas

Las plataformas pueden usar el atributo parents para especificar otra plataforma de la que heredarán los valores de restricción. Aunque 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 recursivamente 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 la misma clave aparece en el exec_properties del elemento superior y del secundario, se usará el valor del 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 remote_execution_properties (obsoleto) 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 para ser 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:

Si no se establece remote_execution_property en la plataforma secundaria, se usará el remote_execution_properties superior.
Si remote_execution_property se establece 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 del elemento superior.
Si remote_execution_property se establece en la plataforma secundaria y no contiene la macro, se usará el remote_execution_property secundario 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 de los suyos.

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 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

Atributos
`name`	Name; obligatorio Un nombre único para este destino.
`constraint_values`	Es una lista de etiquetas no configurables. El valor predeterminado es `[]`. Es la combinación de opciones de restricciones que comprende esta plataforma. Para que una plataforma se aplique a un entorno determinado, este debe tener al menos los valores de esta lista. Cada `constraint_value` de esta lista debe corresponder a un `constraint_setting` diferente. Por ejemplo, no puedes definir una plataforma que requiera que la arquitectura de la CPU sea `@platforms//cpu:x86_64` y `@platforms//cpu:arm` a la vez.
`exec_properties`	Diccionario: String -> String; no configurable; el valor predeterminado es `{}` Un mapa de cadenas que afectan la forma en que se ejecutan las acciones de forma remota. Bazel no intenta interpretar esto, se trata como datos opacos que se reenvían a través del campo Platform del protocolo de ejecución remota. Esto incluye cualquier dato de los atributos `exec_properties` de la plataforma superior. Si la plataforma superior y la secundaria definen las mismas claves, se conservan los valores de la plataforma secundaria. Cualquier clave asociada con un valor que es una string vacía se quita del diccionario. Este atributo reemplaza por completo el elemento `remote_execution_properties` obsoleto.
`parents`	Es una lista de etiquetas no configurables. El valor predeterminado es `[]`. Es la etiqueta de un objetivo `platform` del que esta plataforma debe heredar. Si bien el atributo toma una lista, no debe haber más de una plataforma presente. Cualquier constraint_settings que no se establezca directamente en esta plataforma se encontrará en la plataforma superior. Consulta la sección sobre herencia de plataformas para obtener más detalles.
`remote_execution_properties`	String; no configurable; el valor predeterminado es `""` OBSOLETO. En su lugar, usa el atributo exec_properties. Es una cadena que se usa para configurar una plataforma de ejecución remota. Las compilaciones reales no intentan interpretar esto, se tratan como datos opacos que un SpawnRunner específico puede usar. Esto puede incluir datos del atributo "remote_execution_properties" de la plataforma superior mediante la macro "{PARENT_REMOTE_EXECUTION_PROPERTIES}". Consulta la sección sobre herencia de plataformas para obtener más detalles.

cadena de herramientas

Ver la fuente de la regla

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

Atributos
`name`	Nombre: Obligatorio Un nombre único para este objetivo.
`exec_compatible_with`	Lista de etiquetas; no configurable; el valor predeterminado es `[]` Una lista de `constraint_value` que una plataforma de ejecución debe satisfacer a fin de que se seleccione esta cadena de herramientas para una compilación de destino en esa plataforma.
`target_compatible_with`	Lista de etiquetas; no configurable; el valor predeterminado es `[]` Es una lista de `constraint_value` que la plataforma de destino debe satisfacer para que se seleccione esta cadena de herramientas para una compilación de destino para esa plataforma.
`target_settings`	Lista de etiquetas; el valor predeterminado es `[]` Una lista de `config_setting` que debe satisfacer la configuración de destino para que esta cadena de herramientas se seleccione durante la resolución de la cadena de herramientas.
`toolchain`	Nombre: Obligatorio El destino que representa la herramienta o el conjunto de herramientas reales que se ponen a disposición cuando se selecciona esta cadena de herramientas.
`toolchain_type`	Etiqueta; no configurable; obligatorio Es la etiqueta de un destino `toolchain_type` que representa la función que cumple esta cadena de herramientas.

toolchain_type

Ver la fuente de la regla

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 cumple la misma función para 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

Atributos

name

Nombre: Obligatorio

Un nombre único para este objetivo.