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

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

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