cmake(1)

Синтаксис

Generate a Project Buildsystem
 cmake [<options>] -B <path-to-build> [-S <path-to-source>]
 cmake [<options>] <path-to-source | path-to-existing-build>

Build a Project
 cmake --build <dir> [<options>] [-- <build-tool-options>]

Install a Project
 cmake --install <dir> [<options>]

Open a Project
 cmake --open <dir>

Run a Script
 cmake [-D <var>=<value>]... -P <cmake-script-file>

Run a Command-Line Tool
 cmake -E <command> [<options>]

Run the Find-Package Tool
 cmake --find-package [<options>]

Run a Workflow Preset
 cmake --workflow [<options>]

View Help
 cmake --help[-<topic>]

Описание

Исполняемый файл cmake является командной строкой генератора кроссплатформенной системы сборки CMake. Вышеприведённый Синтаксис перечисляет различные действия, которые может выполнять инструмент, как описано в разделах ниже.

Для построения проекта программного обеспечения с помощью CMake, Сгенерируйте систему сборки проекта. Можно использовать cmake для построения проекта, установки проекта или просто запуска соответствующего инструмента сборки (например, make) напрямую. cmake также может использоваться для просмотра справки.

Другие действия предназначены для использования разработчиками программного обеспечения, которые пишут скрипты на языке CMake language для поддержки своих сборок.

Для графических пользовательских интерфейсов, которые могут быть использованы вместо cmake, см. ccmake и cmake-gui. Для командных интерфейсов к средствам тестирования и упаковки CMake, см. ctest и cpack.

Для получения дополнительной информации о CMake, см. также ссылки в конце этого руководства.

Введение в системы сборки CMake

Система сборки описывает, как построить исполняемые файлы и библиотеки проекта из исходного кода, используя инструмент сборки для автоматизации процесса. Например, система сборки может быть Makefile для использования с командной строкой make инструментом или файлом проекта для интегрированной среды разработки (IDE). Чтобы избежать поддержки нескольких таких систем сборки, проект может абстрактно указать свою систему сборки, используя файлы, написанные на языке CMake language. На основе этих файлов CMake генерирует предпочтительную систему сборки локально для каждого пользователя через бэкенд, называемый генератором.

Для генерации системы сборки с помощью CMake необходимо выбрать следующее:

Дерево исходных файлов

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

Дерево сборки

Верхний каталог, в котором будут храниться файлы системы сборки и артефакты выходных данных сборки (например, исполняемые файлы и библиотеки). CMake запишет файл CMakeCache.txt для идентификации каталога как дерева сборки и хранения постоянной информации, такой как параметры конфигурации системы сборки.

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

Генератор

Это выбирает тип системы сборки для генерации. См. руководство cmake-generators(7) для документации по всем генераторам. Запустите cmake --help, чтобы увидеть список доступных локально генераторов. Можно использовать опцию -G ниже, чтобы указать генератор, или просто принять по умолчанию тот, который выбирает CMake для текущей платформы.

При использовании одного из Генераторов инструментов командной строки для сборки CMake ожидает, что необходимая для компилятора цепочка инструментов среда уже настроена в оболочке. При использовании одного из Генераторов инструментов IDE для сборки особой среды не требуется.

Сгенерировать систему сборки проекта

Запустите CMake с одной из следующих команд, чтобы указать деревья исходных и сборки и сгенерировать систему сборки:

cmake [<options>] -B <path-to-build> [-S <path-to-source>]

Использует <path-to-build> как дерево сборки и <path-to-source> как дерево исходных файлов. Указанные пути могут быть абсолютными или относительными к текущей рабочей директории. Дерево исходных файлов должно содержать файл CMakeLists.txt. Дерево сборки будет автоматически создано, если оно ещё не существует. Например:

$ cmake -S src -B build

cmake [<options>] <path-to-source>

Использует текущую рабочую директорию как дерево сборки и <path-to-source> как дерево исходных файлов. Указанный путь может быть абсолютным или относительным к текущей рабочей директории. Дерево исходных файлов должно содержать файл CMakeLists.txt и не должно содержать файл CMakeCache.txt, поскольку последний идентифицирует существующее дерево сборки. Например:

$ mkdir build ; cd build
$ cmake ../src

cmake [<options>] <path-to-existing-build>

Использует <path-to-existing-build> как дерево сборки и загружает путь к дереву исходных файлов из файла CMakeCache.txt, который должен быть уже сгенерирован предыдущим запуском CMake. Указанный путь может быть абсолютным или относительным к текущей рабочей директории. Например:

$ cd build
$ cmake .

Во всех случаях <options> может содержать ноль или более опций из раздела Опции ниже.

Вышеуказанные стили указания дерева исходных и дерева сборки могут быть смешаны. Пути, указанные с помощью -S или -B, всегда классифицируются как дерево исходных или дерево сборки соответственно. Пути, указанные простыми аргументами, классифицируются на основе их содержимого и типов путей, заданных ранее. Если указан только один тип пути, текущая рабочая директория (cwd) используется для другого. Например:

После генерации системы сборки можно использовать соответствующий инструмент локальной сборки для построения проекта. Например, после использования генератора Unix Makefiles можно запустить make напрямую:

$ make
$ make install

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

Опции

-S <path-to-source>

Путь к корневой директории проекта CMake для сборки.

-B <path-to-build>

Путь к каталогу, который CMake будет использовать в качестве корня каталога сборки.

Если каталог не существует, CMake создаст его.

-C <initial-cache>

Предварительная загрузка скрипта для заполнения кэша.

