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

Опция 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 и будет проигнорирована другими генераторами.

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 для генератора 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

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