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]
                   [JOB_SERVER_AWARE <bool>]
                   [VERBATIM] [APPEND] [USES_TERMINAL]
                   [CODEGEN]
                   [COMMAND_EXPAND_LISTS]
                   [DEPENDS_EXPLICIT_ONLY])

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

Не указывайте выходной файл в более чем одной независимой цели, которые могут собираться параллельно, иначе экземпляры правила могут конфликтовать. Вместо этого используйте команду add_custom_target() для управления командой и сделайте другие цели зависимыми от неё. См. пример ниже Пример: Генерация файлов для нескольких целей.

Доступные параметры:

APPEND

Добавьте значения опций COMMAND и DEPENDS к пользовательской команде для первого указанного вывода. Должен быть уже выполнен предыдущий вызов этой команды с тем же выводом.

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

Опции COMMENT, MAIN_DEPENDENCY, и WORKING_DIRECTORY в настоящее время игнорируются, когда задано APPEND, но могут быть использованы в будущем.

BYPRODUCTS

Добавлена в версии 3.2.

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

См. политику CMP0058 для мотивации этой функции.

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

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

Этот ключевое слово нельзя использовать с APPEND (см. политику CMP0175). Все побочные продукты должны быть заданы в первом вызове add_custom_command(OUTPUT...) для файлов вывода.

Добавлена в версии 3.20: Аргументы к BYPRODUCTS могут использовать ограниченный набор generator expressions. Зависимые от целей выражения не допускаются.

Изменено в версии 3.28: В целях, использующих Наборы файлов, побочные продукты пользовательских команд теперь считаются закрытыми, если они не указаны в наборе файлов, не являющихся закрытыми. См. политику CMP0154.

COMMAND

Укажите командную строку(и) для выполнения во время сборки. Обычно указывается по крайней мере одна COMMAND, но некоторые шаблоны могут её опустить, например, добавление команд в отдельных вызовах с использованием APPEND.

Если указано более одной COMMAND, они будут выполняться в порядке, но не обязательно будут объединены в состояние shell или пакетный скрипт. Для выполнения полного скрипта используйте команду 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

Отобразить указанное сообщение перед выполнением команд во время сборки. Это будет проигнорировано, если задано APPEND, хотя в будущей версии может быть использовано.

Добавлена в версии 3.26: Аргументы к COMMENT могут использовать generator expressions.

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, быть корректно раскрытыми.

Этот ключевой слово нельзя использовать с APPEND (см. политику CMP0175). Если для выполнения добавленных команд необходимо установить этот параметр, он должен быть установлен при первом вызове add_custom_command(OUTPUT...) для выходных файлов.

CODEGEN

Добавлен в версии 3.31.

Добавляет пользовательскую команду к глобальной codegen цели, которую можно использовать для выполнения пользовательской команды, избегая при этом большинства элементов графа сборки.

Этот параметр поддерживается только генераторами Ninja и Makefile, и игнорируется другими генераторами. Кроме того, этот параметр разрешён только если политика CMP0171 установлена в NEW.

Это ключевое слово нельзя использовать с APPEND (см. политику CMP0175). Его можно установить только при первом вызове add_custom_command(OUTPUT...) для выходных файлов.

IMPLICIT_DEPENDS

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

Примечание

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

JOB_POOL

Добавлен в версии 3.15.

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

Это ключевое слово нельзя использовать с APPEND (см. политику CMP0175). Пулы задач можно указать только при первом вызове add_custom_command(OUTPUT...) для выходных файлов.

JOB_SERVER_AWARE

Добавлен в версии 3.28.

Указывает, что команда учитывает сервер задач GNU Make.

Для генераторов Unix Makefiles, MSYS Makefiles и MinGW Makefiles это добавит префикс + к строке рецепта. Подробнее см. Документацию GNU Make.

Этот параметр будет проигнорирован другими генераторами.

Это ключевое слово нельзя использовать с APPEND (см. политику CMP0175). Осведомлённость о сервере задач может быть указана только при первом вызове add_custom_command(OUTPUT...) для выходных файлов.

