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

Reglas de la plataforma

Reglas

constraint_setting
constraint_value
plataforma
cadena de herramientas
toolchain_type

constraint_setting

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

Esta regla se usa con el fin de ingresar un nuevo tipo de restricción para el que 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, estos se definen en el mismo paquete, pero, a veces, un paquete diferente introduce 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 oscura.

Argumentos

Atributos

name

Name; required

Un nombre único para este destino.

default_constraint_value

Name; optional; nonconfigurable

La etiqueta del valor predeterminado para este parámetro de 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 una configuración de restricción tiene un valor predeterminado, siempre que una plataforma no incluya ningún valor de restricción para esa configuración, será 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. En ese caso, la plataforma no coincidiría con ninguna lista de restricciones (como para una config_setting) que requiera un valor particular para esa configuración.

constraint_value

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

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

Ejemplo

Con el siguiente comando, se 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",
)

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

Argumentos

Atributos

name

Name; required

Un nombre único para este destino.

constraint_setting

Label; required; nonconfigurable

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

plataforma

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

Esta regla define una plataforma nueva: una colección determinada de opciones de restricciones (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 se ejecute en 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 valores de restricción. Aunque el atributo parents toma una lista, actualmente solo se admite un solo valor, y especificar varios elementos superiores es un error.

Cuando se verifica el valor de la configuración de una restricción en una plataforma, primero se verifican los valores establecidos directamente (a través del atributo constraint_values) y, luego, los valores de la restricción en el elemento superior. Esto continúa de manera recurrente en la cadena de plataformas superiores. De esta manera, cualquier valor configurado directamente en una plataforma anulará los valores establecidos en el elemento 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 superior y secundaria. Si aparece la misma clave en el exec_properties del elemento superior y el secundario, se usará el valor del secundario. Si la plataforma secundaria especifica una string 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 la remote_execution_platform es la siguiente cuando hay una plataforma superior:

Si remote_execution_property no está configurado en la plataforma secundaria, se usará la remote_execution_properties del elemento superior.
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 superior.
Si remote_execution_property se configura en la plataforma secundaria y no contiene la macro, el remote_execution_property del elemento secundario se usará sin cambios.

Dado que remote_execution_properties dejó de estar disponible y se eliminará, no se permite combinar remote_execution_properties y exec_properties en la misma cadena de herencia. Prefieres usar exec_properties en lugar del objeto remote_execution_properties 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 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 las propias.
child_b hereda el elemento 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 elemento exec_properties del elemento superior y agrega una propiedad nueva. Su exec_properties será: { "k1": "v1", "k2": "v2", "k3": "v3" }.

Argumentos

Atributos
`name`	`Name; required` Un nombre único para este destino.
`constraint_values`	`List of labels; optional` La combinación de opciones de restricciones que incluye 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 una `constraint_setting` diferente. Por ejemplo, no puedes definir una plataforma que requiera que la arquitectura de CPU sea `@platforms//cpu:x86_64` y `@platforms//cpu:arm`.
`exec_properties`	`Dictionary: String -> String; optional` Es un mapa de cadenas que afecta 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 de plataforma del protocolo de ejecución remota. Esto incluye cualquier dato de los atributos `exec_properties` de la plataforma superior. Si la plataforma secundaria y la superior definen las mismas claves, los valores de la secundaria se conservan. Todas las claves asociadas con un valor que sea una string vacía se quitan del diccionario. Este atributo reemplaza al `remote_execution_properties` obsoleto.
`parents`	`List of labels; optional` Es la etiqueta de destino `platform` del que debe heredar esta plataforma. Aunque 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. Para obtener más detalles, consulta la sección Herencia de la plataforma.
`remote_execution_properties`	`String; optional` 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 puede usar un SpawnRunner específico. 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 la plataforma para obtener más detalles.

cadena de herramientas

toolchain(name, deprecation, distribs, exec_compatible_with, exec_properties, 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 pueda seleccionarse durante la resolución de la cadena de herramientas. Consulta la página Cadenas de herramientas para obtener más detalles.

Argumentos

Atributos
`name`	`Name; required` Un nombre único para este destino.
`exec_compatible_with`	`List of labels; optional; nonconfigurable` Es una lista de los elementos `constraint_value` que debe cumplir una plataforma de ejecución a fin de que se seleccione esta cadena de herramientas para una compilación de destino en esa plataforma.
`target_compatible_with`	`List of labels; optional; nonconfigurable` Es una lista de elementos `constraint_value` que la plataforma de destino debe cumplir con el fin de que se seleccione esta cadena de herramientas para una compilación de destino para esa plataforma.
`target_settings`	`List of labels; optional` Es una lista de los `config_setting` que debe cumplir la configuración objetivo para que se seleccione esta cadena de herramientas durante su resolución.
`toolchain`	`Name; required` Es el destino que representa la herramienta o el conjunto de herramientas real que está disponible cuando se selecciona esta cadena de herramientas.
`toolchain_type`	`Label; required; nonconfigurable` Es la etiqueta de destino `toolchain_type` que representa la función que cumple esta cadena de herramientas.

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 información.

Ejemplo

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

toolchain_type(
    name = "bar_toolchain_type",
)

Esto 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

Atributos

name

Name; required

Un nombre único para este destino.