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

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

  Это имеет те же требования «только один выход» что и execpath.

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

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

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

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

  Это имеет те же требования «только один выход» что и execpath.

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

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

Все указанные метки должны появляться в выходных файлах или 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 по адресу https://bazel.build/versions/6.0.0/contribute/support.

• 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, чем инструменты верхнего уровня, такие как интерфейсы Jars, заголовочные интерфейсы Jars и высокооптимизированные реализации упаковки и слияния Jar.

Эти переменные являются механизмом обратной совместимости, который следует использовать специалистам по языку в редких случаях. Если вы решите их использовать, пожалуйста, предварительно обратитесь к разработчикам Bazel по адресу https://bazel.build/versions/6.0.0/contribute/support.

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

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

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

Пример переменных, определённых Starlark.