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

Новая версия с 3.2.

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

Явное указание побочных продуктов поддерживается генератором Ninja для того, чтобы сообщить инструменту сборки ninja как перегенерировать побочные продукты, если они отсутствуют. Это также полезно, когда другие правила сборки (например, пользовательские команды) зависят от побочных продуктов. Ninja требует правила сборки для любого сгенерированного файла, от которого зависит другое правило, даже если есть только зависимости по порядку, чтобы гарантировать, что побочные продукты будут доступны до начала сборки их зависимостей.

Генераторы Makefile удалят BYPRODUCTS и другие файлы GENERATED во время make clean.

Новая версия с 3.20: Аргументы к BYPRODUCTS могут использовать generator expressions.

COMMAND

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

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

• Целевой файл не компилируется в другом окружении (т.е. переменная CMAKE_CROSSCOMPILING не установлена в true).

• Новая версия с 3.6: Целевой файл компилируется в другом окружении и эмулятор предоставлен (т.е. его свойство целевого файла CROSSCOMPILING_EMULATOR установлено). В этом случае содержимое CROSSCOMPILING_EMULATOR будет добавлено в начало команды перед расположением исполняемого файла целевого файла.

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

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

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

• TARGET_FILE
• TARGET_LINKER_FILE
• TARGET_SONAME_FILE
• TARGET_PDB_FILE

Эта зависимость уровня целевого файла не добавляет зависимость уровня файла, которая заставила бы пользовательскую команду повторно запускаться всякий раз, когда исполняемый файл пересобирается. Перечислите имена целевых файлов с опцией DEPENDS для добавления таких зависимостей уровня файла.

COMMENT

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

DEPENDS

Укажите файлы, от которых зависит команда. Каждый аргумент преобразуется в зависимость следующим образом:

1. Если аргумент — имя целевого файла (созданного командой add_custom_target(), add_executable() или add_library()), создаётся зависимость уровня целевого файла, чтобы убедиться, что целевой файл построен перед любым целевым файлом, использующим эту пользовательскую команду. Кроме того, если целевой файл — исполняемый файл или библиотека, создаётся зависимость уровня файла, чтобы заставить пользовательскую команду повторно запускаться всякий раз, когда целевой файл пересобирается.
2. Если аргумент — абсолютный путь, создаётся зависимость уровня файла от этого пути.
3. Если аргумент — имя исходного файла, добавленного в целевой файл или для которого установлено свойство исходного файла, создаётся зависимость уровня файла от этого исходного файла.
4. Если аргумент — относительный путь, и он существует в текущем каталоге исходных файлов, создаётся зависимость уровня файла от этого файла в текущем каталоге исходных файлов.
5. В противном случае создаётся зависимость уровня файла от этого пути относительно текущего каталога двоичных файлов.

Если какая-либо зависимость является OUTPUT другой пользовательской команды в том же каталоге (файл CMakeLists.txt), CMake автоматически добавляет другую пользовательскую команду в целевой файл, в котором построена эта команда.

Новая версия с 3.16: Добавляется зависимость уровня целевого файла, если любая зависимость указана как BYPRODUCTS целевого файла или любого из его событий сборки в том же каталоге, чтобы убедиться, что побочные продукты будут доступны.

Если DEPENDS не указано, команда будет выполняться всякий раз, когда OUTPUT отсутствует; если команда фактически не создаёт OUTPUT, правило будет всегда выполняться.

Новая версия с 3.1: Аргументы к DEPENDS могут использовать generator expressions.

COMMAND_EXPAND_LISTS

Новая версия с 3.8.

Списки в COMMAND аргументах будут расширены, включая те, что созданы с помощью generator expressions, что позволяет COMMAND аргументам, таким как ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc, корректно расширяться.

IMPLICIT_DEPENDS

Запрос на сканирование неявных зависимостей файла-входа. Указанный язык определяет язык программирования, для которого должен использоваться соответствующий сканер зависимостей. В настоящее время поддерживаются только сканеры зависимостей для языков C и CXX. Язык должен быть указан для каждого файла в списке IMPLICIT_DEPENDS. Зависимости, обнаруженные при сканировании, добавляются к тем, которые относятся к пользовательской команде во время сборки. Обратите внимание, что опция IMPLICIT_DEPENDS в настоящее время поддерживается только для генераторов Makefile и будет проигнорирована другими генераторами.

Примечание

Эта опция не может быть указана одновременно с опцией DEPFILE.

JOB_POOL

Новая версия с 3.15.

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

MAIN_DEPENDENCY

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

OUTPUT

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

Новое в версии 3.20: Аргументы для OUTPUT могут использовать generator expressions.

USES_TERMINAL

Новое в версии 3.2.

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

VERBATIM

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

WORKING_DIRECTORY

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

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

DEPFILE

Новое в версии 3.7.

Указать зависимость .d для генератора Ninja и Генераторы Makefile. Файл .d содержит зависимости, обычно выводимые самой пользовательской командой. Использование DEPFILE с другими генераторами, кроме Ninja или Генераторы Makefile, является ошибкой.

Новое в версии 3.20: Добавлена поддержка Генераторов Makefile.

Если аргумент DEPFILE относительный, он должен быть относительным к CMAKE_CURRENT_BINARY_DIR, и любые относительные пути внутри DEPFILE также должны быть относительными к CMAKE_CURRENT_BINARY_DIR (см. политику CMP0116. Эта политика всегда NEW для Генераторов Makefile).

Примечание

Для Генераторов Makefile этот параметр нельзя указать одновременно с параметром IMPLICIT_DEPENDS.

Примеры: Генерация файлов

Пользовательские команды могут использоваться для генерации исходных файлов. Например, код:

add_custom_command(
  OUTPUT out.c
  COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
                   -o out.c
  DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
  VERBATIM)
add_library(myLib out.c)

добавляет пользовательскую команду для выполнения someTool для генерации out.c и последующей компиляции сгенерированного исходного кода как части библиотеки. Правило генерации будет повторно выполняться всякий раз, когда in.txt изменяется.

add_custom_command(
  OUTPUT "out-$<CONFIG>.c"
  COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
                   -o "out-$<CONFIG>.c"
                   -c "$<CONFIG>"
  DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
  VERBATIM)
add_library(myLib "out-$<CONFIG>.c")

События построения

Второй вариант добавляет пользовательскую команду к целевому объекту, такому как библиотека или исполняемый файл. Это полезно для выполнения операции до или после построения целевого объекта. Команда становится частью целевого объекта и будет выполняться только при построении самого целевого объекта. Если целевой объект уже построен, команда не будет выполняться.

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

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

Примеры: События построения

Событие POST_BUILD может использоваться для постобработки двоичного файла после связывания. Например, код:

add_executable(myExe myExe.c)
add_custom_command(
  TARGET myExe POST_BUILD
  COMMAND someHasher -i "$<TARGET_FILE:myExe>"
                     -o "$<TARGET_FILE:myExe>.hash"
  VERBATIM)

выполнит someHasher для создания файла .hash рядом с исполняемым файлом после связывания.

add_library(myPlugin MODULE myPlugin.c)
add_custom_command(
  TARGET myPlugin POST_BUILD
  COMMAND someHasher -i "$<TARGET_FILE:myPlugin>"
                     --as-code "myPlugin-hash-$<CONFIG>.c"
  BYPRODUCTS "myPlugin-hash-$<CONFIG>.c"
  VERBATIM)
add_executable(myExe myExe.c "myPlugin-hash-$<CONFIG>.c")

Ninja Multi-Config