"Make" Переменные

• Использование
• Предопределённые переменные
• Предопределённые переменные genrule
• Предопределённые переменные путей к исходникам/выходам
• Пользовательские переменные

Переменные "Make" — это специальный тип расширяемых строковых переменных, доступных для атрибутов, помеченных как "Подлежащие подстановке переменных 'Make'".

Их можно использовать, например, для вставки специфических путей к инструментарию в пользовательские действия сборки.

Bazel предоставляет как предопределённые переменные, доступные всем мишеням, так и пользовательские переменные, которые определяются в зависимых мишенях и доступны только мишеням, зависящим от них.

Причина использования термина "Make" историческая: синтаксис и семантика этих переменных изначально были разработаны для соответствия GNU Make.

Использование

Атрибуты, помеченные как "Подлежащие подстановке переменных 'Make'", могут ссылаться на переменную "Make" FOO следующим образом:

my_attr = "prefix $(FOO) suffix"

Другими словами, любой подстроке, соответствующей $(FOO), присваивается значение FOO. Если это значение "bar", то итоговая строка будет:

my_attr = "prefix bar suffix"

Если FOO не соответствует известной переменной для потребляющей мишени, Bazel выдаст ошибку.

Переменные "Make", имена которых не являются символами, такими как @, могут быть обработаны используя только знак доллара, без скобок. Например:

my_attr = "prefix $@ suffix"

Чтобы записать $ как строковую литерал (то есть, предотвратить расширение переменной), запишите $$.

Предопределённые переменные

К предопределённым переменным "Make" можно обратиться из любого атрибута, помеченного как "Подлежащие подстановке переменных 'Make'", на любой мишени.

Для просмотра списка этих переменных и их значений для заданного набора опций сборки, выполните

bazel info --show_make_env [build options]

и посмотрите верхние строки вывода с заглавными буквами.

См. пример предопределённых переменных.

Переменные опций инструментария

• COMPILATION_MODE: fastbuild, dbg, или opt. (Подробнее)

Переменные путей

• BINDIR: Основание сгенерированного бинарного дерева для архитектуры мишени.

  Обратите внимание, что для программ, работающих во время сборки в архитектуре хоста, может использоваться другое дерево, для поддержки кросс-компиляции.

  Если вы хотите запустить инструмент из genrule, рекомендуемый способ получения его пути — $(execpath toolname), где toolname должен быть указан в атрибуте genrule tools.

• GENDIR: Основание сгенерированного дерева кода для архитектуры мишени.

Переменные архитектуры машины

• TARGET_CPU: Процессор архитектуры мишени, например, k8.

Предопределённые переменные genrule

Следующие переменные специально доступны для атрибута genrule cmd и, как правило, важны для корректной работы этого атрибута.

См. пример предопределённых переменных genrule.

• OUTS: Список genrule outs. Если у вас только один выходной файл, вы также можете использовать $@.
• SRCS: Список genrule srcs (точнее: имена путей к файлам, соответствующие меткам в списке srcs). Если у вас только один исходный файл, вы также можете использовать $<.
• <: SRCS, если это единственный файл. В противном случае, вызывает ошибку сборки.
• @: OUTS, если это единственный файл. В противном случае, вызывает ошибку сборки.

• RULEDIR: Каталог вывода мишени, то есть каталог, соответствующий имени пакета, содержащего мишень, в дереве genfiles или bin. Для //my/pkg:my_genrule он всегда заканчивается my/pkg, даже если выходы //my/pkg:my_genrule находятся в подкаталогах.

• @D: Каталог вывода. Если outs содержит одну запись, эта переменная расширяется до каталога, содержащего этот файл. Если она содержит несколько записей, эта переменная расширяется до корневого каталога пакета в дереве genfiles, даже если все выходные файлы находятся в одном подкаталоге!

  Примечание: Используйте RULEDIR вместо @D, так как RULEDIR имеет более простую семантику и ведет себя одинаково независимо от количества выходных файлов.

  Если genrule нужно сгенерировать временные промежуточные файлы (возможно, в результате использования другого инструмента, например, компилятора), он должен попытаться записать их в @D (хотя /tmp также будет доступен) и удалить их перед завершением.

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

