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 для генератора 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, выполняется до выполнения любых других правил в целевом объекте. В других генераторах, выполняется непосредственно перед PRE_LINK командами.

PRE_LINK

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

POST_BUILD

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