cmake(1)

Синопсис

Generate a Project Buildsystem
 cmake [<options>] <path-to-source>
 cmake [<options>] <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>]

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

-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. По умолчанию это также включит предупреждения об устаревании.

-Werror=dev

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

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

-Wno-error=dev

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

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

-Wdeprecated

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

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

-Wno-deprecated

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

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

-Werror=deprecated

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

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

-Wno-error=deprecated

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

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

-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=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>

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

Команда message() будет выводить сообщения только указанного уровня журнала или выше. Уровень журнала по умолчанию STATUS.

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

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

--log-context

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

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

--debug-trycompile

Не удаляйте дерево сборки try_compile(). Полезно только для одной try_compile() за раз.

Не удаляйте файлы и каталоги, созданные для вызовов try_compile(). Это полезно при отладке неудачных вызовов try_compiles. Однако это может изменить результаты try-compiles, так как старый мусор из предыдущего try-compile может привести к неверному успеху или провалу теста. Этот параметр лучше всего использовать для одного 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
}

Поля:

file

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

line

Строка в file вызова функции.

defer

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

cmd

Имя вызываемой функции.

args

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

time

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

frame

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

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

Формат трассировки JSON:

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

Поля:

version

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

--trace-source=<file>

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

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

--trace-redirect=<file>

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

--warn-uninitialized

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

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

--warn-unused-vars

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

--no-warn-unused-cli

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

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

--check-system-vars

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

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

--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, --list-presets=<[configure | build | test | all]>

Отображает доступные пресеты. Если параметр не указан, будут отображаться только пресеты конфигурации. Текущий рабочий каталог должен содержать файлы пресетов 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.

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

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

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

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

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

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

--config <cfg>

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

--clean-first

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

--resolve-package-references=<on|off|only>

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

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

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

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

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

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

--use-stderr

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

--verbose, -v

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

Этот параметр можно опустить, если переменная среды 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>...]

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

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

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

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

cmake -E <command> [<options>]

Запустите 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.

cat <files>...

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

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

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

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

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

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

Новое в версии 3.14: Опция --ignore-eol подразумевает сравнение по строкам и игнорирует различия LF/CRLF.

copy <file>... <destination>

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

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

copy_directory <dir>... <destination>

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

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

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

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 [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...

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

Запустить команду в изменённой среде.

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 изменяет поведение, возвращая нулевой код выхода (т.е. успех) в таких ситуациях.

server

Запустить cmake-server(7) режим.

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.

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

--

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

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

env_vs9_wince <sdkname>

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

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

write_regv <key> <value>

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

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

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

cmake --find-package [<options>]

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

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

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

cmake --help[-<topic>]

с одним из следующих вариантов:

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

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

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

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

Показать баннер с именем/версией программы и выйти.

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

--help-full [<f>]

Вывести все руководства по помощи и выйти.

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

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

Вывести одно руководство по помощи и выйти.

Указанное руководство выводится в удобочитаемом текстовом формате. Помощь выводится в указанный файл <f>, если он задан.

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

Вывести список доступных руководств по помощи и выйти.

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

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

Вывести помощь по одной команде и выйти.

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

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

Вывести список команд с доступной помощью и выйти.

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

--help-commands [<f>]

Вывести руководство cmake-commands и выйти.

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

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

Вывести помощь по одному модулю и выйти.

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

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

Вывести список модулей с доступной помощью и выйти.

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

--help-modules [<f>]

Вывести руководство cmake-modules и выйти.

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

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

Вывести помощь по одной политике и выйти.

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

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

Вывести список политик с доступной помощью и выйти.

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

--help-policies [<f>]

Вывести руководство cmake-policies и выйти.

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

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

Вывести помощь по одному свойству и выйти.

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

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

Вывести список свойств с доступной помощью и выйти.

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

--help-properties [<f>]

Вывести руководство cmake-properties и выйти.

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

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

Вывести помощь по одной переменной и выйти.

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

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

Вывести список переменных с доступной помощью и выйти.

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

--help-variables [<f>]

Вывести руководство cmake-variables и выйти.

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

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

cmake <source-dir> --list-presets

См. также

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

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

https://cmake.org

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

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

https://cmake.org/documentation

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

Форум Discourse

https://discourse.cmake.org

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