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/ и пересоздаст их с нуля.

Изменено в версии 3.30: Для зависимостей, ранее заполненных с помощью FetchContent с установкой NEW для политики CMP0168, будут удалены их метки и файлы сценариев из любого предыдущего выполнения. Следовательно, шаги загрузки, обновления и исправления будут вынуждены повторно выполниться.

-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

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

--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 из файлов CMakePresets.json и CMakeUserPresets.json, которые должны находиться в той же директории, что и основной файл CMakeLists.txt. Предварительная настройка может указать генератор, каталог построения, список переменных и другие аргументы для передачи в CMake. По крайней мере, один из файлов CMakePresets.json или CMakeUserPresets.json должен быть присутствовать. CMake GUI также распознает и поддерживает файлы CMakePresets.json и CMakeUserPresets.json. Более подробную информацию об этих файлах см. в cmake-presets(7).

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

--list-presets[=<type>]

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

--debugger

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

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

Ответ отладчика на инициализацию

{
  "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>]

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

--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, определяющие целочисленные компоненты версии не менее 0.

serverMode

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

tls

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

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

debugger

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

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

cat [--] <files>...

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

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

--

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

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

Новое в версии 3.29: 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.

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

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

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

env_vs9_wince <sdkname>

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

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

write_regv <key> <value>

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

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

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

cmake --find-package [<options>]

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

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

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

cmake --workflow [<options>]

Доступны следующие варианты:

--workflow

Выберите Набор параметров процесса, используя один из следующих вариантов.

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

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

--list-presets

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

--fresh

Выполните свежую конфигурацию дерева сборки, что эквивалентно cmake --fresh.

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

Чтобы распечатать выбранные страницы из документации 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.