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

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

Аргументы к WORKING_DIRECTORY могут использовать generator expressions.

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

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

POST_BUILD

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