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 удалят 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, не зависит от генератора или платформы.

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

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

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

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

Этот ключевой параметр не может использоваться с APPEND (см. политику CMP0175). Depfiles могут быть установлены только при первом вызове 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()