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

• Введение

  • Инструмент cmake в командной строке
  • Инструмент cmake-gui

• Генерация системы сборки

  • Среда командной строки
  • Опция командной строки -G
  • Выбор генератора в cmake-gui

• Настройка переменных сборки

  • Настройка переменных в командной строке
  • Настройка переменных с помощью cmake-gui
  • Кэш CMake

• Пресеты

  • Использование пресетов в командной строке
  • Использование пресетов в cmake-gui

• Вызов системы сборки

  • Выбор целевого объекта
  • Указание программы сборки
• Установка программного обеспечения
• Запуск тестов

Введение

Если программный пакет предоставляет систему сборки на основе CMake вместе с исходным кодом, пользователю необходимо запустить инструмент взаимодействия с пользователем CMake для её построения.

Корректно разработанные системы сборки на основе CMake не создают никакого вывода в каталоге исходных кодов, поэтому обычно пользователь выполняет внеисточниковый build в отдельном каталоге. Сначала CMake необходимо дать команду сгенерировать подходящую систему сборки, а затем пользователь вызывает инструмент сборки для обработки сгенерированной системы. Сгенерированная система сборки специфична для используемой машины и не перераспределяется. Каждый пользователь, использующий предоставленный пакет исходного кода, обязан использовать CMake для генерации системы сборки, специфичной для его системы.

Сгенерированные системы сборки в целом должны рассматриваться как только для чтения. Файлы CMake в качестве основного артефакта должны полностью определять систему сборки, и нет причин для ручного заполнения свойств в IDE, например, после генерации системы сборки. CMake периодически перезаписывает сгенерированную систему сборки, поэтому изменения, внесённые пользователем, будут перезаписаны.

Функции и пользовательские интерфейсы, описанные в этом руководстве, доступны для всех систем сборки на основе CMake благодаря предоставленным файлам CMake.

Инструментарий CMake может сообщать пользователю об ошибках при обработке предоставленных файлов CMake, например, сообщая, что компилятор не поддерживается, или компилятор не поддерживает требуемую опцию компиляции, или зависимость не найдена. Эти ошибки необходимо устранить пользователю, выбрав другой компилятор, installing dependencies, или указав CMake, где их найти, и т. д.

Инструмент cmake в командной строке

Простой, но типичный пример использования cmake(1) с новой копией исходного кода программного обеспечения заключается в создании каталога сборки и вызове cmake там:

$ cd some_software-1.4.2
$ mkdir build
$ cd build
$ cmake .. -DCMAKE_INSTALL_PREFIX=/opt/the/prefix
$ cmake --build .
$ cmake --build . --target install

Рекомендуется строить в отдельном каталоге от исходного, так как это сохраняет исходный каталог без изменений, позволяет строить один исходный код с несколькими инструментальными цепочками и позволяет легко очистить артефакты сборки, просто удалив каталог сборки.

Инструментарий CMake может сообщать о предупреждениях, которые предназначены для разработчика программного обеспечения, а не для пользователя. Такие предупреждения заканчиваются фразой «Это предупреждение для разработчиков проекта». Пользователи могут отключить такие предупреждения, передав флаг -Wno-dev инструменту cmake(1).

Инструмент cmake-gui

Пользователи, более привыкшие к графическим интерфейсам, могут использовать инструмент cmake-gui(1) для вызова CMake и генерации системы сборки.

Сначала необходимо заполнить каталоги исходного кода и библиотек. Всегда рекомендуется использовать разные каталоги для исходного кода и сборки.

Генерация системы сборки

Существует несколько инструментов пользовательского интерфейса, которые можно использовать для генерации системы сборки из файлов CMake. Инструменты ccmake(1) и cmake-gui(1) ведут пользователя через настройку необходимых параметров. Инструмент cmake(1) можно вызвать для указания параметров в командной строке. В данном руководстве описаны параметры, которые можно задать с помощью любого из инструментов пользовательского интерфейса, хотя способ задания параметра отличается для каждого инструмента.

Среда командной строки

При вызове cmake(1) с системой сборки командной строки, такой как Makefiles или Ninja, необходимо использовать правильную среду сборки, чтобы гарантировать доступность инструментов сборки. CMake должен иметь возможность найти соответствующую программу build tool, компилятор, компоновщик и другие необходимые инструменты.

В системах Linux соответствующие инструменты часто предоставляются в системных местах и могут быть легко установлены через системный менеджер пакетов. Также можно использовать другие инструментальные цепочки, предоставленные пользователем или установленные в местах, отличных от стандартных.

