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

• Введение

  • Инструмент 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).