Переменные Make

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

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

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

Bazel предоставляет как предопределённые переменные, доступные всем целевым объектам, так и пользовательские переменные, определяемые в целевых объектах-зависимостях и доступные только целевым объектам, которые зависят от них.

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

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

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

my_attr = "prefix $(FOO) suffix"

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

my_attr = "prefix bar suffix"

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

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

my_attr = "prefix $@ suffix"

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

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

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

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

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 и в целом важны для работы этого атрибута.

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

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

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

Переменные пользователя

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

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

Переменные инструментария C++

Ниже перечислены переменные, определённые в правилах инструментария C++, доступные для любого правила, устанавливающего toolchains = ["@bazel_tools//tools/cpp:current_cc_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.