При кросс-компиляции некоторые платформы могут потребовать задания переменных среды или могут предоставить скрипты для настройки среды.

Visual Studio поставляется с несколькими командными интерпретаторами и скриптами vcvarsall.bat для настройки правильных сред для систем сборки командной строки. Хотя это не строго необходимо для использования соответствующей среды командной строки при использовании генератора Visual Studio, это не приносит никаких недостатков.

При использовании Xcode может быть установлено более одной версии Xcode. Выбор используемой версии можно выполнить несколькими способами, но наиболее распространённые методы:

• Установка предпочтительной версии в настройках IDE Xcode.
• Установка предпочтительной версии через инструмент командной строки xcode-select.
• Переопределение предпочтительной версии путём задания переменной среды DEVELOPER_DIR при запуске CMake и инструмента сборки.

Для удобства cmake-gui(1) предоставляет редактор переменных среды.

Опция командной строки -G

CMake по умолчанию выбирает генератор на основе платформы. Обычно, генератор по умолчанию достаточно для продолжения построения программного обеспечения.

Пользователь может переопределить генератор по умолчанию с помощью опции -G:

$ cmake .. -G Ninja

Вывод команды cmake --help включает список generators, доступных для выбора пользователем. Обратите внимание, что имена генераторов чувствительны к регистру.

В системах Unix-подобных системах (включая Mac OS X) по умолчанию используется генератор Unix Makefiles. Вариант этого генератора также может использоваться в Windows в различных средах, таких как генератор NMake Makefiles и MinGW Makefiles. Эти генераторы генерируют Makefile вариант, который можно выполнить с помощью make, gmake, nmake или аналогичных инструментов. Более подробную информацию о целевых средах и инструментах см. в документации по отдельным генераторам.

Генератор Ninja доступен на всех основных платформах. ninja — это инструмент сборки, схожий по функциональности с make, но с упором на производительность и эффективность.

В Windows cmake(1) можно использовать для генерации решений для IDE Visual Studio. Версии Visual Studio можно указать по имени продукта IDE, которое включает четырёхзначный год. Предоставляются алиасы для других способов обозначения версий Visual Studio, например, двухзначные цифры, соответствующие версии компилятора VisualC++, или их комбинация:

$ cmake .. -G "Visual Studio 2019"
$ cmake .. -G "Visual Studio 16"
$ cmake .. -G "Visual Studio 16 2019"

Генераторы Visual Studio могут нацеливаться на различные архитектуры. Можно указать целевую архитектуру, используя опцию -A:

cmake .. -G "Visual Studio 2019" -A x64
cmake .. -G "Visual Studio 16" -A ARM
cmake .. -G "Visual Studio 16 2019" -A ARM64

В Apple используется генератор Xcode, чтобы генерировать файлы проекта для IDE Xcode.

Некоторые IDE, такие как KDevelop4, QtCreator и CLion, имеют встроенную поддержку систем сборки CMake. Эти IDE предоставляют интерфейс для выбора используемого генератора, обычно между генератором на основе Makefile и генератором на основе Ninja.

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

При генерации файлов проектов и решений для Visual Studio доступно несколько других опций при первоначальном запуске cmake(1).

Набор инструментов Visual Studio можно указать с помощью опции cmake -T:

$ # Build with the clang-cl toolset
$ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T ClangCL
$ # Build targeting Windows XP
$ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T v120_xp

В то время как опция -A указывает _целевую_ архитектуру, опция -T может использоваться для указания деталей используемой цепочки инструментов. Например, -Thost=x64 можно использовать для выбора 64-битной версии инструментов хоста. Следующий пример демонстрирует использование 64-битных инструментов и компиляцию для 64-битной целевой архитектуры:

$ cmake .. -G "Visual Studio 16 2019" -A x64 -Thost=x64

Выбор генератора в cmake-gui

Кнопка "Настроить" вызывает новое диалоговое окно для выбора генератора CMake.

Все доступные генераторы командной строки также доступны в cmake-gui(1).

При выборе генератора Visual Studio доступны дополнительные опции для установки архитектуры, для которой необходимо сгенерировать проект.

Установка переменных сборки

Проекты программного обеспечения часто требуют установки переменных в командной строке при вызове CMake. Некоторые из наиболее часто используемых переменных CMake перечислены в таблице ниже:

