"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's tools.

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

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

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

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

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

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

• OUTS: Список genrule's outs. Если у вас только один выходной файл, вы также можете использовать $@.
• SRCS: Список genrule's 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's 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, в зависимости от расширяемого атрибута. Это устаревшее поведение до 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.