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

• Введение

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

Некоторые среды разработки, такие как KDevelop4, QtCreator и CLion, поддерживают системы построения на основе CMake. Эти среды предоставляют интерфейс пользователя для выбора используемого генератора, обычно между генератором на основе 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).