Другие переменные, специфичные для проекта, могут быть доступны для управления сборками, например, включения или выключения компонентов проекта.

CMake не предоставляет соглашения о наименовании таких переменных между различными системами сборки, за исключением того, что переменные с префиксом CMAKE_ обычно относятся к опциям, предоставляемым самим CMake, и не должны использоваться в сторонних опциях, которые должны использовать свой собственный префикс. Инструмент cmake-gui(1) может отображать опции в группах, определённых их префиксом, поэтому для сторонних разработчиков имеет смысл использовать согласованный префикс.

Установка переменных в командной строке

Переменные CMake можно установить в командной строке при создании первоначальной сборки:

$ mkdir build
$ cd build
$ cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Debug

или позднее при последующем вызове cmake(1):

$ cd build
$ cmake . -DCMAKE_BUILD_TYPE=Debug

Флаг -U может использоваться для сброса переменных в командной строке cmake(1):

$ cd build
$ cmake . -UMyPackage_DIR

Система сборки CMake, первоначально созданная в командной строке, может быть изменена с помощью cmake-gui(1) и наоборот.

Инструмент cmake(1) позволяет указать файл для заполнения исходного кэша с помощью опции -C. Это может быть полезно для упрощения команд и скриптов, которые многократно требуют одних и тех же записей кэша.

Установка переменных с помощью cmake-gui

Переменные могут быть установлены в cmake-gui с помощью кнопки "Добавить запись". Это вызывает новое диалоговое окно для установки значения переменной.

Основное окно пользовательского интерфейса cmake-gui(1) может использоваться для редактирования существующих переменных.

Кэш CMake

При выполнении CMake ему необходимо найти расположения компиляторов, инструментов и зависимостей. Также ему нужно последовательно перегенерировать систему сборки, используя те же флаги компиляции/связывания и пути к зависимостям. Такие параметры также должны быть настраиваемыми для пользователя, поскольку они являются путями и опциями, специфичными для системы пользователя.

При первом запуске CMake генерирует файл CMakeCache.txt в директории сборки, содержащий пары ключ-значение для таких артефактов. Файл кэша может быть просмотрен или отредактирован пользователем с помощью инструмента cmake-gui(1) или ccmake(1). Инструменты предоставляют интерактивный интерфейс для переконфигурации предоставленного программного обеспечения и перегенерации системы сборки, как это требуется после редактирования кэшированных значений. Каждая запись кэша может иметь связанный короткий текст справки, отображаемый в инструментах пользовательского интерфейса.

Записи кэша также могут иметь тип, указывающий, как они должны быть представлены в пользовательском интерфейсе. Например, запись кэша типа BOOL может быть отредактирована с помощью флажка в пользовательском интерфейсе, запись типа STRING может быть отредактирована в поле ввода текста, а запись типа FILEPATH (аналогичная STRING) должна также обеспечить возможность поиска путей файловой системы с помощью диалогового окна выбора файла. Запись типа STRING может предоставить ограниченный список разрешенных значений, которые затем будут представлены в раскрывающемся меню в пользовательском интерфейсе cmake-gui(1) (см. свойство кэша STRINGS).

Файлы CMake, поставляемые с пакетом программного обеспечения, также могут определять логические опции с помощью команды option(). Эта команда создаёт запись кэша с текстом справки и значением по умолчанию. Такие записи кэша, как правило, специфичны для предоставляемого программного обеспечения и влияют на конфигурацию сборки, например, на сборку тестов и примеров, сборку с включёнными исключениями и т. д.

Настройки

CMake понимает файл CMakePresets.json и его пользовательский аналог CMakeUserPresets.json для сохранения настроек конфигурации, часто используемых при настройке. Эти настройки могут задавать директорию сборки, генератор, переменные кэша, переменные среды и другие опции командной строки. Все эти опции могут быть переопределены пользователем. Полные детали формата CMakePresets.json перечислены в руководстве cmake-presets(7).

Использование настроек в командной строке

При использовании утилиты командной строки cmake(1), предустановку можно вызвать, используя опцию --preset. Если указана --preset, то генератор и каталог сборки не требуются, но могут быть указаны для их переопределения. Например, если у вас есть следующий CMakePresets.json файл:

{
  "version": 1,
  "configurePresets": [
    {
      "name": "ninja-release",
      "binaryDir": "${sourceDir}/build/${presetName}",
      "generator": "Ninja",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Release"
      }
    }
  ]
}

и вы выполняете следующее:

