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]
                   [JOB_POOL job_pool]
                   [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 требует правила сборки для любого сгенерированного файла, от которого зависит другое правило, даже если есть только зависимости по порядку, чтобы гарантировать, что побочные продукты будут доступны перед сборкой их зависимостей.

COMMAND

Укажите команду(ы) командной строки для выполнения во время сборки. Если указано более одной COMMAND, они будут выполняться в порядке следования, но не обязательно объединяться в состоятельный командный интерпретатор или пакетную скрипт. (Чтобы запустить полную скрипт, используйте команду configure_file() или команду file(GENERATE) для её создания, а затем укажите COMMAND для запуска.) Необязательный аргумент ARGS предназначен для обратной совместимости и будет проигнорирован.

Если COMMAND указывает имя целевого исполняемого файла (созданного командой add_executable()), он будет автоматически заменён расположением созданного во время сборки исполняемого файла, если выполняется хотя бы одно из следующих условий:

• Целевой файл не компилируется на другом компьютере (т.е. переменная CMAKE_CROSSCOMPILING не установлена в значение true).
• Целевой файл компилируется на другом компьютере и предоставляется эмулятор (т.е. его свойство целевого файла CROSSCOMPILING_EMULATOR установлено). В этом случае содержимое CROSSCOMPILING_EMULATOR будет добавлено перед расположением исполняемого файла целевого файла.

Если ни одно из вышеперечисленных условий не выполняется, предполагается, что имя команды — это программа, которую необходимо найти в PATH во время сборки.

Аргументы COMMAND могут использовать generator expressions. Используйте выражение генератора TARGET_FILE для ссылки на расположение целевого объекта позже в командной строке (т.е. в качестве аргумента команды, а не как команды для выполнения).

Всякий раз, когда целевой объект используется как команда для выполнения или упоминается в выражении генератора в качестве аргумента команды, автоматически добавляется зависимость уровня целевого объекта, чтобы указанный целевой объект был собран до любого целевого объекта, использующего эту пользовательскую команду. Однако это НЕ добавляет зависимость уровня файла, которая заставила бы пользовательскую команду повторно выполняться при каждой перекомпиляции исполняемого файла. Перечислите имена целевых объектов с помощью опции DEPENDS для добавления таких зависимостей на уровне файлов.

COMMENT

Вывести указанное сообщение перед выполнением команд во время сборки.

DEPENDS

Указать файлы, от которых зависит команда. Если любая зависимость является OUTPUT другой пользовательской команды в той же директории (файл CMakeLists.txt), CMake автоматически включает другую пользовательскую команду в целевой объект, в котором построена эта команда. Добавляется зависимость уровня целевого объекта, если любая зависимость указана как BYPRODUCTS целевого объекта или любого из его событий сборки в той же директории, чтобы убедиться, что побочные продукты будут доступны. Если 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 и будет проигнорирована другими генераторами.

JOB_POOL

Укажите pool для генератора Ninja. Несовместимо с USES_TERMINAL, что подразумевает пул console. Использование пула, который не определён JOB_POOLS, приводит к ошибке в ninja во время сборки.

MAIN_DEPENDENCY

Укажите основной входной файл-источник для команды. Это обрабатывается так же, как любое значение, заданное для опции DEPENDS, но также подразумевает для генераторов Visual Studio, где следует расположить пользовательскую команду. Каждый файл-источник может иметь не более одной команды, указывающей его как основную зависимость. Команда компиляции (т.е. для библиотеки или исполняемого файла) считается неявной основной зависимостью, которая безмолвно перезаписывается указанием пользовательской команды.

OUTPUT

Укажите выходные файлы, которые команда должна произвести. Если имя выходного файла — это относительный путь, оно будет интерпретировано относительно каталога дерева сборки, соответствующего текущей директории исходного кода. Каждый выходной файл будет автоматически помечен свойством файла-источника GENERATED. Если выход пользовательской команды на самом деле не создаётся как файл на диске, он должен быть помечен свойством файла-источника SYMBOLIC.

USES_TERMINAL

Команда получит прямой доступ к терминалу, если это возможно. С генератором Ninja это помещает команду в пул console pool.

VERBATIM

Все аргументы команд будут правильно экранированы для инструмента сборки, чтобы вызываемая команда получала каждый аргумент без изменений. Обратите внимание, что один уровень экранирования всё ещё используется процессором языка CMake перед тем, как add_custom_command получит аргументы. Рекомендуется использовать VERBATIM, так как это обеспечивает правильное поведение. Если VERBATIM не указано, поведение зависит от платформы, так как нет защиты от специальных символов, специфичных для инструмента.

WORKING_DIRECTORY

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

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

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

Это определяет новую команду, которая будет связана со сборкой указанного <target>. <target> должна быть определена в текущем каталоге; целевые объекты, определенные в других каталогах, могут не быть указаны.

Время выполнения команды определяется выбранным из следующего:

PRE_BUILD

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

PRE_LINK

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

POST_BUILD

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