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>

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

--install-prefix <directory>

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

-Wno-dev

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

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

-Wdev

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

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

-Wdeprecated

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

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

-Wno-deprecated

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

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

-Werror=<what>

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

dev

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

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

deprecated

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

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

-Wno-error=<what>

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

dev

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

deprecated

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

--fresh

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

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

-L[A][H]

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

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

-N

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

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

--graphviz=<file>

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

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

--system-information [file]

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

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

--log-level=<level>

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

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

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

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

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

--log-context

Включить вывод контекста для каждой команды message().

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

--debug-trycompile

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

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

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

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

--debug-output

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

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

--debug-find

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

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

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

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

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

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

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

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

--trace

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

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

--trace-expand

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

Подобно --trace, но с подстановкой переменных.

--trace-format=<format>

Включить режим трассировки CMake и установить формат вывода трассировки.

<format> может принимать одно из следующих значений.

human

Выводит каждую строку трассировки в читаемом формате. Это формат по умолчанию.

json-v1

Выводит каждую строку как отдельную JSON-документ. Документы разделены новой строкой ( \n ). Гарантируется, что внутри JSON-документа не будет символов новой строки.

JSON-формат трассировки

{
  "file": "/full/path/to/the/CMake/file.txt",
  "line": 0,
  "cmd": "add_executable",
  "args": ["foo", "bar"],
  "time": 1579512535.9687231,
  "frame": 2,
  "global_frame": 4
}

Поля:

file

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

line

Строка в file , где начинается вызов функции.

line_end

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

defer

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

cmd

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

args

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

time

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

frame

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

global_frame

Глубина кадра стека функции, которая была вызвана, отслеживаемая глобально для всех файлов CMakeLists.txt , участвующих в трассировке. Это поле было добавлено в малой версии 2 формата json-v1.

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

Формат версии JSON

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

Поля:

version

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

--trace-source=<file>

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

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

--trace-redirect=<file>

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

--warn-uninitialized

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

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

--warn-unused-vars

Не выполняет никаких действий. В версиях CMake 3.2 и ниже этот параметр активировал предупреждения об unused переменных. В версиях 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, который можно проанализировать в вкладке «about:tracing» браузера 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.

Debugger initialize response

{
  "cmakeVersion": {
    "major": 3,
    "minor": 27,
    "patch": 0,
    "full": "3.27.0"
  }
}

Члены:

major

Целое число, указывающее номер основной версии.

minor

Целое число, указывающее номер дополнительной версии.

patch

Целое число, указывающее номер патча.

full

Строка, указывающая полную версию CMake.

--debugger-pipe <pipe name>, --debugger-pipe=<pipe name>

Имя канала (в Windows) или сокета домена (в Unix) для использования в коммуникации с отладчиком.

--debugger-dap-log <log path>, --debugger-dap-log=<log path>

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

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

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

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

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

--build <dir>

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

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

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

--list-presets

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

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

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

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

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

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

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

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

--config <cfg>

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

--clean-first

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

--resolve-package-references=<value>

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

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

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

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

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

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

--use-stderr

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

-v, --verbose

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

Этот параметр можно опустить, если переменная окружения VERBOSE или кэшированная переменная CMAKE_VERBOSE_MAKEFILE установлена.

--

Передать оставшиеся параметры инструменту.

Запустите cmake --build без опций для получения краткой справки.

Установить проект

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

cmake --install <dir> [<options>]

Это может быть использовано после сборки проекта для выполнения установки без использования сгенерированной системы сборки или системного инструмента сборки. Доступные опции:

--install <dir>

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

--config <cfg>

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

--component <comp>

Установка по компонентам. Установить только компонент <comp>.

--default-directory-permissions <permissions>

Права доступа для установки по умолчанию. Права в формате <u=rwx,g=rx,o=rx>.

--prefix <prefix>

Переопределить префикс установки, CMAKE_INSTALL_PREFIX.

--strip

Сжать перед установкой.

-v, --verbose

Включить подробный вывод.

Эта опция может быть опущена, если переменная окружения VERBOSE задана.

Запустите cmake --install без опций для получения краткой справки.

Открыть проект

cmake --open <dir>

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

Выполнить скрипт

cmake [-D <var>=<value>]... -P <cmake-script-file> [-- <unparsed-options>...]

-D <var>=<value>

Определить переменную для режима скрипта.

-P <cmake-script-file>

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

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

Запустить командную утилиту

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

cmake -E <command> [<options>]

-E [help]

Запустите cmake -E или cmake -E help для получения сводки команд.

Доступные команды:

capabilities

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

Отчет о возможностях cmake в формате JSON. Вывод – это JSON-объект со следующими ключами:

version

JSON-объект с информацией о версии. Ключи:

string

Полная строка версии, отображаемая cmake --version.

major

Основной номер версии в целочисленной форме.

minor

Дополнительный номер версии в целочисленной форме.

patch

Номер патча в целочисленной форме.

suffix

Строка суффикса версии cmake.

isDirty

Булево значение, установленное, если сборка cmake выполняется из модифицированного дерева.

generators

Список доступных генераторов. Каждый генератор – это JSON-объект со следующими ключами:

name

Строка, содержащая имя генератора.

toolsetSupport

true если генератор поддерживает наборы инструментов, и false в противном случае.

platformSupport