cmake -S /path/to/source --preset=ninja-release

Это сгенерирует каталог сборки в /path/to/source/build/ninja-release с генератором Ninja и с CMAKE_BUILD_TYPE, установленным в Release.

Если вы хотите увидеть список доступных предустановок, вы можете выполнить:

cmake -S /path/to/source --list-presets

Это отобразит предустановки, доступные в /path/to/source/CMakePresets.json и /path/to/source/CMakeUsersPresets.json без генерации дерева сборки.

Использование предустановок в cmake-gui

Если проект имеет доступные предустановки, либо через CMakePresets.json или CMakeUserPresets.json, список предустановок будет отображаться в выпадающем меню в cmake-gui(1) между каталогом исходных файлов и каталогом бинарных файлов. Выбор предустановки устанавливает каталог бинарных файлов, генератор, переменные среды и переменные кэша, но все эти параметры можно переопределить после выбора предустановки.

Вызов системы сборки

После генерации системы сборки программное обеспечение можно собрать, вызвав конкретный инструмент сборки. В случае генераторов IDE это может включать загрузку сгенерированного файла проекта в IDE для вызова сборки.

CMake знает, какой конкретный инструмент сборки нужен для вызова сборки, поэтому, в общем случае, для сборки системы сборки или проекта из командной строки после генерации можно вызвать следующую команду в каталоге сборки:

$ cmake --build .

Флаг --build включает определённый режим работы для утилиты cmake(1). Он вызывает команду CMAKE_MAKE_PROGRAM, связанную с generator, или инструмент сборки, настроенный пользователем.

Режим --build также принимает параметр --target для указания конкретной цели сборки, например, конкретной библиотеки, исполняемого файла или пользовательской цели, или конкретной специальной цели, такой как install:

$ cmake --build . --target myexe

Режим --build также принимает параметр --config в случае генераторов с несколькими конфигурациями, чтобы указать, какую конкретную конфигурацию нужно собрать:

$ cmake --build . --target myexe --config Release

Опция --config не оказывает никакого влияния, если генератор генерирует систему сборки, специфичную для конфигурации, которая выбирается при вызове cmake с переменной CMAKE_BUILD_TYPE.

Некоторые системы сборки опускают подробности командных строк, вызываемых во время сборки. Флаг --verbose можно использовать для отображения этих командных строк:

$ cmake --build . --target myexe --verbose

Режим --build также может передать конкретные параметры командной строки в основной инструмент сборки, перечислив их после --. Это может быть полезно для указания параметров инструмента сборки, например, для продолжения сборки после завершения неудачной задачи, где CMake не предоставляет удобный интерфейс пользователя высокого уровня.

Для всех генераторов возможно запуск основного инструмента сборки после вызова CMake. Например, make может быть выполнен после генерации с генератором Unix Makefiles для вызова сборки, или ninja после генерации с генератором Ninja и т.д. Системы сборки IDE обычно предоставляют инструменты командной строки для сборки проекта, которые также можно вызвать.

Выбор цели

Каждый исполняемый файл и библиотека, описанные в файлах CMake, являются целью сборки, и система сборки может описывать пользовательские цели, либо для внутреннего использования, либо для использования пользователем, например, для создания документации.

CMake предоставляет некоторые встроенные цели для всех систем сборки, предоставляющих файлы CMake.

all

Умолчательная цель, используемая генераторами Makefile и Ninja. Сборка всех целей в системе сборки, за исключением тех, которые исключены их свойством цели EXCLUDE_FROM_ALL или свойством каталога EXCLUDE_FROM_ALL. Имя ALL_BUILD используется для этой цели для генераторов Xcode и Visual Studio.

help

Отображает доступные для сборки цели. Эта цель доступна при использовании генератора Unix Makefiles или Ninja, и точный вывод зависит от инструмента.

clean

Удаляет сгенерированные файлы объектов и другие выходные файлы. Генераторы на основе Makefile создают цель clean для каждого каталога, чтобы можно было очистить отдельный каталог. Инструмент Ninja предоставляет свою собственную гранулированную систему -t clean.

test

Запуск тестов. Эта цель доступна только автоматически, если файлы CMake предоставляют тесты на основе CTest. См. также Запуск тестов.

install

Установка программного обеспечения. Эта цель доступна только автоматически, если файлы CMake определяют правила установки с помощью команды install(). См. также Установка программного обеспечения.

package

Создание двоичного пакета. Эта цель доступна только автоматически, если файлы 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).