Правила платформ и инструментальных цепочек

Этот набор правил предназначен для того, чтобы позволить вам моделировать конкретные аппаратные платформы, для которых вы разрабатываете, и указывать конкретные инструменты, которые могут потребоваться для компиляции кода для этих платформ. Пользователь должен быть знаком с концепциями, объясненными здесь.

Правила

• constraint_setting
• constraint_value
• platform
• toolchain
• toolchain_type

constraint_setting

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

Это правило используется для введения нового типа ограничения, для которого платформа может указать значение. Например, вы можете определить constraint_setting, названный "glibc_version", для представления возможности платформ иметь разные версии библиотеки glibc. Для получения более подробной информации см. страницу Платформы.

Каждая constraint_setting имеет расширяемый набор связанных constraint_value. Обычно они определяются в одном и том же пакете, но иногда другой пакет введёт новые значения для существующего параметра. Например, предопределённый параметр @platforms//cpu:cpu может быть расширен пользовательским значением, чтобы определить платформу, нацеленную на нестандартную архитектуру процессора.

Аргументы

constraint_value

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

Пример

Следующее создаёт новое возможное значение для предопределённого constraint_value, представляющего архитектуру процессора.

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

Аргументы

platform

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

Это правило определяет новую платформу — именованный набор вариантов ограничений (например, архитектура процессора или версия компилятора), описывающий среду, в которой может работать часть сборки. Для получения более подробной информации см. страницу Платформы.

Пример

Это определяет платформу, описывающую любую среду, на которой работает Linux на ARM.

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

Флаги платформы

Платформы могут использовать атрибут flags для указания списка флагов, которые будут добавлены к конфигурации всякий раз, когда платформа используется в качестве целевой платформы (то есть, как значение флага --platforms).

Флаги, установленные с платформы, имеют наивысший приоритет и перезаписывают любое предыдущее значение для этого флага, заданное из командной строки, файла конфигурации или перехода.

Пример

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

Это определяет платформу под названием foo. Когда это целевая платформа (либо потому, что пользователь указал --platforms//:foo, либо потому, что переход установил флаг //command_line_option:platforms в значение ["//:foo"], или потому, что //:foo был использован в качестве платформы выполнения), тогда указанные флаги будут установлены в конфигурации.

Платформы и повторяющиеся флаги

Некоторые флаги накапливают значения при повторении, такие как --features, --copt, любой флаг Starlark, созданный как config.string(repeatable = True). Эти флаги несовместимы с установкой флагов с платформы: вместо этого все предыдущие значения будут удалены и перезаписаны значениями с платформы.

Например, приведённая ниже платформа, вызов build --platforms=//:repeat_demo --features feature_a --features feature_b приведет к тому, что значение флага --feature станет ["feature_c", "feature_d"], удалив особенности, заданные в командной строке.

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

По этой причине не рекомендуется использовать повторяющиеся флаги в атрибуте flags.

Наследование платформ

Платформы могут использовать атрибут parents для указания другой платформы, от которой они будут наследовать значения ограничений. Хотя атрибут parents принимает список, в настоящее время поддерживается не более одного значения, а указание нескольких родительских платформ является ошибкой.

При проверке значения параметра ограничения на платформе сначала проверяются значения, установленные непосредственно (через атрибут constraint_values), а затем значения ограничений на родительской платформе. Это продолжается рекурсивно по цепочке родительских платформ. Таким образом, любые значения, установленные непосредственно на платформе, будут перекрывать значения, установленные на родительской платформе.

Платформы наследуют атрибут exec_properties от родительской платформы. Элементы словаря в exec_properties родительской и дочерней платформ будут объединены. Если один и тот же ключ присутствует в родительской и дочерней exec_properties, будет использоваться значение дочерней платформы. Если дочерняя платформа указывает пустую строку как значение, соответствующее свойство будет сброшено.

Платформы также могут унаследовать (устаревший) атрибут remote_execution_properties от родительской платформы. Примечание: новый код должен использовать exec_properties вместо этого. Приведенная ниже логика сохраняется для совместимости со старым поведением, но будет удалена в будущем. Логика установки remote_execution_platform следующая, когда есть родительская платформа:

1. Если remote_execution_property не установлен на дочерней платформе, будет использоваться remote_execution_properties родительской платформы.
2. Если remote_execution_property установлен на дочерней платформе и содержит строку-макрос {PARENT_REMOTE_EXECUTION_PROPERTIES}, это макрос будет заменён содержимым атрибута remote_execution_property родительской платформы.
3. Если remote_execution_property установлен на дочерней платформе и не содержит макрос, будет использоваться remote_execution_property дочерней платформы без изменений.

Поскольку remote_execution_properties устарел и будет постепенно удалён, смешивание remote_execution_properties и exec_properties в одной цепочке наследования недопустимо. Предпочтительнее использовать exec_properties вместо устаревшего remote_execution_properties.

Пример: Значения ограничений

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

В этом примере у дочерних платформ есть следующие свойства:

• child_a имеет значения ограничений @platforms//os:linux (унаследованные от родителя) и @platforms//cpu:x86_64 (установленные непосредственно на платформе).
• child_b наследует все значения ограничений от родителя и не устанавливает свои собственные.

Пример: Свойства выполнения

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

В этом примере у дочерних платформ есть следующие свойства:

• child_a наследует "exec_properties" родителя и не устанавливает свои собственные.
• child_b наследует exec_properties родителя и переопределяет значение k1. Его exec_properties будет: { "k1": "child", "k2": "v2" }.
• child_c наследует exec_properties родителя и сбрасывает k1. Его exec_properties будет: { "k2": "v2" }.
• child_d наследует exec_properties родителя и добавляет новое свойство. Его exec_properties будет: { "k1": "v1", "k2": "v2", "k3": "v3" }.

Аргументы

Инструментарий

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

Это правило объявляет тип и ограничения конкретного инструментария, чтобы его можно было выбрать во время разрешения инструментария. Дополнительные сведения см. на странице Инструментарий.

Аргументы

Тип инструментария

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

Это правило определяет новый тип инструментария — простую цель, представляющую класс инструментов, которые выполняют одинаковую роль для разных платформ.

Дополнительные сведения см. на странице Инструментарий.

Пример

Это определяет тип инструментария для пользовательского правила.

toolchain_type(
    name = "bar_toolchain_type",
)

Это можно использовать в файле 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"]
)

Аргументы