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

PRE_LINK

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

POST_BUILD

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