Para obtener documentación sobre versiones estables, usa el menú desplegable "Documentos con versiones". La vista predeterminada refleja la versión más reciente en el encabezado.

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

Reglas de las plataformas y las cadenas de herramientas

Informar un problema Ver el código fuente

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

configuración_restricción

Ver fuente de la regla

constraint_setting(name, default_constraint_value, deprecation, distribs, 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 un constraint_setting llamado "glibc_version" para representar la capacidad de las plataformas de tener diferentes versiones de la biblioteca glibc instaladas. 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, otro paquete 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 esta orientación.

default_constraint_value

Name; optional; nonconfigurable

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 una configuración de restricción tiene un valor predeterminado, entonces, cuando una plataforma no incluye ningún valor de restricción para esa configuración, es igual que si la plataforma hubiera especificado el valor predeterminado. De lo contrario, si no hay un valor predeterminado, la plataforma considera que la configuración no está especificada. En ese caso, la plataforma no coincidirá con ninguna lista de restricciones (como un config_setting) que requiera un valor particular para esa configuración.

valor_restricción

Ver el origen de las reglas

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

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

Ejemplo

A continuación, se crea un nuevo valor posible para la constraint_value predefinida 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 esta orientación.

constraint_setting

Label; required; nonconfigurable

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

platform

Ver 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 con nombre de opciones de restricción (como la arquitectura de CPU o la versión de compilador) que describe un entorno en el que se puede ejecutar la parte de la compilación. Para obtener más detalles, consulta la página de 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 plataforma

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

Cuando se verifica el valor de una configuración de restricción en una plataforma, primero se verifican los valores establecidos directamente (mediante el 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 el elemento superior.

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

Las plataformas también pueden heredar el atributo remote_execution_properties (obsoleto) de la plataforma superior. Nota: El código nuevo debería usar exec_properties en su lugar. Se mantiene la lógica descrita a continuación para que sea 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 principal:

Si remote_execution_property no está configurado en la plataforma secundaria, se usará la remote_execution_properties superior.
Si remote_execution_property está configurado en la plataforma secundaria y contiene la string literal {PARENT_REMOTE_EXECUTION_PROPERTIES}, esa macro se reemplazará por el contenido del atributo remote_execution_property principal.
Si remote_execution_property está configurado en la plataforma secundaria y no contiene la macro, la remote_execution_property secundaria se usará sin cambios.

Como remote_execution_properties es obsoleto y se quitará de forma gradual, no se permite combinar remote_execution_properties y exec_properties en la misma cadena de herencia. Se prefiere 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 propiedades siguientes:

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

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 propiedades siguientes:

child_a hereda la "exec_properties" del elemento superior y no establece la suya propia.
child_b hereda el elemento superior exec_properties 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 de 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; required` Un nombre único para esta orientación.
`constraint_values`	`List of labels; optional; nonconfigurable` La combinación de opciones de restricción 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 ser para un `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` Mapa de strings 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 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, se conservan los valores del elemento secundario. Las claves asociadas con un valor que es una string vacía se quitan del diccionario. Este atributo reemplaza por completo a la versión obsoleta de `remote_execution_properties`.
`parents`	`List of labels; optional; nonconfigurable` La etiqueta de un destino `platform` del cual 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 Herencia de plataformas para obtener más información.
`remote_execution_properties`	`String; optional` OBSOLETO. En su lugar, use el atributo exec_properties. Una string 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 principal mediante la macro "{PARENT_REMOTE_EXECUTION_PROPERTIES}". Consulta la sección Herencia de plataformas para obtener más información.

cadena de herramientas

Ver 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`	`Name; required` Un nombre único para esta orientación.
`exec_compatible_with`	`List of labels; optional; nonconfigurable` Una lista de las `constraint_value` que una plataforma de ejecución debe satisfacer a fin de que esta cadena de herramientas se seleccione para una compilación de destino en esa plataforma.
`target_compatible_with`	`List of labels; optional; nonconfigurable` Una lista de las `constraint_value` que la plataforma de destino debe satisfacer a fin de que se seleccione esta cadena de herramientas para una compilación de destino de esa plataforma.
`target_settings`	`List of labels; optional` Una lista de objetos `config_setting` que la configuración de destino debe satisfacer para que se seleccione esta cadena de herramientas durante su resolución.
`toolchain`	`Name; required` Es el objetivo que representa la herramienta o el paquete de herramientas reales que está disponible cuando se selecciona esta cadena de herramientas.
`toolchain_type`	`Label; required; nonconfigurable` La etiqueta de un destino `toolchain_type` que representa la función que cumple esta cadena de herramientas.

Tipo de cadena de herramientas

Ver 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 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 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 esta orientación.