cmake(1)

Краткое описание

Generate a Project Buildsystem
 cmake [<options>] <path-to-source | path-to-existing-build>
 cmake [<options>] -S <path-to-source> -B <path-to-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>] <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 .

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

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

$ cmake -S src -B build

Во всех случаях <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>

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

--install-prefix <directory>

Указать каталог установки, используемый переменной 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_run() фактически является try_compile(). Любая комбинация этих двух команд подвержена потенциальным проблемам, описанным выше.)

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

--debug-output

Включить режим отладки CMake.

Печать дополнительной информации во время выполнения CMake, например, трассировки стека с вызовами message(SEND_ERROR).

--debug-find

Включить режим отладки для команд поиска CMake.

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

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

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

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

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

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

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

--trace

Включить режим трассировки CMake.

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

--trace-expand

Включить режим трассировки CMake.

Аналогично --trace, но с раскрытыми переменными.

--trace-format=<format>

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

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

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

--profiling-output=<path>

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

--profiling-format=<file>

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

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

В настоящее время поддерживаются следующие значения: google-trace Вывод в формате Google Trace, который можно проанализировать с помощью вкладки «Прослеживание» в 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 должны находиться в текущей рабочей директории.

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

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

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

Это абстрагирует интерфейс командной строки утилиты сборки с помощью следующих параметров:

--build <dir>

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

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

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

--list-presets

Отображает список доступных пресетов сборки. Файлы пресетов CMake должны находиться в текущей рабочей директории.

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

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

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

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

Некоторые утилиты сборки всегда работают параллельно. Можно использовать значение <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-массив, содержащий ноль или более поддерживаемых запросов file-api. Каждый запрос — JSON-объект с членами:

kind

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

version

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

serverMode

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

tls

Новая в версии 3.25.

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

sleep <number>...

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

Подождать заданное количество секунд.

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.

Указать время изменения, которое будет записано в записи архива tar.

--touch

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

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

--

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

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

Добавлен в версии 3.1: Поддержка LZMA (7zip).

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

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

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

Добавлен в версии 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() и выводит полученные флаги в стандартный вывод. Это можно использовать вместо pkg-config для поиска установленных библиотек в простых проектах на основе Makefile или в проектах на основе autoconf (через share/aclocal/cmake.m4).

Запуск набора действий (Workflow)

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-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.