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

• Введение

  • Инструмент 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 можно указать с помощью параметра cmake -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

Создаёт бинарный пакет.

package_source

Создаёт исходный пакет.

Для систем на основе 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).