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

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

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

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

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

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

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

Аргументы для 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

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