add_custom_command

Добавить пользовательское правило сборки в сгенерированную систему сборки.

Существует две основные сигнатуры для add_custom_command.

Генерация файлов

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

add_custom_command(OUTPUT output1 [output2 ...]
                   COMMAND command1 [ARGS] [args1...]
                   [COMMAND command2 [ARGS] [args2...] ...]
                   [MAIN_DEPENDENCY depend]
                   [DEPENDS [depends...]]
                   [BYPRODUCTS [files...]]
                   [IMPLICIT_DEPENDS <lang1> depend1
                                    [<lang2> depend2] ...]
                   [WORKING_DIRECTORY dir]
                   [COMMENT comment]
                   [DEPFILE depfile]
                   [VERBATIM] [APPEND] [USES_TERMINAL]
                   [COMMAND_EXPAND_LISTS])

Это определяет команду для генерации указанных OUTPUT файла(ов). Цель, созданная в том же каталоге (файл %%%CODE_BLOCK_3%%), которая указывает любой вывод пользовательской команды как исходный файл, получает правило для генерации файла с помощью команды во время сборки. Не перечисляйте вывод более чем в одной независимой цели, которая может собираться параллельно, или две копии правила могут конфликтовать (вместо этого используйте команду add_custom_target() для управления командой и делайте другие цели зависимыми от этой цели). В терминах makefile это создаёт новую цель в следующем формате:

OUTPUT: MAIN_DEPENDENCY DEPENDS
        COMMAND

Опции:

APPEND

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

BYPRODUCTS

Укажите файлы, которые, как ожидается, создаст команда, но время их изменения может быть или не быть новее, чем время изменения зависимостей. Если имя побочного продукта — относительный путь, оно будет интерпретировано относительно каталога дерева сборки, соответствующего текущему каталогу исходных файлов. Каждый файл побочного продукта будет автоматически помечен свойством исходного файла GENERATED.

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

Опция BYPRODUCTS игнорируется генераторами, не являющимися Ninja, за исключением пометки побочных продуктов GENERATED.

COMMAND

Укажите командную строку(и) для выполнения во время сборки. Если указано более одной COMMAND, они будут выполняться в порядке, но не обязательно будут объединены в состояние shell или пакетной оболочки. (Для запуска полного скрипта используйте команду configure_file() или команду file(GENERATE) для его создания, а затем укажите COMMAND для запуска.) Необязательный аргумент ARGS предназначен для обратной совместимости и будет проигнорирован.

Если COMMAND указывает имя целевого исполняемого файла (созданного командой add_executable()), он будет автоматически заменён путём исполняемого файла, созданного во время сборки. При необходимости, свойство целевого исполняемого файла CROSSCOMPILING_EMULATOR также будет добавлено в начало команды для запуска исполняемого файла на хосте. (Используйте TARGET_FILE generator expression для ссылки на исполняемый файл позже в командной строке.) Кроме того, будет добавлена зависимость уровня цели, чтобы исполняемый файл был собран до любой цели, использующей эту пользовательскую команду. Однако ЭТО НЕ добавляет зависимость уровня файла, которая заставила бы пользовательскую команду повторно выполняться всякий раз, когда исполняемый файл пересобирается.

Аргументы для COMMAND могут использовать generator expressions. Ссылки на имена целей в выражениях генератора подразумевают зависимости уровня цели, но НЕ зависимости уровня файла. Перечислите имена целей с опцией DEPENDS для добавления зависимостей уровня файла.

COMMENT

Отобразить указанное сообщение перед выполнением команд во время сборки.

DEPENDS

Укажите файлы, от которых зависит команда. Если какая-либо зависимость является OUTPUT другой пользовательской команды в том же каталоге (файл CMakeLists.txt), CMake автоматически подключает другую пользовательскую команду в цель, в которой собирается эта команда. Если DEPENDS не указан, команда будет выполняться всякий раз, когда OUTPUT отсутствует; если команда на самом деле не создаёт OUTPUT, то правило будет всегда выполняться. Если DEPENDS указывает на любую цель (созданную командами add_custom_target(), add_executable() или add_library()), создаётся зависимость уровня цели, чтобы убедиться, что цель собрана до любой цели, использующей эту пользовательскую команду. Кроме того, если цель является исполняемым файлом или библиотекой, создаётся зависимость уровня файла, чтобы заставить пользовательскую команду повторно выполняться всякий раз, когда цель пересобирается.

