"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 variable'", на любом целевом объекте можно ссылаться через предопределённые переменные "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, в зависимости от расширяемого атрибута. Это устаревшее поведение до 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.4.0/support.html.

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

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

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

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

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

Пример использования переменных, определённых в Starlark.