MAIN_DEPENDENCY

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

Этот параметр в настоящее время игнорируется, если указан APPEND, но в будущей версии он может быть использован.

OUTPUT

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

Если имя выходного файла является относительным путем, его абсолютный путь определяется путем интерпретации относительно:

1. каталога сборки, соответствующего текущему каталогу исходных файлов (CMAKE_CURRENT_BINARY_DIR), или
2. текущего каталога исходных файлов (CMAKE_CURRENT_SOURCE_DIR).

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

Путь к выходному файлу не может содержать символы < или >.

Добавлена в версии 3.20: Аргументы для OUTPUT могут использовать ограниченный набор generator expressions. Выражения, зависящие от целевых объектов не допускаются.

Изменено в версии 3.28: В целевых объектах, использующих Наборы файлов, выходные данные пользовательских команд теперь считаются закрытыми, если они не перечислены в не закрытом наборе файлов. См. политику CMP0154.

Изменено в версии 3.30: Путь к выходному файлу теперь может содержать символы #, за исключением использования генератора Borland Makefiles.

USES_TERMINAL

Добавлена в версии 3.2.

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

Этот ключевое слово не может быть использовано с APPEND (см. политику CMP0175). Если добавленные команды нуждаются в доступе к терминалу, это должно быть установлено при первом вызове add_custom_command(OUTPUT...) для выходных файлов.

VERBATIM

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

Это ключевое слово не может быть использовано с APPEND (см. политику CMP0175). Если добавленные команды должны обрабатываться как VERBATIM, это должно быть установлено при первом вызове add_custom_command(OUTPUT...) для выходных файлов.

WORKING_DIRECTORY

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

Этот параметр в настоящее время игнорируется, если указан APPEND, но в будущей версии он может быть использован.

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

DEPFILE

Добавлена в версии 3.7.

Укажите depfile, который содержит зависимости для пользовательской команды. Он обычно генерируется самой пользовательской командой. Это ключевое слово может быть использовано только если генератор его поддерживает, как описано ниже.

Ожидаемый формат, совместимый с тем, что генерируется gcc с параметром -M, не зависит от генератора или платформы.

Формальная синтаксическая запись, заданная с использованием обозначений Бэкуса-Наура с обычными расширениями, следующая:

depfile       ::=  rule*
rule          ::=  targets (':' (separator dependencies?)?)? eol
targets       ::=  target (separator target)* separator*
target        ::=  pathname
dependencies  ::=  dependency (separator dependency)* separator*
dependency    ::=  pathname
separator     ::=  (space | line_continue)+
line_continue ::=  '\' eol
space         ::=  ' ' | '\t'
pathname      ::=  character+
character     ::=  std_character | dollar | hash | whitespace
std_character ::=  <any character except '$', '#' or ' '>
dollar        ::=  '$$'
hash          ::=  '\#'
whitespace    ::=  '\ '
eol           ::=  '\r'? '\n'

Примечание

В качестве части pathname, все косые черты и обратные косые черты интерпретируются как разделители каталогов.

Добавлена в версии 3.7: Генератор Ninja поддерживает DEPFILE с момента добавления ключевого слова.

Добавлена в версии 3.17: Добавлен генератор Ninja Multi-Config, который включает поддержку ключевого слова DEPFILE.

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

Примечание

DEPFILE не может быть указан одновременно с параметром IMPLICIT_DEPENDS для Генераторов Makefile.

Добавлена в версии 3.21: Добавлена поддержка Генераторов Visual Studio с VS 2012 и выше, и для генератора Xcode. Также добавлена поддержка generator expressions.

Добавлена в версии 3.29: Генераторы Ninja теперь будут включать зависимости в базу данных "журнала зависимостей", если файл не указан в OUTPUTS или BYPRODUCTS.

Использование DEPFILE с генераторами, отличными от указанных выше, является ошибкой.

