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

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

Правила

• constraint_setting
• constraint_value
• platform
• toolchain
• тип_инструментальной_цепочки

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 может быть расширен пользовательским значением, чтобы определить платформу, нацеленную на малораспространённую архитектуру процессора.

Аргументы

Атрибуты
name	Имя; обязательно Уникальное имя для этой цели.
default_constraint_value	Имя; неперенастраиваемый; по умолчанию None Метка значения по умолчанию для этого параметра, которая используется, если значение не указано. Если этот атрибут присутствует, constraint_value на который он ссылается, должен быть определён в том же пакете, что и это constraint_setting. Если у параметра ограничения есть значение по умолчанию, то, когда платформа не включает никакого значения ограничения для этого параметра, это равносильно тому, как если бы платформа указала значение по умолчанию. В противном случае, если значения по умолчанию нет, параметр ограничения считается неуказанным данной платформой. В этом случае платформа не будет соответствовать ни одному списку ограничений (например, для config_setting), требующему определённого значения для этого параметра.

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

Платформы затем могут объявлять, что у них есть архитектура mips в качестве альтернативы x86_64, arm, и так далее.

Аргументы

Атрибуты
name	Имя; обязательно Уникальное имя для этой цели.
constraint_setting	Метка; неперенастраиваемый; обязательно constraint_setting, для которого это constraint_value является возможным выбором.

платформа

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

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

Пример

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

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

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

Платформы могут использовать атрибут 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" }.

Аргументы

Атрибуты
name	Имя; обязательно Уникальное имя для этой цели.
constraint_values	Список метки; неперенастраиваемый; значение по умолчанию [] Комбинация вариантов ограничений, из которых состоит эта платформа. Для того чтобы платформа применялась к данной среде, среда должна содержать как минимум значения в этом списке. Каждая constraint_value в этом списке должна относиться к разным constraint_setting. Например, вы не можете определить платформу, которая требует, чтобы архитектура ЦП была одновременно @platforms//cpu:x86_64 и @platforms//cpu:arm.
exec_properties	Словарь: Строка -> Строка; неперенастраиваемый; значение по умолчанию {} Карта строк, которые влияют на способ выполнения действий удалённо. Bazel не пытается интерпретировать это, это обрабатывается как непрозрачные данные, которые передаются через поле Платформа протокола удаленного выполнения. Это включает любые данные из атрибутов родительской платформы exec_properties. Если дочерняя и родительская платформа определяют одни и те же ключи, значения дочерней платформы сохраняются. Любые ключи, связанные со значением, являющимся пустой строкой, удаляются из словаря. Этот атрибут полностью заменяет устаревший атрибут remote_execution_properties.
parents	Список метки; неперенастраиваемый; значение по умолчанию [] Метка цели platform , от которой должна унаследовать эта платформа. Хотя атрибут принимает список, не должно быть более одной платформы. Любые constraint_settings, не заданные непосредственно на этой платформе, будут найдены на родительской платформе. Подробности см. в разделе Наследование платформы.
remote_execution_properties	Строка; неперенастраиваемый; значение по умолчанию "" УСТАРЕЛО. Используйте атрибут exec_properties вместо него. Строка, используемая для настройки платформы удалённого выполнения. Фактические сборки не пытаются интерпретировать это, это обрабатывается как непрозрачные данные, которые могут использоваться конкретным SpawnRunner. Это может включать данные из атрибута «remote_execution_properties» родительской платформы, используя макрос «{PARENT_REMOTE_EXECUTION_PROPERTIES}». Подробности см. в разделе Наследование платформы.

Цепочка инструментов

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

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

Аргументы

Атрибуты
name	Имя; обязательно Уникальное имя для этой цели.
exec_compatible_with	Список метки; неперенастраиваемый; значение по умолчанию [] Список constraint_value , которые должны быть удовлетворены платформой выполнения для того, чтобы эта цепочка инструментов была выбрана для сборки цели на этой платформе.
target_compatible_with	Список метки; неперенастраиваемый; значение по умолчанию [] Список constraint_value , которые должны быть удовлетворены целевой платформой для того, чтобы эта цепочка инструментов была выбрана для сборки цели на этой платформе.
target_settings	Список метки; значение по умолчанию [] Список config_setting , которые должны быть удовлетворены настройками цели, чтобы эта цепочка инструментов была выбрана при разрешении цепочки инструментов.
toolchain	Имя; обязательно Цель, представляющая фактический инструмент или набор инструментов, которые становятся доступными при выборе этой цепочки инструментов.
toolchain_type	Метка; неперенастраиваемый; обязательно Метка цели toolchain_type , которая представляет роль, которую выполняет эта цепочка инструментов.

Тип цепочки инструментов

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

Аргументы

Атрибуты
name	Имя; обязательно Уникальное имя для этой цели.