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]
                   [VERBATIM] [APPEND] [USES_TERMINAL])

Это определяет команду для генерации указанного OUTPUT файла(ов). Цель, созданная в той же директории (файл CMakeLists.txt), которая указывает любой выходной файл пользовательской команды как исходный файл, получает правило для генерации файла с помощью команды во время сборки. Не указывайте выходной файл в более чем одной независимой цели, которая может выполняться параллельно, так как два экземпляра правила могут конфликтовать (вместо этого используйте команду 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, они будут выполняться в порядке, но не обязательно объединяться в состояниевое командное или пакетное сценарий. (Для выполнения полного сценария используйте команду configure_file() или команду file(GENERATE) для его создания, а затем укажите COMMAND для его запуска.) Необязательный аргумент ARGS предназначен для обратной совместимости и будет проигнорирован.

Если COMMAND указывает исполняемую цель (созданную командой add_executable()), она будет автоматически заменена местоположением исполняемого файла, созданного во время сборки. (Используйте 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.

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

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

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

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

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 7 и более поздних версий. Для всех других генераторов PRE_BUILD будет рассматриваться как PRE_LINK.

PRE_LINK

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

POST_BUILD

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