Когда CMake впервые запускается в пустом дереве сборки, он создаёт файл CMakeCache.txt и заполняет его настраиваемыми параметрами проекта. Эта опция может быть использована для указания файла, из которого следует загрузить записи кэша перед первым проходом по файлам CMake проекта. Загруженные записи имеют приоритет над значениями по умолчанию проекта. Указанный файл должен быть скриптом CMake, содержащим команды set(), которые используют опцию CACHE, а не файл формата кэша.

Ссылки на CMAKE_SOURCE_DIR и CMAKE_BINARY_DIR в скрипте интерпретируются как корневое дерево исходных файлов и дерево сборки.

-D <var>:<type>=<value>, -D <var>=<value>

Создать или обновить запись CMake CACHE.

При первом запуске CMake в пустом дереве сборки, он создает файл CMakeCache.txt и заполняет его настраиваемыми настройками проекта. Этот параметр может использоваться для указания настройки, которая имеет приоритет над значением по умолчанию проекта. Параметр можно повторять для любого количества CACHE записей по желанию.

Если указана часть :<type>, она должна быть одним из типов, указанных в документации команды set() для ее CACHE сигнатуры. Если часть :<type> опущена, запись будет создана без типа, если она не существует с уже заданным типом. Если команда в проекте установит тип на PATH или FILEPATH, то <value> будет преобразовано в абсолютный путь.

Этот параметр также может быть задан как один аргумент: -D<var>:<type>=<value> или -D<var>=<value>.

Важно отметить, что порядок аргументов -C и -D важен. Они будут выполняться в том порядке, в котором они перечислены, причем последний аргумент имеет приоритет над предыдущими. Например, если вы укажете -DCMAKE_BUILD_TYPE=Debug, за которым следует аргумент -C с файлом, который вызывает:

set(CMAKE_BUILD_TYPE "Release" CACHE STRING "" FORCE)

то аргумент -C будет иметь приоритет, и CMAKE_BUILD_TYPE будет установлено в Release. Однако, если аргумент -D следует за аргументом -C, он будет установлен на Debug.

Если вызов set(... CACHE ...) в файле -C не использует FORCE, а аргумент -D устанавливает ту же переменную, то аргумент -D будет иметь приоритет независимо от порядка, из-за особенностей вызовов не-FORCE set(... CACHE ...).

-U <globbing_expr>

Удалить соответствующие записи из CMake CACHE.

Этот параметр может использоваться для удаления одной или нескольких переменных из файла CMakeCache.txt, поддерживаются выражения поиска по шаблону, использующие * и ? . Параметр можно повторять для любого количества CACHE записей по желанию.

Используйте с осторожностью, вы можете сделать свой CMakeCache.txt неработающим.

-G <generator-name>

Указать генератор системы сборки.

CMake может поддерживать несколько собственных систем сборки на определенных платформах. Генератор отвечает за генерацию конкретной системы сборки. Возможные имена генераторов указаны в руководстве cmake-generators(7).

Если не указано, CMake проверяет переменную среды CMAKE_GENERATOR и в противном случае использует встроенный выбор по умолчанию.

-T <toolset-spec>

Указание набора инструментов для генератора, если он поддерживается.

Некоторые генераторы CMake поддерживают указание набора инструментов, чтобы сообщить собственной системе сборки, как выбрать компилятор. Подробнее см. переменную CMAKE_GENERATOR_TOOLSET.

-A <platform-name>

Указать имя платформы, если оно поддерживается генератором.

Некоторые генераторы CMake поддерживают имя платформы, которое нужно передать собственной системе сборки, чтобы выбрать компилятор или SDK. Подробнее см. переменную CMAKE_GENERATOR_PLATFORM.

--toolchain <path-to-file>

Новое в версии 3.21.

Укажите файл инструментальной цепочки кросс-компиляции, эквивалентный установке переменной CMAKE_TOOLCHAIN_FILE.

--install-prefix <directory>

Новое в версии 3.21.

Укажите каталог установки, используемый переменной CMAKE_INSTALL_PREFIX. Должен быть абсолютным путем.

-Wno-dev

Отключить предупреждения для разработчиков.

Отключить предупреждения, предназначенные для автора файлов CMakeLists.txt. По умолчанию это также отключит предупреждения об устаревании.

-Wdev

Включить предупреждения для разработчиков.

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

-Wdeprecated

Включить предупреждения об устаревшей функциональности.

Включить предупреждения об использовании устаревшей функциональности, предназначенные для автора файлов CMakeLists.txt.

-Wno-deprecated

Отключить предупреждения об устаревшей функциональности.

Отключить предупреждения об использовании устаревшей функциональности, предназначенные для автора файлов CMakeLists.txt.

-Werror=<what>

Обрабатывать предупреждения CMake как ошибки. <what> должен быть одним из следующих:

dev

Сделать предупреждения разработчиков ошибками.

Сделать предупреждения, предназначенные для автора файлов CMakeLists.txt, ошибками. По умолчанию это также включит предупреждения об устаревании как ошибки.

deprecated

Сделать предупреждения об устаревших макросах и функциях ошибками.

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

-Wno-error=<what>

Не обрабатывать предупреждения CMake как ошибки. <what> должен быть одним из следующих:

dev

Сделать предупреждения, предназначенные для автора файлов CMakeLists.txt, не ошибками. По умолчанию это также отключит предупреждения об устаревании как ошибки.

deprecated

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

--fresh

Новое в версии 3.24.

Выполнить свежую конфигурацию дерева сборки. Это удалит любой существующий файл CMakeCache.txt и связанную директорию CMakeFiles/, и создаст их заново с нуля.

-L[A][H]

Список не-расширенных кэшированных переменных.

Список переменных CACHE запустит CMake и отобразит все переменные из кэша CMake CACHE, которые не помечены как INTERNAL или ADVANCED. Это эффективно отобразит текущие настройки CMake, которые затем можно изменить с помощью параметра -D. Изменение некоторых переменных может привести к созданию большего количества переменных. Если A указано, то он также отобразит расширенные переменные. Если H указано, то он также отобразит справку для каждой переменной.

