Руководство по взаимодействию с пользователем

• Введение

  • Инструмент cmake в командной строке
  • Инструмент cmake-gui

• Генерация системы сборки

  • Окружение командной строки
  • Опция командной строки -G
  • Выбор генератора в cmake-gui

• Установка переменных сборки

  • Установка переменных в командной строке
  • Установка переменных с помощью cmake-gui
  • Кэш CMake

• Пресеты

  • Использование пресетов в командной строке
  • Использование пресетов в cmake-gui

• Вызов системы сборки

  • Выбор цели
  • Указание программы сборки
• Установка программного обеспечения
• Запуск тестов

Введение

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

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

Сгенерированные системы сборки обычно следует рассматривать как только для чтения. Файлы CMake как основной артефакт должны полностью определять систему сборки, и нет причин заполнять свойства вручную в IDE, например, после генерации системы сборки. CMake будет периодически переписывать сгенерированную систему сборки, поэтому изменения, внесённые пользователем, будут перезаписаны.

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

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

Инструмент cmake в командной строке

Простой, но типичный способ использования cmake(1) с новой копией исходного кода программного обеспечения заключается в создании каталога сборки и вызове cmake там:

$ cd some_software-1.4.2
$ mkdir build
$ cd build
$ cmake .. -DCMAKE_INSTALL_PREFIX=/opt/the/prefix
$ cmake --build .
$ cmake --build . --target install

Рекомендуется выполнять сборку в отдельном каталоге от исходного кода, так как это позволяет сохранить исходный каталог неизменным, позволяет сборку одного исходного кода с несколькими инструментальными цепочками и упрощает очистку артефактов сборки путём простого удаления каталога сборки.

Инструменты CMake могут сообщать об ошибках, которые предназначены для поставщика программного обеспечения, а не для потребителя программного обеспечения. Такие предупреждения заканчиваются фразой «Это предупреждение для разработчиков проекта». Пользователи могут отключить такие предупреждения, передав флаг -Wno-dev инструменту cmake(1).

Инструмент cmake-gui

Пользователи, более привыкшие к графическим интерфейсам, могут использовать инструмент cmake-gui(1) для вызова CMake и генерации системы сборки.

Сначала необходимо заполнить каталоги исходного кода и двоичных файлов. Всегда рекомендуется использовать разные каталоги для исходного кода и каталога сборки.

Генерация системы сборки

Существуют несколько инструментов пользовательского интерфейса, которые могут быть использованы для генерации системы сборки из файлов CMake. Инструменты ccmake(1) и cmake-gui(1) направляют пользователя по установке различных необходимых параметров. Инструмент cmake(1) может быть вызван для указания параметров в командной строке. Это руководство описывает параметры, которые могут быть установлены с помощью любого из инструментов пользовательского интерфейса, хотя способ установки параметра отличается для каждого инструмента.

Окружение командной строки

При вызове cmake(1) с системой сборки командной строки, такой как Makefiles или Ninja, необходимо использовать правильную среду сборки, чтобы убедиться, что инструменты сборки доступны. CMake должен иметь возможность найти соответствующую программу build tool, компилятор, компоновщик и другие необходимые инструменты.

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

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

Visual Studio поставляется с несколькими командными подсказками и скриптами vcvarsall.bat для настройки правильных сред для систем сборки командной строки. Хотя строго не обязательно использовать соответствующую среду командной строки при использовании генератора Visual Studio, это не приведёт к негативным последствиям.

При использовании Xcode может быть установлено более одной версии Xcode. Какую использовать, можно выбрать несколькими способами, но наиболее распространённые методы:

• Установление значения по умолчанию в настройках IDE Xcode.
• Установка значения по умолчанию через инструмент командной строки xcode-select.
• Переопределение значения по умолчанию путём установки переменной среды DEVELOPER_DIR при запуске CMake и инструмента сборки.

Для удобства cmake-gui(1) предоставляет редактор переменных среды.

Опция командной строки -G

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

Пользователь может переопределить генератор по умолчанию с помощью опции -G:

$ cmake .. -G Ninja

Вывод cmake --help включает список generators, доступных для выбора пользователем. Обратите внимание, что имена генераторов чувствительны к регистру.

В системах Unix-подобных системах (включая Mac OS X) по умолчанию используется генератор Unix Makefiles. Вариант этого генератора также может использоваться в Windows в различных средах, таких как генераторы NMake Makefiles и MinGW Makefiles. Эти генераторы генерируют вариант Makefile, который можно выполнить с помощью make, gmake, nmake или аналогичных инструментов. Дополнительную информацию о целевых средах и инструментах см. в документации по соответствующим генераторам.