Аргументы для DEPENDS могут использовать generator expressions.

COMMAND_EXPAND_LISTS

Список в аргументах COMMAND будет расширен, включая те, что созданы с помощью generator expressions, позволяя расширять аргументы COMMAND, такие как ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc.

IMPLICIT_DEPENDS

Запрос сканирования неявных зависимостей входного файла. Указанный язык определяет язык программирования, соответствующий сканеру зависимостей. В настоящее время поддерживаются только сканеры зависимостей для языков C и CXX. Язык должен быть указан для каждого файла в списке IMPLICIT_DEPENDS. Обнаруженные при сканировании зависимости добавляются к тем, которые относятся к пользовательской команде во время сборки. Обратите внимание, что опция IMPLICIT_DEPENDS в настоящее время поддерживается только для генераторов Makefile и будет проигнорирована другими генераторами.

MAIN_DEPENDENCY

Укажите основной исходный файл ввода для команды. Это рассматривается так же, как любое значение, указанное для опции DEPENDS, но также предполагает для генераторов Visual Studio, где повесить пользовательскую команду. Каждый исходный файл может иметь не более одной команды, указывающей его как основную зависимость. Команда компиляции (т.е. для библиотеки или исполняемого файла) считается неявной основной зависимостью, которая будет незаметно перезаписана спецификацией пользовательской команды.

OUTPUT

Укажите выходные файлы, которые, как ожидается, будут созданы командой. Если имя выходного файла — относительный путь, оно будет интерпретировано относительно каталога дерева сборки, соответствующего текущему каталогу исходных файлов. Каждый выходной файл будет автоматически помечен свойством исходного файла GENERATED. Если вывод пользовательской команды на самом деле не создаётся как файл на диске, он должен быть помечен свойством исходного файла SYMBOLIC.

USES_TERMINAL

Команда получит прямой доступ к терминалу, если это возможно. С генератором Ninja это помещает команду в пул console pool.

VERBATIM

Все аргументы команд будут правильно экранированы для инструмента сборки, чтобы вызванная команда получила каждый аргумент без изменений. Обратите внимание, что один уровень экранирования всё ещё используется процессором языка CMake перед тем, как add_custom_command даже увидит аргументы. Рекомендуется использовать VERBATIM, поскольку это обеспечивает правильное поведение. Когда VERBATIM не указан, поведение зависит от платформы, так как нет защиты от платформо-специфических специальных символов.

WORKING_DIRECTORY

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

Аргументы для WORKING_DIRECTORY могут использовать generator expressions.

DEPFILE

Указать файл .d depfile для генератора Ninja. Файл .d содержит зависимости, обычно выводимые самой пользовательской командой. Использование DEPFILE с генераторами, отличными от Ninja, является ошибкой.

События сборки

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

add_custom_command(TARGET <target>
                   PRE_BUILD | PRE_LINK | POST_BUILD
                   COMMAND command1 [ARGS] [args1...]
                   [COMMAND command2 [ARGS] [args2...] ...]
                   [BYPRODUCTS [files...]]
                   [WORKING_DIRECTORY dir]
                   [COMMENT comment]
                   [VERBATIM] [USES_TERMINAL])

Это определяет новую команду, которая будет связана со сборкой указанного <target>. <target> должен быть определён в текущем каталоге; целевые объекты, определённые в других каталогах, указать нельзя.

Время выполнения команды определяется тем, что из следующего указано:

PRE_BUILD

На генераторах Visual Studio, выполняется до выполнения любых других правил внутри целевого объекта. На других генераторах, выполняется непосредственно перед PRE_LINK командами.

PRE_LINK

Выполняется после того, как исходные файлы были скомпилированы, но перед линковкой бинарного файла или запуском утилиты библиотекаря или архиватора для статической библиотеки. Это не определено для целевых объектов, созданных командой add_custom_target().

POST_BUILD

Выполняется после выполнения всех других правил внутри целевого объекта.