Предопределённые переменные путей к исходникам/выходам

Предопределённые переменные execpath, execpaths, rootpath, rootpaths, location, и locations принимают параметры метки (например, $(execpath //foo:bar)) и подставляют пути к файлам, обозначенные этой меткой.

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

См. пример предопределённых переменных путей.

• execpath: Обозначает путь под execroot, где Bazel выполняет действия сборки.

  В приведённом примере Bazel выполняет все действия сборки в каталоге, связанном с символической ссылкой bazel-myproject в корне вашего рабочего пространства. Исходный файл empty.source связан по пути bazel-myproject/testapp/empty.source. Таким образом, его путь выполнения (который является подпутем ниже корня) составляет testapp/empty.source. Это путь, который действия сборки могут использовать для поиска файла.

  Файлы вывода подготавливаются аналогично, но также имеют префикс подпути bazel-out/cpu-compilation_mode/bin (или для выходов инструментов: bazel-out/cpu-opt-exec-hash/bin). В приведённом примере //testapp:app — это инструмент, так как он появляется в атрибуте show_app_output tools. Поэтому выходной файл app записывается в bazel-myproject/bazel-out/cpu-opt-exec-hash/bin/testapp/app. Таким образом, путь выполнения составляет bazel-out/cpu-opt-exec-hash/bin/testapp/app. Этот дополнительный префикс позволяет собирать одну и ту же мишень для, скажем, двух разных процессоров в одной сборке без перезаписи результатов.

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

• rootpath: Обозначает путь, который сгенерированный двоичный файл может использовать для поиска зависимости во время выполнения относительно подкаталога каталога runfiles, соответствующего главному репозиторию. Примечание: Это работает только если --enable_runfiles включено, что по умолчанию не так в Windows. Используйте rlocationpath для кроссплатформенной поддержки вместо этого.

  Это аналогично execpath, но удаляет описанные выше конфигурационные префиксы. В приведённом примере это означает, что empty.source и app используют чисто относительные пути к рабочему пространству: testapp/empty.source и testapp/app.

  Путь rootpath файла в внешнем репозитории repo будет начинаться с ../repo/, за которым следует путь относительно репозитория.

  У этой переменной те же требования «только один выход», что и у execpath.

• rlocationpath: Путь, который сгенерированный двоичный файл может передать функции Rlocation библиотеки runfiles для поиска зависимости во время выполнения, либо в каталоге runfiles (если доступен), либо с помощью манифеста runfiles.

  Это похоже на rootpath, поскольку не содержит конфигурационных префиксов, но отличается тем, что всегда начинается с имени репозитория. В приведённом примере это означает, что empty.source и app приводят к следующим путям: myproject/testapp/empty.source и myproject/testapp/app.

  Путь rlocationpath файла в внешнем репозитории repo будет начинаться с repo/, за которым следует путь относительно репозитория.

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

  У этой переменной те же требования «только один выход», что и у execpath.

• location: Синоним для execpath или rootpath, в зависимости от расширяемого атрибута. Это поведение legacy до Starlark, и не рекомендуется, если вы точно не знаете, что оно делает для конкретного правила. См. #2475 для получения дополнительной информации.

execpaths, rootpaths, rlocationpaths, и locations являются множественными вариантами execpath, rootpath, rlocationpaths, и location, соответственно. Они поддерживают метки, производящие несколько выходов, в котором каждый выход перечисляется, разделённый пробелом. Правила с нулевым выходом и неправильные метки вызывают ошибки сборки.

Все ссылки на метки должны присутствовать в srcs потребляющей мишени, файлах вывода или deps. В противном случае сборка завершится ошибкой. Мишени C++ также могут ссылаться на метки в data.

Метки не обязательно должны быть в каноническом формате: foo, :foo и //somepkg:foo подойдут.

Пользовательские переменные

Пользовательские переменные "Make" могут быть использованы в атрибутах, помеченных как "Подлежащие подстановке переменных 'Make'", но только в мишенях, которые зависят от других мишеней, которые определяют эти переменные.

В качестве лучшей практики все переменные должны быть настраиваемыми, если только нет веских причин для их включения в ядро Bazel. Это избавляет Bazel от необходимости загружать потенциально дорогостоящие зависимости для предоставления переменных, которые могут быть неинтересны целевым таргетам.

Переменные цепочки инструментов C++

Следующие переменные определены в правилах цепочки инструментов C++ и доступны для любого правила, которое устанавливает toolchains = ["@bazel_tools//tools/cpp:current_cc_toolchain"] (или "@bazel_tools//tools/cpp:current_cc_host_toolchain" для эквивалента цепочки инструментов хоста). Некоторые правила, такие как java_binary, неявно включают цепочку инструментов C++ в их определение правила. Они автоматически наследуют эти переменные.

Встроенные правила C++ намного сложнее, чем просто «скомпилировать код с помощью компилятора». Чтобы поддерживать такие разнообразные режимы компиляции, как *SAN, ThinLTO, с модулями/без модулей и тщательно оптимизированные исполняемые файлы одновременно с быстрым выполнением тестов на нескольких платформах, встроенные правила прилагают значительные усилия для обеспечения правильных входов, выходов и флагов командной строки для каждого из потенциально нескольких генерируемых внутренне действий.

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

• ABI: Версия ABI C++.
• AR: Команда «ar» из crosstool.
• C_COMPILER: Идентификатор компилятора C/C++, например llvm.

• CC: Команда компилятора C и C++.

  Мы настоятельно рекомендуем всегда использовать CC_FLAGS в сочетании с CC. Риск использования без этого сочетания возлагается на вас.

• CC_FLAGS: Минимальный набор флагов для компилятора C/C++, чтобы он был пригоден для использования правилами genrules. В частности, он содержит флаги для выбора правильной архитектуры, если CC поддерживает несколько архитектур.
• NM: Команда «nm» из crosstool.
• OBJCOPY: Команда objcopy из того же набора, что и компилятор C/C++.
• STRIP: Команда strip из того же набора, что и компилятор C/C++.

Переменные цепочки инструментов Java

Следующие переменные определены в правилах цепочки инструментов Java и доступны для любого правила, которое устанавливает toolchains = ["@bazel_tools//tools/jdk:current_java_runtime"] (или "@bazel_tools//tools/jdk:current_host_java_runtime" для эквивалента цепочки инструментов хоста).

Большинство инструментов в JDK не следует использовать напрямую. Встроенные правила Java используют гораздо более сложные подходы к компиляции и упаковке Java, чем могут выразить инструменты верхнего уровня, такие как интерфейсные JAR-файлы, интерфейсные JAR-файлы заголовков и высокооптимизированные реализации упаковки и слияния JAR-файлов.

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

• JAVA: Команда «java» (виртуальная машина Java). Избегайте её, используйте правило java_binary вместо неё, где это возможно. Может быть относительным путём. Если вам необходимо изменить директорию перед запуском java, необходимо сохранить текущую рабочую директорию перед её изменением.
• JAVABASE: Базовая директория, содержащая утилиты Java. Может быть относительным путём. Она будет иметь поддиректорию «bin».

Переменные, определённые в Starlark

Авторы правил и цепочек инструментов могут определять полностью настраиваемые переменные, возвращая поставщика TemplateVariableInfo. Любые правила, зависящие от этих переменных через атрибут toolchains, могут затем читать их значения:

Смотрите пример переменных, определённых в Starlark.