Генератор Ninja доступен на всех основных платформах. ninja — это инструмент сборки, похожий по целевому назначению на make, но с упором на производительность и эффективность.

В Windows, cmake(1) может быть использован для генерации решений для IDE Visual Studio. Версии Visual Studio могут быть указаны по имени продукта IDE, которое включает четырёхзначный год. Для других способов ссылки на версии Visual Studio, таких как двухзначная цифра, соответствующая версии продукта компилятора VisualC++, или комбинация обоих, предоставляются псевдонимы:

$ cmake .. -G "Visual Studio 2019"
$ cmake .. -G "Visual Studio 16"
$ cmake .. -G "Visual Studio 16 2019"

Генераторы Visual Studio могут нацеливаться на различные архитектуры. Архитектуру цели можно указать с помощью опции -A:

cmake .. -G "Visual Studio 2019" -A x64
cmake .. -G "Visual Studio 16" -A ARM
cmake .. -G "Visual Studio 16 2019" -A ARM64

В Apple используется генератор Xcode, чтобы генерировать файлы проекта для IDE Xcode.

Некоторые IDE, такие как KDevelop4, QtCreator и CLion, имеют встроенную поддержку систем сборки на основе CMake. Эти IDE предоставляют интерфейс пользователя для выбора используемого генератора, обычно между генератором на основе Makefile и генератором на основе Ninja.

Обратите внимание, что изменить генератор с помощью -G после первого вызова CMake невозможно. Чтобы изменить генератор, необходимо удалить директорию сборки и начать сборку заново.

При генерации файлов проекта и решений Visual Studio доступно несколько дополнительных опций при первоначальном запуске cmake(1).

Набор инструментов Visual Studio можно указать с помощью опции -T:

$ # Build with the clang-cl toolset
$ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T ClangCL
$ # Build targeting Windows XP
$ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T v120_xp

В то время как опция -A указывает целевую архитектуру, опция -T может быть использована для указания деталей используемой цепочки инструментов. Например, -Thost=x64 можно использовать для выбора 64-битной версии инструментов хоста. Ниже показано, как использовать 64-битные инструменты и также создать сборку для 64-битной целевой архитектуры:

$ cmake .. -G "Visual Studio 16 2019" -A x64 -Thost=x64

Выбор генератора в cmake-gui

Кнопка "Настроить" запускает новое диалоговое окно для выбора генератора CMake.

Все генераторы, доступные в командной строке, также доступны в cmake-gui(1).

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

Установка переменных сборки

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

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

CMake не предоставляет соглашения об именовании таких переменных между различными системами сборки, за исключением того, что переменные с префиксом CMAKE_ обычно относятся к параметрам, предоставляемым самим CMake, и не должны использоваться в параметрах сторонних разработчиков, которые должны использовать свой собственный префикс вместо этого. Инструмент cmake-gui(1) может отображать параметры группами, определяемыми их префиксом, поэтому сторонним разработчикам имеет смысл убедиться, что они используют самосогласованный префикс.

Установка переменных в командной строке

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

$ mkdir build
$ cd build
$ cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Debug

или позже при последующем вызове cmake(1):

$ cd build
$ cmake . -DCMAKE_BUILD_TYPE=Debug

Флаг -U может использоваться для сброса переменных в командной строке cmake(1):

$ cd build
$ cmake . -UMyPackage_DIR

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

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

Установка переменных с помощью cmake-gui

Переменные можно установить в cmake-gui с помощью кнопки "Добавить запись". Это запускает новое диалоговое окно для установки значения переменной.

Основное окно интерфейса пользователя cmake-gui(1) можно использовать для редактирования существующих переменных.

Кэш CMake

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

При первом запуске CMake генерирует файл CMakeCache.txt в директории сборки, содержащий пары "ключ-значение" для таких артефактов. Пользователь может просмотреть или изменить файл кэша, запустив инструмент cmake-gui(1) или ccmake(1). Инструменты предоставляют интерактивный интерфейс для переконфигурации предоставленного программного обеспечения и перегенерации системы сборки, как это необходимо после редактирования значений кэша. Для каждой записи кэша может быть связан короткий текст справки, который отображается в пользовательском интерфейсе инструментов.

Записи кэша также могут иметь тип, чтобы указать, как они должны быть представлены в пользовательском интерфейсе. Например, запись кэша типа BOOL может быть отредактирована с помощью флажка в пользовательском интерфейсе, STRING может быть отредактирована в поле ввода, а FILEPATH, хотя и похож на STRING, также должен предоставить способ поиска путей к файловой системе с помощью диалогового окна выбора файла. Запись типа STRING может предоставить ограниченный список допустимых значений, которые затем будут представлены в выпадающем меню в пользовательском интерфейсе cmake-gui(1) (см. свойство кэша STRINGS).

