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

Все аргументы команд будут корректно экранированы для инструмента сборки, так что вызываемая команда получит каждый аргумент без изменений. Обратите внимание, что один уровень экранирования всё ещё используется процессором языка CMake перед тем, как add_custom_command даже увидит аргументы. Рекомендовано использование 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 8 и более поздних версиях. Для всех остальных генераторов PRE_BUILD будет обрабатываться как PRE_LINK.

PRE_LINK

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

POST_BUILD

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