add_custom_command

Добавляет пользовательское правило сборки в сгенерированную систему сборки.

Синтаксис

Generating Files
  add_custom_command(OUTPUT <output1> [<output2> ...]
                     COMMAND <command1> [ARGS] [<args1>...]
                     [...])

Build Events
  add_custom_command(TARGET <target>
                     PRE_BUILD | PRE_LINK | POST_BUILD
                     [...])

Создание файлов

add_custom_command(OUTPUT <output1> [<output2> ...] COMMAND <command1> [ARGS] [<args1>...] [...])

Добавить пользовательскую команду для создания выходного файла:

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

   Изменено в версии 4.4: Ранее исполняемую цель можно было указать, добавив .exe к имени цели. Теперь это запрещено. См. политику CMP0212.

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

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

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

Примечание

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

Добавлено в версии 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). Файлы depfile можно задать только при первом вызове add_custom_command(OUTPUT...) для выходных файлов.

DEPENDS_EXPLICIT_ONLY

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

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

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

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

Это ключевое слово нельзя использовать с 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 [...])

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

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()