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

• Введение

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