Файлы CMake, поставляемые с пакетом программного обеспечения, также могут определять логические параметры переключателей с помощью команды option(). Команда создает запись в кэше, которая имеет текст справки и значение по умолчанию. Такие записи в кэше обычно специфичны для предоставляемого программного обеспечения и влияют на конфигурацию сборки, например, на то, собирать ли тесты и примеры, собирать ли с поддержкой исключений и т. д.

Наборы параметров

CMake понимает файл CMakePresets.json и его пользовательский аналог CMakeUserPresets.json для сохранения наборов параметров для часто используемых настроек конфигурации. Эти наборы параметров могут устанавливать директорию сборки, генератор, переменные кэша, переменные среды и другие параметры командной строки. Все эти параметры могут быть переопределены пользователем. Полные детали формата CMakePresets.json перечислены в руководстве cmake-presets(7).

Использование наборов параметров в командной строке

При использовании командной утилиты cmake(1), предустановку можно вызвать, используя опцию --preset. Если указана --preset, то директории генератора и сборки не требуются, но могут быть указаны для их переопределения. Например, если у вас есть следующий файл CMakePresets.json:

{
  "version": 1,
  "configurePresets": [
    {
      "name": "ninja-release",
      "binaryDir": "${sourceDir}/build/${presetName}",
      "generator": "Ninja",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Release"
      }
    }
  ]
}

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

cmake -S /path/to/source --preset=ninja-release

Это сгенерирует директорию сборки в /path/to/source/build/ninja-release с генератором Ninja и с CMAKE_BUILD_TYPE, установленным в значение Release.

Если вы хотите увидеть список доступных предустановок, вы можете выполнить:

cmake -S /path/to/source --list-presets

Это отобразит список предустановок, доступных в /path/to/source/CMakePresets.json и /path/to/source/CMakeUsersPresets.json, без генерации дерева сборки.

Использование предустановок в cmake-gui

Если у проекта есть доступные предустановки, либо через CMakePresets.json, либо через CMakeUserPresets.json, список предустановок появится в выпадающем меню в cmake-gui(1) между директорией исходного кода и директорией бинарных файлов. Выбор предустановки задает директорию бинарных файлов, генератор, переменные среды и переменные кэша, но все эти параметры могут быть переопределены после выбора предустановки.

Вызов системы сборки

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

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

$ cmake --build .

Флаг --build включает определённый режим работы для утилиты cmake(1). Он вызывает команду CMAKE_MAKE_PROGRAM, связанную с генератором generator, или инструментом сборки, настроенным пользователем.

Режим --build также принимает параметр --target для указания конкретной цели сборки, например, конкретной библиотеки, исполняемого файла или пользовательской цели, или конкретной специальной цели, такой как install:

$ cmake --build . --target myexe

Режим --build также принимает параметр --config в случае генераторов с несколькими конфигурациями, чтобы указать, какую именно конфигурацию необходимо собрать:

$ cmake --build . --target myexe --config Release

Опция --config не имеет эффекта, если генератор создаёт систему сборки, специфичную для конфигурации, которая выбирается при вызове cmake с переменной CMAKE_BUILD_TYPE.

Некоторые системы сборки пропускают подробности командных строк, вызываемых во время сборки. Флаг --verbose может быть использован для отображения этих командных строк:

$ cmake --build . --target myexe --verbose

Режим --build также может передавать определённые параметры командной строки в основной инструмент сборки, перечисляя их после --. Это может быть полезно для указания параметров инструменту сборки, например, для продолжения сборки после завершения неудачной задачи, где CMake не предоставляет удобный пользовательский интерфейс.

Для всех генераторов возможно запустить основной инструмент сборки после вызова CMake. Например, make может быть выполнен после генерации с генератором Unix Makefiles для вызова сборки, или ninja после генерации с генератором Ninja и т. д. Системы сборки IDE обычно предоставляют инструменты командной строки для сборки проекта, которые также можно вызвать.

Выбор цели

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

CMake предоставляет некоторые встроенные цели для всех систем сборки, предоставляющих файлы CMake.

all

Целевая сборка по умолчанию, используемая генераторами Makefile и Ninja. Сборка всех целей в системе сборки, за исключением тех, которые исключены своим свойством цели EXCLUDE_FROM_ALL или свойством директории EXCLUDE_FROM_ALL. Имя ALL_BUILD используется для этой цели для генераторов Xcode и Visual Studio.

help

Отображает доступные для сборки цели. Эта цель доступна при использовании генераторов Unix Makefiles или Ninja, а точный вывод зависит от инструмента.

clean

