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 файла(ов). Цель, созданная в том же каталоге (файл 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.

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

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

WORKING_DIRECTORY

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

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

PRE_LINK

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

POST_BUILD

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