-N

Только режим просмотра.

Только загрузить кэш. Не фактически выполнять шаги конфигурации и генерации.

--graphviz=<file>

Сгенерировать граф graphviz зависимостей, см. CMakeGraphVizOptions для более подробной информации.

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

--system-information [file]

Вывести информацию об этой системе.

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

--log-level=<level>

Установите уровень ведения журнала <level>.

Команда message() будет выводить только сообщения указанного уровня журнала или выше. Допустимые уровни журналов — ERROR, WARNING, NOTICE, STATUS (по умолчанию), VERBOSE, DEBUG, или TRACE.

Чтобы сохранить уровень ведения журнала между запусками CMake, установите CMAKE_MESSAGE_LOG_LEVEL в качестве переменной кэша. Если заданы оба параметра командной строки и переменная, приоритет отдаётся параметру командной строки.

Для обеспечения обратной совместимости также принимается --loglevel в качестве синонима этого параметра.

Новое в версии 3.25: См. команду cmake_language() для получения способа получения текущего уровня ведения журнала сообщений.

--log-context

Включить вывод команды message() с контекстом, прикреплённым к каждому сообщению.

Этот параметр включает отображение контекста только для текущего запуска CMake. Чтобы отображение контекста сохранялось для всех последующих запусков CMake, установите CMAKE_MESSAGE_CONTEXT_SHOW в качестве переменной кэша вместо этого. При указании этого параметра командной строки параметр CMAKE_MESSAGE_CONTEXT_SHOW игнорируется.

--debug-trycompile

Не удалять файлы и каталоги, созданные для вызовов try_compile() / try_run(). Это полезно при отладке неудачных проверок.

Обратите внимание, что некоторые использования try_compile() могут использовать ту же структуру сборки, что ограничит полезность этого параметра, если проект выполняет более одного try_compile(). Например, такие использования могут изменить результаты, так как артефакты из предыдущего try-compile могут привести к тому, что тест либо пройдёт, либо не пройдёт неправильно. Этот параметр лучше всего использовать только при отладке.

(В связи с вышесказанным, команда try_run() фактически является try_compile(). Любая комбинация из двух является предметом потенциальных проблем, описанных выше.)

Новое в версии 3.25: При включении этого параметра, каждая проверка try-compile печатает сообщение в журнал, сообщающее о каталоге, в котором выполняется проверка.

--debug-output

Перевести cmake в отладочный режим.

Выводить дополнительную информацию во время выполнения cmake, такие как трассировки стека с вызовами message(SEND_ERROR).

--debug-find

Новое в версии 3.17.

Перевести команды поиска cmake в отладочный режим.

Печатать дополнительную информацию о вызовах поиска во время выполнения cmake в стандартный поток ошибок. Вывод предназначен для чтения человеком, а не для парсинга. Также см. переменную CMAKE_FIND_DEBUG_MODE для отладки более локальной части проекта.

--debug-find-pkg=<pkg>[,...]

Новое в версии 3.23.

Перевести команды поиска cmake в отладочный режим при выполнении вызовов find_package(<pkg>), где <pkg> — запись в заданном списке имён пакетов, разделённых запятыми, регистрозависимая.

Аналогично --debug-find, но ограничивая область действия указанными пакетами.

--debug-find-var=<var>[,...]

Новое в версии 3.23.

Перевести команды поиска cmake в отладочный режим при вызове с <var> в качестве переменной результата, где <var> — запись в заданном списке, разделённом запятыми.

Аналогично --debug-find, но ограничивая область действия указанными именами переменных.

--trace

Перевести cmake в режим трассировки.

Печатать трассировку всех выполненных вызовов и от куда.

--trace-expand

Перевести cmake в режим трассировки.

Как --trace, но с расширенными переменными.

--trace-format=<format>

Новое в версии 3.17.

Перевести cmake в режим трассировки и установить формат вывода трассировки.

<format> может принимать одно из следующих значений.

human

Выводит каждую строку трассировки в удобочитаемом формате. Это формат по умолчанию.

json-v1

Выводит каждую строку как отдельный JSON-документ. Каждый документ отделяется новой строкой ( \n ). Гарантируется, что внутри JSON-документа не будет символов новой строки.

JSON-формат трассировки

{
  "file": "/full/path/to/the/CMake/file.txt",
  "line": 0,
  "cmd": "add_executable",
  "args": ["foo", "bar"],
  "time": 1579512535.9687231,
  "frame": 2,
  "global_frame": 4
}

Элементы:

file

Полный путь к файлу CMake, где была вызвана функция.

line

Строка в file где начался вызов функции.

line_end

Если вызов функции занимает несколько строк, это поле будет установлено в строку, где вызов функции заканчивается. Если вызов функции занимает одну строку, это поле будет отсутствовать. Это поле было добавлено в малой версии 2 формата json-v1.

defer

Необязательное поле, которое присутствует, когда вызов функции был отложен командой cmake_language(DEFER). Если оно присутствует, его значение — строка, содержащая отложенный вызов <id>.

cmd

Имя функции, которая была вызвана.

args

Список строк всех параметров функции.

time

Отметка времени (секунды с начала эпохи) вызова функции.

frame

Глубина кадра стека вызвавшей функции в контексте обрабатываемого в данный момент CMakeLists.txt.

global_frame

Глубина кадра стека вызвавшей функции, отслеживаемая глобально для всех CMakeLists.txt файлов, участвующих в трассировке. Это поле было добавлено в малой версии 2 формата json-v1.

Кроме того, первый JSON-документ, выводимый, содержит поле version для текущей основной и дополнительной версии