Удаляет скомпилированные файлы объектов и другие выходные файлы. Генераторы на основе Makefile создают целевую сборку clean на каждый каталог, чтобы можно было очистить отдельный каталог. Инструмент Ninja предоставляет собственную систему гранулированной очистки -t clean.

test

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

install

Устанавливает программное обеспечение. Эта цель доступна только в том случае, если файлы CMake определяют правила установки с помощью команды install(). См. также Установка программного обеспечения.

package

Создаёт двоичный пакет. Эта цель доступна только в том случае, если файлы CMake предоставляют пакеты на основе CPack.

package_source

Создаёт исходный пакет. Эта цель доступна только в том случае, если файлы CMake предоставляют пакеты на основе CPack.

Для систем на основе Makefile предоставляются варианты целевых сборок двоичных файлов /fast. Варианты /fast используются для сборки указанной цели без учёта зависимостей. Зависимости не проверяются и не пересобираются, если они устарели. Генератор Ninja достаточно быстро проверяет зависимости, поэтому такие цели не предоставляются для этого генератора.

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

$ make foo.cpp.i
$ make foo.cpp.s
$ make foo.cpp.o

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

$ make foo.i
$ make foo.s
$ make foo.o

В системах сборки, которые содержат файлы foo.c и foo.cpp, сборка цели foo.i будет обрабатывать оба файла.

Указание программы сборки

Программа, вызываемая в режиме --build, определяется переменной CMAKE_MAKE_PROGRAM. Для большинства генераторов не требуется настройка конкретной программы.

Инструмент jom способен читать makefiles формата NMake и выполнять сборку параллельно, в то время как инструмент nmake всегда выполняет сборку последовательно. После генерации с помощью генератора NMake Makefiles пользователь может запустить jom вместо nmake. Режим --build также будет использовать jom, если CMAKE_MAKE_PROGRAM был установлен в значение jom при использовании генератора NMake Makefiles, и для удобства предоставляется генератор NMake Makefiles JOM для поиска jom стандартным способом и использования его в качестве CMAKE_MAKE_PROGRAM. Для полноты, nmake является альтернативным инструментом, который может обрабатывать вывод генератора NMake Makefiles JOM, но это будет ухудшением производительности.

Установка программного обеспечения

Переменная CMAKE_INSTALL_PREFIX может быть задана в кэше CMake для указания места установки предоставляемого программного обеспечения. Если предоставленное программное обеспечение имеет правила установки, заданные с помощью команды install(), они будут устанавливать артефакты в этот префикс. В Windows по умолчанию место установки соответствует системному каталогу ProgramFiles, который может быть специфичен для архитектуры. В Unix-системах по умолчанию местом установки является /usr/local.

Переменная CMAKE_INSTALL_PREFIX всегда ссылается на префикс установки на целевом файловом системе.

В сценариях кросс-компиляции или упаковки, где sysroot является только для чтения или где sysroot должен оставаться неизменным, переменная CMAKE_STAGING_PREFIX может быть установлена в расположение для фактической установки файлов.

Команды:

$ cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local \
  -DCMAKE_SYSROOT=$HOME/root \
  -DCMAKE_STAGING_PREFIX=/tmp/package
$ cmake --build .
$ cmake --build . --target install

приводят к установке файлов по таким путям, как /tmp/package/lib/libfoo.so на машине-хосте. Расположение /usr/local на машине-хосте не затронуто.

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

Запуск тестов

Инструмент ctest(1) поставляется с дистрибутивом CMake для выполнения предоставленных тестов и отчета о результатах. Целевой объект test предназначен для выполнения всех доступных тестов, но инструмент ctest(1) позволяет более тонко управлять тем, какие тесты запускать, как их запускать и как сообщать результаты. Выполнение ctest(1) в каталоге сборки эквивалентно запуску целевого объекта test:

$ ctest

Можно передать регулярное выражение для запуска только тестов, которые соответствуют выражению. Для запуска только тестов, содержащих Qt в своем имени:

$ ctest -R Qt

Тесты могут быть исключены по регулярному выражению. Для запуска только тестов без Qt в своем имени:

$ ctest -E Qt

Тесты могут выполняться параллельно, передавая аргументы -j инструменту ctest(1):

$ ctest -R Qt -j8

Переменная среды CTEST_PARALLEL_LEVEL также может быть установлена, чтобы избежать необходимости передавать -j.

По умолчанию ctest(1) не выводит вывод тестов. Флаг командной строки -V (или --verbose) включает подробный режим для вывода вывода всех тестов. Флаг --output-on-failure выводит вывод тестов только для неудачных тестов. Переменная среды CTEST_OUTPUT_ON_FAILURE может быть установлена в значение 1 в качестве альтернативы передаче флага --output-on-failure инструменту ctest(1).