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

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

defer

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

cmd

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

args

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

time

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

frame

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

global_frame

Глубина кадра стека вызвавшей функции, отслеживаемая глобально для всех файлов CMakeLists.txt , участвующих в трассировке. Это поле было добавлено в версию 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 в противном случае. Всегда 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>

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

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.

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

Отображает пакетный файл, который устанавливает среду для предоставленного 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

Выполнить свежую конфигурацию дерева сборки. Это удаляет любой существующий 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.