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, они будут выполняться в порядке, но не обязательно в составе состояния shell или пакетной скрипта. (Чтобы запустить полную скрипт, используйте команду 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

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