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

• Введение

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

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

При генерации файлов проекта и решений 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

Установка программного обеспечения. Эта цель доступна только автоматически, если программное обеспечение определяет правила установки с помощью команды 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).