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])

Это определяет команду для генерации указанного 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.

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

PRE_LINK

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

POST_BUILD

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