JSON-формат версии

{
  "version": {
    "major": 1,
    "minor": 2
  }
}

Элементы:

version

Указывает версию формата JSON. Версия имеет основные и второстепенные компоненты, следуя соглашениям о версионировании semver.

--trace-source=<file>

Перевести cmake в режим трассировки, но выводить только строки указанного файла.

Разрешено несколько параметров.

--trace-redirect=<file>

Перевести cmake в режим трассировки и перенаправить вывод трассировки в файл вместо stderr.

--warn-uninitialized

Выводить предупреждения об инициализированных значениях.

Выводить предупреждение, когда используется неинициализированная переменная.

--warn-unused-vars

Ничего не делает. В версиях CMake 3.2 и ниже это включало предупреждения об неиспользуемых переменных. В версиях CMake 3.3 по 3.18 этот параметр был неисправен. В CMake 3.19 и выше этот параметр был удален.

--no-warn-unused-cli

Не выводить предупреждения о параметрах командной строки.

Не искать переменные, объявленные в командной строке, но не используемые.

--check-system-vars

Поиск проблем с использованием переменных в системных файлах.

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

--compile-no-warning-as-error

Новое в версии 3.24.

Игнорировать свойство целевого объекта COMPILE_WARNING_AS_ERROR и переменную CMAKE_COMPILE_WARNING_AS_ERROR, предотвращая обработку предупреждений как ошибок при компиляции.

--profiling-output=<path>

Новое в версии 3.18.

Используется совместно с --profiling-format для вывода в заданный путь.

--profiling-format=<file>

Включить вывод профилирующей информации скрипта CMake в заданном формате.

Это может помочь в анализе производительности исполняемых скриптов CMake. Для преобразования вывода в читаемый формат должны использоваться сторонние приложения.

В настоящее время поддерживаются значения: google-trace Вывод в формате Google Trace, который можно анализировать с помощью вкладки «about:tracing» в Google Chrome или с помощью плагина для инструмента, такого как Trace Compass.

--preset <preset>, --preset=<preset>

Читает preset из <path-to-source>/CMakePresets.json и <path-to-source>/CMakeUserPresets.json. Пресет может указать генератор и каталог сборки, а также список переменных и других аргументов для передачи CMake. Текущий рабочий каталог должен содержать файлы пресетов CMake. CMake GUI также может распознать файлы CMakePresets.json и CMakeUserPresets.json. Более подробную информацию о этих файлах см. в cmake-presets(7).

Пресеты считываются до всех других параметров командной строки. Параметры, указанные в пресете (переменные, генератор и т. д.), можно переопределить, вручную указав их в командной строке. Например, если пресет устанавливает переменную MYVAR в значение 1, но пользователь устанавливает её в значение 2 с аргументом -D, то значение 2 будет предпочтительным.

--list-presets[=<type>]

Выводит список доступных пресетов указанного <type>. Допустимые значения для <type> — configure, build, test, package, или all. Если <type> опущено, то предполагается configure. Текущий рабочий каталог должен содержать файлы пресетов CMake.

--debugger

Включает интерактивную отладку языка CMake. CMake предоставляет интерфейс отладки на имеющейся в системе трубе, названной --debugger-pipe, соответствующей спецификации Debug Adapter Protocol со следующими изменениями.

Ответ initialize содержит дополнительное поле с именем cmakeVersion, которое указывает версию отлаживаемого CMake.

Debugger initialize response

{
  "cmakeVersion": {
    "major": 3,
    "minor": 27,
    "patch": 0,
    "full": "3.27.0"
  }
}

Члены:

major

Целое число, указывающее номер основной версии.

minor

Целое число, указывающее номер дополнительной версии.

patch

Целое число, указывающее номер патча.

full

Строка, указывающая полную версию CMake.

--debugger-pipe <pipe name>, --debugger-pipe=<pipe name>

Имя трубы (в Windows) или сокета домена (в Unix) для использования в коммуникации с отладчиком.

--debugger-dap-log <log path>, --debugger-dap-log=<log path>

Ведет протокол всех коммуникаций с отладчиком в указанный файл.

Сборка проекта

CMake предоставляет командную строку для сборки уже сгенерированного бинарного дерева проекта:

cmake --build <dir>             [<options>] [-- <build-tool-options>]
cmake --build --preset <preset> [<options>] [-- <build-tool-options>]

Это абстракция командной строки для инструментов native сборки с последующими параметрами:

--build <dir>

Каталог бинарного дерева проекта для сборки. Это обязательно (если не указан пресет) и должно быть первым.

--preset <preset>, --preset=<preset>

Использовать пресет сборки для задания опций сборки. Каталог бинарного дерева проекта определяется из ключа configurePreset. Текущий рабочий каталог должен содержать файлы пресетов CMake. См. preset для получения более подробной информации.

--list-presets

Выводит список доступных пресетов сборки. Текущий рабочий каталог должен содержать файлы пресетов CMake.

-j [<jobs>], --parallel [<jobs>]

Новое в версии 3.12.

Максимальное количество одновременных процессов для сборки. Если <jobs> опущено, используется значение по умолчанию для native инструмента сборки.

Переменная окружения CMAKE_BUILD_PARALLEL_LEVEL, если задана, определяет значение уровня параллели по умолчанию, когда этот параметр не задан.

Некоторые инструменты native сборки всегда выполняют сборку параллельно. Использование значения <jobs> в виде 1 может быть использовано для ограничения до одного задания.

-t <tgt>..., --target <tgt>...

Сборка <tgt> вместо целевого объекта по умолчанию. Можно указать несколько целевых объектов, разделенных пробелами.

--config <cfg>

Для инструментов с несколькими конфигурациями, выбрать конфигурацию <cfg>.