true если генератор поддерживает платформы, и false в противном случае.

supportedPlatforms

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

Дополнительный член, который может присутствовать, когда генератор поддерживает указание платформы через CMAKE_GENERATOR_PLATFORM (-A ...). Значение – это список известных поддерживаемых платформ.

extraGenerators

Список строк со всеми Дополнительными генераторами, совместимыми с генератором.

fileApi

Необязательный член, который присутствует, когда cmake-file-api(7) доступен. Значение – это JSON-объект с одним членом:

requests

JSON-массив, содержащий ноль или более поддерживаемых запросов file-api. Каждый запрос – это JSON-объект с членами:

kind

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

version

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

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

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 в значение null.

--modify ENVIRONMENT_MODIFICATION

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

Применить одно ENVIRONMENT_MODIFICATION операцию к изменённой среде.

Опции NAME=VALUE и --unset=NAME эквивалентны --modify NAME=set:VALUE и --modify NAME=unset:, соответственно. Обратите внимание, что --modify NAME=reset: сбрасывает NAME до значения, которое было при запуске cmake (или устанавливает его в null), а не к последнему значению опции NAME=VALUE.

--

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

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

environment

Отобразить текущие переменные среды.

false

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

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

make_directory <dir>...

Создать каталоги <dir>. При необходимости создаются также родительские каталоги. Если каталог уже существует, он будет проигнорирован.

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

md5sum <file>...

Создать контрольную сумму MD5 файлов в формате, совместимом с md5sum:

351abe79cd3800b38cdfb25d45015a15  file1.txt
052f86c15bbde68af55c7f7b340ab639  file2.txt

sha1sum <file>...

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

Создать контрольную сумму SHA1 файлов в формате, совместимом с sha1sum:

4bb7932a29e6f73c97bb9272f2bdc393122f86e0  file1.txt
1df4c8f318665f9a5f2ed38f55adadb7ef9f559c  file2.txt

sha224sum <file>...

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

Создать контрольную сумму SHA224 файлов в формате, совместимом с sha224sum:

b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930  file1.txt
6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24  file2.txt

sha256sum <file>...

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

Создать контрольную сумму SHA256 файлов в формате, совместимом с sha256sum:

76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc  file1.txt
15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea  file2.txt

sha384sum <file>...

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

Создать контрольную сумму SHA384 файлов в формате, совместимом с sha384sum:

acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434  file1.txt
668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d  file2.txt

sha512sum <file>...

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

Создать контрольную сумму SHA512 файлов в формате, совместимом с sha512sum:

2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89  file1.txt
7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d  file2.txt

remove [-f] <file>...

Устаревшая начиная с версии 3.17.

Удалить файлы. Предполагалось, что если хотя бы один из перечисленных файлов не существует, команда возвращает ненулевой код выхода, но никаких сообщений не регистрируется. Опция -f изменяет поведение, чтобы возвращать нулевой код выхода (т.е. успех) в таких ситуациях вместо этого. Опция remove не следует за символическими ссылками. Это означает, что она удаляет только символические ссылки, а не файлы, на которые они указывают.

Реализация была ошибочной и всегда возвращала 0. Исправить её нельзя без нарушения обратной совместимости. Используйте rm вместо этого.

remove_directory <dir>...

Устаревшая начиная с версии 3.17.

Удалить каталоги <dir> и их содержимое. Если каталог не существует, он будет проигнорирован. Используйте rm вместо этого.

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

Новое в версии 3.16: Если <dir> является символической ссылкой на каталог, будет удалена только символическая ссылка.

rename <oldname> <newname>

Переименовать файл или каталог (на одном томе). Если файл с именем <newname> уже существует, он будет молча заменён.

rm [-rRf] [--] <file|dir>...

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

Удалить файлы <file> или каталоги <dir>. Используйте -r или -R для рекурсивного удаления каталогов и их содержимого. Если какой-либо из перечисленных файлов/каталогов не существует, команда возвращает ненулевой код выхода, но никаких сообщений не регистрируется. Опция -f изменяет поведение, чтобы возвращать нулевой код выхода (т.е. успех) в таких ситуациях вместо этого. Используйте -- для остановки интерпретации опций и обработки всех оставшихся аргументов как путей, даже если они начинаются с -.

sleep <number>

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

Задержка на <number> секунд. <number> может быть числом с плавающей точкой. Практический минимум составляет около 0,1 секунды из-за накладных расходов на запуск/остановку исполняемого файла CMake. Это может быть полезно в скрипте CMake для вставки задержки:

# Sleep for about 0.5 seconds
execute_process(COMMAND ${CMAKE_COMMAND} -E sleep 0.5)

tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]

Создать или извлечь архив tar или zip. Доступны следующие параметры:

c

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

x

Извлечь файлы из архива.

Новое в версии 3.15: Аргумент <pathname>... может быть использован для извлечения только выбранных файлов или каталогов. При извлечении выбранных файлов или каталогов необходимо указать их точные имена, включая путь, как указано в списке (-t).

t

Вывести содержимое архива.

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

v

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

z

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

j

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

J

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

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

--zstd

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

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

--files-from=<file>

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

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

--format=<format>

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

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

--mtime=<date>

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

Указать время изменения, записанное в записях 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.

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

env_vs9_wince <sdkname>

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

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

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