cmake(1)

Синтаксис

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

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

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

Open a Project
 cmake --open <dir>

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

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

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

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

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

Описание

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

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

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

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

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

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

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

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

Дерево исходного кода

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

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

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

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

Генератор

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

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

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

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

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

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

$ cmake -S src -B build

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

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

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

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

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

$ cd build
$ cmake .

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

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

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

$ make
$ make install

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

Параметры

-S <path-to-source>

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

-B <path-to-build>

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

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

-C <initial-cache>

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

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

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

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

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

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

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

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

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

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

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

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

-U <globbing_expr>

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

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

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

-G <generator-name>

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

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

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

-T <toolset-spec>

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

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

-A <platform-name>

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

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

--toolchain <path-to-file>

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

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

--install-prefix <directory>

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

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

-Wno-dev

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

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

-Wdev

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

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

-Wdeprecated

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

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

-Wno-deprecated

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

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

-Werror=<what>

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

dev

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

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

deprecated

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

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

-Wno-error=<what>

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

dev

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

deprecated

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

--fresh

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

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

-L[A][H]

Отобразить не-расширенные кэшированные переменные.

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

-N

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

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

--graphviz=<file>

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

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

--system-information [file]

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

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

--log-level=<level>

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

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

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

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

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

--log-context

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

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

--debug-trycompile

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

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

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

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

--debug-output

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

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

--debug-find

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

Перевести cmake find-команды в режим отладки.

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

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

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

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

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

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

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

Перевести cmake find-команды в режим отладки при вызове с <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, который можно проанализировать в вкладке «Отслеживание» в Google Chrome или с помощью плагина для инструмента, такого как Trace Compass.

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

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

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

--list-presets[=<type>]

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

--debugger

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

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

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

{
  "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-массив, содержащий ноль или более поддерживаемых запросов к файловой API. Каждый запрос — это JSON-объект с членами:

kind

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

version

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

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

t

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

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

v

Вывести подробный вывод.

z

Сжать создаваемый архив с помощью gzip.

j

Сжать создаваемый архив с помощью bzip2.

J

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

Сжать создаваемый архив с помощью XZ.

--zstd

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

Сжать создаваемый архив с помощью Zstandard.

--files-from=<file>

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

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

--format=<format>

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

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

--mtime=<date>

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

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

--touch

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

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

--

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

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

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

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

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

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

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

touch <file>...

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

touch_nocreate <file>...

Отмечает файл, если он существует, но не создаёт его. Если файл не существует, он будет проигнорирован.

true

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

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

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

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

delete_regv <key>

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

env_vs8_wince <sdkname>

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

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

env_vs9_wince <sdkname>

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

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

write_regv <key> <value>

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

Использование инструмента Find-Package

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