--clean-first

Сначала очистить цель clean, а затем выполнить сборку. (Для очистки только используйте --target clean.)

--resolve-package-references=<value>

Новое в версии 3.23.

Разрешение ссылок на удаленные пакеты из внешних менеджеров пакетов (например, NuGet) до сборки. Когда <value> установлено в значение on (по умолчанию), пакеты будут восстановлены перед сборкой целевого объекта. Когда <value> установлено в значение only, пакеты будут восстановлены, но сборка не будет выполнена. Когда <value> установлено в значение off, пакеты не будут восстановлены.

Если целевой объект не определяет никаких ссылок на пакеты, этот параметр ничего не делает.

Это значение может быть указано в пресете сборки (с помощью resolvePackageReferences). Если параметр командной строки указан, значение пресета будет проигнорировано.

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

При использовании генератора Visual Studio ссылки на пакеты определяются с помощью свойства VS_PACKAGE_REFERENCES. Восстановление пакетов выполняется с помощью NuGet. Это можно отключить, установив переменную CMAKE_VS_NUGET_PACKAGE_RESTORE в значение OFF.

--use-stderr

Проигнорировано. Поведение по умолчанию в CMake >= 3.0.

-v, --verbose

Включить подробный вывод — если поддерживается — включая команды сборки, которые будут выполнены.

Этот параметр можно опустить, если переменная окружения VERBOSE или кэшированная переменная CMAKE_VERBOSE_MAKEFILE задана.

--

Передать оставшиеся параметры в инструмент.

Запустите cmake --build без параметров для получения краткой справки.

Установка проекта

CMake предоставляет команду для установки уже сгенерированного бинарного дерева проекта:

cmake --install <dir> [<options>]

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

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

--install <dir>

Директория установки бинарных файлов проекта. Требуется и должна быть первой.

--config <cfg>

Для генераторов с несколькими конфигурациями, выберите конфигурацию <cfg>.

--component <comp>

Установка по компонентам. Установить только компонент <comp>.

--default-directory-permissions <permissions>

Права доступа по умолчанию для директорий. Формат прав доступа <u=rwx,g=rx,o=rx>.

--prefix <prefix>

Переопределить префикс установки, CMAKE_INSTALL_PREFIX.

--strip

Сжать перед установкой.

-v, --verbose

Включить подробный вывод.

Этот параметр можно опустить, если переменная окружения VERBOSE установлена.

Запустите cmake --install без параметров для получения краткой справки.

Открытие проекта

cmake --open <dir>

Открыть сгенерированный проект в соответствующем приложении. Поддерживается только некоторыми генераторами.

Запуск скрипта

cmake [-D <var>=<value>]... -P <cmake-script-file> [-- <unparsed-options>...]

-D <var>=<value>

Определить переменную для режима скрипта.

-P <cmake-script-file>

Обработать заданный файл CMake как скрипт, написанный на языке CMake. Этап конфигурации или генерации не выполняется, и кеш не изменяется. Если переменные определены с помощью -D, это должно быть сделано перед аргументом -P.

Любые параметры после -- не анализируются CMake, но все же включаются в набор переменных CMAKE_ARGV<n>, переданных в скрипт (включая сам --).

Запуск инструмента командной строки

CMake предоставляет встроенные инструменты командной строки через синтаксис

cmake -E <command> [<options>]

-E [help]

Запустить cmake -E или cmake -E help для получения справки по командам.

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

capabilities

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

Отчет о возможностях cmake в формате JSON. Вывод — это JSON-объект со следующими ключами:

version

JSON-объект с информацией о версии. Ключи:

string

Полная строка версии, отображаемая cmake --version.

major

Главный номер версии в виде целого числа.

minor

Дополнительный номер версии в виде целого числа.

patch

Номер патча в виде целого числа.

suffix

Строка суффикса версии cmake.

isDirty

Булево значение, устанавливаемое, если сборка cmake выполнена из грязного дерева.

generators

Список доступных генераторов. Каждый генератор — JSON-объект со следующими ключами:

name

Строка, содержащая имя генератора.

toolsetSupport

true если генератор поддерживает наборы инструментов и false в противном случае.

platformSupport

true если генератор поддерживает платформы и false в противном случае.

supportedPlatforms

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

Необязательный член, который может присутствовать, если генератор поддерживает указание платформы через CMAKE_GENERATOR_PLATFORM (-A ...). Значение — список известных поддерживаемых платформ.

extraGenerators

Список строк со всеми Дополнительными генераторами, совместимыми с генератором.

fileApi

Необязательный член, который присутствует, если cmake-file-api(7) доступен. Значение — JSON-объект с одним членом:

requests

JSON-массив, содержащий ноль или более поддерживаемых запросов к файловой API. Каждый запрос — JSON-объект с членами:

kind

Указывает один из поддерживаемых видов объектов.

version

JSON-массив, элементы которого представляют собой JSON-объекты, содержащие члены major и minor, определяющие целые числа версий компонентов без знака.

serverMode

true если cmake поддерживает режим сервера, и false в противном случае. Всегда false начиная с CMake 3.20.

tls

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

true если поддержка TLS включена, и false в противном случае.

debugger

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

true если режим --debugger поддерживается, и false в противном случае.

cat [--] <files>...

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

Объединить файлы и вывести на стандартный вывод.

--

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

Добавлена поддержка аргумента с двумя дефисами --. Эта базовая реализация cat не поддерживает никаких параметров, поэтому использование параметра, начинающегося с -, приведет к ошибке. Используйте -- для обозначения конца параметров, если файл начинается с -.

chdir <dir> <cmd> [<arg>...]

Изменить текущую рабочую директорию и запустить команду.

compare_files [--ignore-eol] <file1> <file2>