Если аргумент DEPFILE является относительным, он должен относиться к CMAKE_CURRENT_BINARY_DIR, а любые относительные пути внутри DEPFILE также должны относиться к CMAKE_CURRENT_BINARY_DIR. См. политику CMP0116, которая всегда NEW для Генераторов Makefile, Генераторов Visual Studio и генератора Xcode.

Это ключевое слово не может быть использовано с APPEND (см. политику CMP0175). Файлы depfile могут быть заданы только при первом вызове add_custom_command(OUTPUT...) для выходных файлов.

DEPENDS_EXPLICIT_ONLY

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

Без этого параметра, если какой-либо целевой объект использует выходные данные пользовательской команды, CMake будет рассматривать зависимости этого целевого объекта как неявные зависимости для пользовательской команды в случае, если эта пользовательская команда требует файлов, неявно созданных этими целевыми объектами.

Этот параметр можно включить для всех пользовательских команд, установив CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY в ON.

Этот ключевой параметр нельзя использовать с APPEND (см. политику CMP0175). Его можно задать только при первом вызове add_custom_command(OUTPUT...) для выходных файлов.

Только Генераторы Ninja фактически используют эту информацию для удаления ненужных неявных зависимостей.

См. также свойство целевого объекта OPTIMIZE_DEPENDENCIES, которое может предоставить другой способ уменьшения влияния зависимостей целевых объектов в некоторых сценариях.

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

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

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_executable(someTool someTool.c)

add_custom_command(
  OUTPUT out.c
  COMMAND someTool -o out.c
  CODEGEN)

add_library(myLib out.c)

Пример: Генерация файлов для нескольких целевых объектов

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

add_custom_command(
  OUTPUT table.csv
  COMMAND makeTable -i ${CMAKE_CURRENT_SOURCE_DIR}/input.dat
                    -o table.csv
  DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/input.dat
  VERBATIM)
add_custom_target(generate_table_csv DEPENDS table.csv)

add_custom_command(
  OUTPUT foo.cxx
  COMMAND genFromTable -i table.csv -case foo -o foo.cxx
  DEPENDS table.csv           # file-level dependency
          generate_table_csv  # target-level dependency
  VERBATIM)
add_library(foo foo.cxx)

add_custom_command(
  OUTPUT bar.cxx
  COMMAND genFromTable -i table.csv -case bar -o bar.cxx
  DEPENDS table.csv           # file-level dependency
          generate_table_csv  # target-level dependency
  VERBATIM)
add_library(bar bar.cxx)

Выход foo.cxx нужен только целевому объекту foo, а выход bar.cxx нужен только целевому объекту bar, но оба целевых объекта нуждаются в table.csv, транзитивно. Поскольку foo и bar — независимые целевые объекты, которые могут собираться параллельно, мы предотвращаем гонку за генерацию table.csv путем размещения его пользовательской команды в отдельном целевом объекте generate_table_csv. Пользовательские команды, генерирующие foo.cxx и bar.cxx указывают на уровне целевого объекта зависимость от generate_table_csv, поэтому целевые объекты, использующие их, foo и bar, не будут собираться до тех пор, пока не будет собран целевой объект generate_table_csv.

События сборки

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

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

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

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

PRE_BUILD

Этот параметр имеет уникальное поведение для Генераторов Visual Studio. При использовании одного из генераторов Visual Studio команда будет выполняться до выполнения других правил в рамках целевого объекта. Во всех других генераторах этот параметр ведет себя так же, как PRE_LINK вместо этого. По этой причине рекомендуется избегать использования PRE_BUILD за исключением случаев, когда известно, что используется генератор Visual Studio.

PRE_LINK

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

POST_BUILD

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

Проекты всегда должны указывать один из этих трех ключевых параметров при использовании формы TARGET. См. политику CMP0175.

Все другие ключевые параметры, показанные в сигнатуре выше, имеют то же значение, что и при использовании формы add_custom_command(OUTPUT) команды. Должен быть указан как минимум один COMMAND, см. политику CMP0175.

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

Событие 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

См. также

• add_custom_target()