Проверить, является ли <file1> таким же, как <file2>. Если файлы одинаковы, возвращается 0, в противном случае — 1. В случае неверных аргументов возвращается 2.

--ignore-eol

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

Параметр подразумевает сравнение по строкам и игнорирует различия в разделителях строк LF/CRLF.

copy <file>... <destination>, copy -t <destination> <file>...

Копирует файлы в <destination> (файл или директория). Если указано несколько файлов или задан -t, то <destination> должно быть директорией и она должна существовать. Если -t не указан, последний аргумент предполагается <destination>. Поддержка шаблонов не реализована. copy следует за символьными ссылками. Это означает, что он не копирует символьную ссылку, но копирует файлы или директории, на которые она указывает.

Добавлена в версии 3.5: Поддержка нескольких входных файлов.

Добавлена в версии 3.26: Поддержка аргумента -t.

copy_directory <dir>... <destination>

Копирует содержимое директорий <dir>... в директорию <destination>. Если директория <destination> не существует, она будет создана. copy_directory следует за символьными ссылками.

Добавлена в версии 3.5: Поддержка нескольких входных директорий.

Добавлена в версии 3.15: Команда теперь завершается ошибкой, если исходная директория не существует. Ранее она успешно выполнялась, создавая пустую целевую директорию.

copy_directory_if_different <dir>... <destination>

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

Копирует измененное содержимое директорий <dir>... в директорию <destination>. Если директория <destination> не существует, она будет создана.

copy_directory_if_different следует за символьными ссылками. Команда завершается ошибкой, если исходная директория не существует.

copy_if_different <file>... <destination>

Копирует файлы в <destination> (файл или директория) только если они изменены. Если указано несколько файлов, то <destination> должна быть директорией и должна существовать. copy_if_different следует за символьными ссылками.

Добавлена в версии 3.5: Поддержка нескольких входных файлов.

create_symlink <old> <new>

Создает символическую ссылку <new> с именем <old>.

Добавлена в версии 3.13: Поддержка создания символических ссылок в Windows.

Примечание

Директория, в которую будет создана символическая ссылка <new>, должна существовать предварительно.

create_hardlink <old> <new>

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

Создаёт жёсткую ссылку <new> с именем <old>.

Примечание

Путь, куда будет создана жёсткая ссылка <new>, должен существовать предварительно. Файл <old> должен существовать предварительно.

echo [<string>...]

Отображает аргументы в виде текста.

echo_append [<string>...]

Отображает аргументы в виде текста, но без новой строки.

env [<options>] [--] <command> [<arg>...]

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

Выполняет команду в изменённой среде. Варианты:

NAME=VALUE

Заменяет текущее значение NAME на VALUE.

--unset=NAME

Удаляет текущее значение NAME.

--modify ENVIRONMENT_MODIFICATION

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

Применяет одно ENVIRONMENT_MODIFICATION действие к изменённой среде.

Опции NAME=VALUE и --unset=NAME эквивалентны --modify NAME=set:VALUE и --modify NAME=unset:, соответственно. Обратите внимание, что --modify NAME=reset: сбрасывает NAME до значения, которое оно имело при запуске cmake (или удаляет его), а не до самого последнего значения опции NAME=VALUE.

--

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

Добавлена поддержка аргумента с двойным дефисом --. Используйте -- для остановки интерпретации опций/переменных среды и обработки следующего аргумента как команды, даже если он начинается с - или содержит =.

environment

Отображает текущие переменные среды.

false

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

Не делает ничего, с кодом завершения 1.

make_directory <dir>...

Создаёт директории <dir>. При необходимости создаются и родительские директории. Если директория уже существует, она будет проигнорирована.

Добавлена в версии 3.5: Поддержка нескольких входных директорий.

md5sum <file>...

Создаёт MD5 контрольную сумму файлов в формате, совместимом с md5sum:

351abe79cd3800b38cdfb25d45015a15  file1.txt
052f86c15bbde68af55c7f7b340ab639  file2.txt

sha1sum <file>...

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

Создаёт SHA1 контрольную сумму файлов в формате, совместимом с sha1sum:

4bb7932a29e6f73c97bb9272f2bdc393122f86e0  file1.txt
1df4c8f318665f9a5f2ed38f55adadb7ef9f559c  file2.txt

sha224sum <file>...

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

Создаёт SHA224 контрольную сумму файлов в формате, совместимом с sha224sum:

b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930  file1.txt
6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24  file2.txt

sha256sum <file>...

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

Создаёт SHA256 контрольную сумму файлов в формате, совместимом с sha256sum:

76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc  file1.txt
15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea  file2.txt

sha384sum <file>...

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

Создаёт SHA384 контрольную сумму файлов в формате, совместимом с sha384sum:

acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434  file1.txt
668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d  file2.txt

sha512sum <file>...

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

Создаёт SHA512 контрольную сумму файлов в формате, совместимом с sha512sum:

2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89  file1.txt
7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d  file2.txt

remove [-f] <file>...

Устарело начиная с версии 3.17.

Удаляет файл(ы). Планировалось, что если какой-либо из перечисленных файлов не существует, команда возвращает код ошибки ненулевой, но сообщение не регистрируется. Опция -f меняет поведение на возвращение кода 0 (т.е. успех) в таких ситуациях вместо этого. remove не следует за символьными ссылками. Это означает, что он удаляет только символьную ссылку, а не файлы, на которые она указывает.

Реализация была некорректной и всегда возвращала 0. Ее нельзя исправить без нарушения обратной совместимости. Используйте rm вместо этого.

remove_directory <dir>...

Устарело начиная с версии 3.17.

Удаляет директории <dir> и их содержимое. Если директории не существует, она будет проигнорирована. Используйте rm вместо этого.

Добавлена в версии 3.15: Поддержка нескольких директорий.

Добавлена в версии 3.16: Если <dir> является символьным указателем на директорию, будет удалена только ссылка.

rename <oldname> <newname>

Переименовывает файл или директорию (на одном томе). Если файл с <newname> именем уже существует, он будет заменён без предупреждения.

rm [-rRf] [--] <file|dir>...

Новое в версии 3.17.

Удалить файлы <file> или каталоги <dir>. Используйте -r или -R для рекурсивного удаления каталогов и их содержимого. Если какой-либо из указанных файлов/каталогов не существует, команда возвращает код выхода, отличный от нуля, но сообщение не регистрируется. Опция -f изменяет поведение, чтобы возвращать код выхода 0 (т.е. успех) в таких ситуациях. Используйте -- для остановки интерпретации опций и обработки всех оставшихся аргументов как путей, даже если они начинаются с -.

sleep <number>

Новое в версии 3.0.

Подождать <number> секунд. <number> может быть числом с плавающей точкой. Практический минимум составляет около 0,1 секунды из-за накладных расходов на запуск/остановку исполняемого файла CMake. Это может быть полезно в скрипте CMake для вставки задержки:

# Sleep for about 0.5 seconds
execute_process(COMMAND ${CMAKE_COMMAND} -E sleep 0.5)

tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]

Создать или извлечь архив tar или zip. Доступны следующие опции:

c

Создать новый архив, содержащий указанные файлы. Если используется, аргумент <pathname>... является обязательным.

x

Извлечь из архива на диск.

Новое в версии 3.15: Аргумент <pathname>... может использоваться для извлечения только выбранных файлов или каталогов. При извлечении выбранных файлов или каталогов необходимо указать их точные имена, включая путь, как указано в списке (-t).

t

Показать содержимое архива.

Новое в версии 3.15: Аргумент <pathname>... может использоваться для отображения только выбранных файлов или каталогов.

v

Выводить подробную информацию.

z

Сжать полученный архив с помощью gzip.

j

Сжать полученный архив с помощью bzip2.

J

Новое в версии 3.1.

Сжать полученный архив с помощью XZ.

--zstd

Новое в версии 3.15.

Сжать полученный архив с помощью Zstandard.

--files-from=<file>

Новое в версии 3.1.

Считывать имена файлов из указанного файла, по одному в строке. Пустые строки игнорируются. Строки не могут начинаться с - за исключением --add-file=<name> для добавления файлов, имена которых начинаются с -.

--format=<format>

Новое в версии 3.3.

Указать формат создаваемого архива. Поддерживаемые форматы: 7zip, gnutar, pax, paxr (ограниченный pax, по умолчанию) и zip.

--mtime=<date>

Новое в версии 3.1.

Указать время изменения, записанное в записях tarball.

--touch

Новое в версии 3.24.

Использовать текущее локальное время вместо извлечения времен метки файлов из архива.

--

Новое в версии 3.1.

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

Новое в версии 3.1: Поддержка LZMA (7zip).

Новое в версии 3.15: Команда теперь продолжает добавлять файлы в архив, даже если некоторые файлы недоступны для чтения. Это поведение более согласуется со стандартным инструментом tar . Команда теперь также анализирует все флаги, и если был предоставлен недопустимый флаг, выводится предупреждение.

time <command> [<args>...]

Запустить <command> и отобразить время выполнения (включая накладные расходы переднего фронтенда CMake).

Новое в версии 3.5: Команда теперь правильно передает аргументы с пробелами или специальными символами в дочерний процесс. Это может нарушить работу скриптов, которые обходили ошибку с помощью дополнительной цитирования или экранирования.

touch <file>...

Создаёт <file> если файл не существует. Если <file> существует, изменяются время доступа и изменения <file>.

touch_nocreate <file>...

Изменить время файла, если он существует, но не создавать его. Если файла не существует, он будет проигнорирован.

true

Новое в версии 3.16.

Ничего не делать, с кодом выхода 0.

Инструменты командной строки, специфичные для Windows

Следующие cmake -E команды доступны только в Windows:

delete_regv <key>

Удалить значение в реестре Windows.

env_vs8_wince <sdkname>

Новое в версии 3.2.

Отображает пакетный файл, который задаёт среду для установленного Windows CE SDK в VS2005.

env_vs9_wince <sdkname>

Новое в версии 3.2.

Отображает пакетный файл, который задаёт среду для установленного Windows CE SDK в VS2008.

write_regv <key> <value>

Записать значение в реестре Windows.

Запуск инструмента поиска пакетов

CMake предоставляет помощник pkg-config для проектов на основе Makefile:

cmake --find-package [<options>]

Он ищет пакет, используя find_package() и выводит полученные флаги в stdout. Это можно использовать вместо pkg-config для поиска установленных библиотек в простых проектах на основе Makefile или в проектах на основе autoconf (через share/aclocal/cmake.m4).

Запуск предопределенного рабочего процесса

CMake Presets предоставляет способ выполнения нескольких шагов сборки в определенном порядке:

cmake --workflow [<options>]

Доступные опции:

--workflow

Выберите Пресет рабочего процесса с помощью одной из следующих опций.

--preset <preset>, --preset=<preset>

Используйте пресет рабочего процесса для указания рабочего процесса. Директория бинарных файлов проекта определяется по умолчанию из первоначального предопределения конфигурации. Текущая рабочая директория должна содержать файлы предопределений CMake. Подробнее см. preset.

--list-presets

Отображает доступные пресеты рабочего процесса. Текущая рабочая директория должна содержать файлы предопределений CMake.

--fresh

Выполнить чистую конфигурацию дерева сборки. Это удаляет любой существующий файл CMakeCache.txt и связанную директорию CMakeFiles/, и создаёт их заново.

Просмотр справки

Для печати выбранных страниц документации CMake используйте

cmake --help[-<topic>]

с одной из следующих опций:

-version [<file>], --version [<file>], /V [<file>]

Показать заголовок программы/версии и завершить работу. Вывод печатается в указанный <file> файл, если он задан.

-h, -H, --help, -help, -usage, /?

Вывести информацию об использовании и завершить работу.

Информация об использовании описывает базовый интерфейс командной строки и его опции.

--help <keyword> [<file>]

Вывести справку по одному ключевому слову CMake.

<keyword> может быть свойством, переменной, командой, политикой, генератором или модулем.

Соответствующая запись руководства для <keyword> печатается в удобочитаемом текстовом формате. Вывод печатается в указанный <file> файл, если он задан.

Изменено в версии 3.28: До CMake 3.28 эта опция поддерживала только имена команд.

--help-full [<file>]

Вывести все руководства по справке и завершить работу.

Все руководства печатаются в удобочитаемом текстовом формате. Вывод печатается в указанный <file> файл, если он задан.

--help-manual <man> [<file>]

Вывести одно руководство по справке и завершить работу.

Указанное руководство печатается в удобочитаемом текстовом формате. Вывод печатается в указанный <file> файл, если он задан.

--help-manual-list [<file>]

Вывести список доступных руководств по справке и завершить работу.

Список содержит все руководства, справку по которым можно получить, используя опцию --help-manual и имя руководства. Вывод печатается в указанный <file> файл, если он задан.

--help-command <cmd> [<file>]

Вывести справку по одной команде и завершить работу.

Запись руководства cmake-commands(7) для <cmd> печатается в удобочитаемом текстовом формате. Вывод печатается в указанный <file> файл, если он задан.

--help-command-list [<file>]

Вывести список команд со справочной информацией и завершить работу.

Список содержит все команды, справку по которым можно получить, используя опцию --help-command и имя команды. Вывод печатается в указанный <file> файл, если он задан.

--help-commands [<file>]

Вывести руководство cmake-commands и завершить работу.

Руководство cmake-commands(7) печатается в удобочитаемом текстовом формате. Вывод печатается в указанный <file> файл, если он задан.

--help-module <mod> [<file>]

Вывести справку по одному модулю и завершить работу.

Запись руководства cmake-modules(7) для <mod> печатается в удобочитаемом текстовом формате. Вывод печатается в указанный <file> файл, если он задан.

--help-module-list [<file>]

Вывести список модулей со справочной информацией и завершить работу.

Список содержит все модули, справку по которым можно получить, используя опцию --help-module и имя модуля. Вывод печатается в указанный <file> файл, если он задан.

--help-modules [<file>]

Вывести руководство cmake-modules и завершить работу.

Руководство cmake-modules(7) печатается в удобочитаемом текстовом формате. Вывод печатается в указанный <file> файл, если он задан.

--help-policy <cmp> [<file>]

Вывести справку по одной политике и завершить работу.

Запись руководства cmake-policies(7) для <cmp> печатается в удобочитаемом текстовом формате. Вывод печатается в указанный <file> файл, если он задан.

--help-policy-list [<file>]

Вывести список политик со справочной информацией и завершить работу.

Список содержит все политики, справку по которым можно получить, используя опцию --help-policy и имя политики. Вывод печатается в указанный <file> файл, если он задан.

--help-policies [<file>]

Вывести руководство cmake-policies и завершить работу.

Руководство cmake-policies(7) печатается в удобочитаемом текстовом формате. Вывод печатается в указанный <file> файл, если он задан.

--help-property <prop> [<file>]

Вывести справку по одному свойству и завершить работу.

Записи руководств cmake-properties(7) для <prop> печатаются в удобочитаемом текстовом формате. Вывод печатается в указанный <file> файл, если он задан.

--help-property-list [<file>]

Вывести список свойств со справочной информацией и завершить работу.

Список содержит все свойства, справку по которым можно получить, используя опцию --help-property и имя свойства. Вывод печатается в указанный <file> файл, если он задан.

--help-properties [<file>]

Вывести руководство cmake-properties и завершить работу.

Руководство cmake-properties(7) печатается в удобочитаемом текстовом формате. Вывод печатается в указанный <file> файл, если он задан.

--help-variable <var> [<file>]

Вывести справку по одной переменной и завершить работу.

Запись руководства cmake-variables(7) для <var> печатается в удобочитаемом текстовом формате. Вывод печатается в указанный <file> файл, если он задан.

--help-variable-list [<file>]

Вывести список переменных со справочной информацией и завершить работу.

Список содержит все переменные, справку по которым можно получить, используя опцию --help-variable и имя переменной. Вывод печатается в указанный <file> файл, если он задан.

--help-variables [<file>]

Вывести руководство cmake-variables и завершить работу.

Руководство cmake-variables(7) печатается в удобочитаемом текстовом формате. Вывод печатается в указанный <file> файл, если он задан.

Чтобы просмотреть доступные настройки для проекта, используйте

cmake <source-dir> --list-presets

Значение возврата (код выхода)

При нормальном завершении работа cmake возвращает код выхода 0.

Если завершение вызвано командой message(FATAL_ERROR) или другой ошибкой, возвращается ненулевой код выхода.

См. также

Для получения помощи по использованию CMake доступны следующие ресурсы:

Главная страница

https://cmake.org

Основная точка входа для изучения CMake.

Онлайн-документация и ресурсы сообщества

https://cmake.org/documentation

Ссылки на доступную документацию и ресурсы сообщества можно найти на этой веб-странице.

Форум Discourse

https://discourse.cmake.org

Форум Discourse предназначен для обсуждения и вопросов по CMake.