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

• Введение

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

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

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

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

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

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

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

Введение

В случае, если пакет программного обеспечения предоставляет систему сборки 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 и инструмента сборки.

Опция командной строки -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 LLVM
$ # 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(). Команда создаёт запись кэша, которая имеет текст справки и значение по умолчанию. Такие записи кэша, как правило, специфичны для предоставляемого программного обеспечения и влияют на конфигурацию сборки, например, на то, будут ли построены тесты и примеры, будет ли сборка производиться с поддержкой исключений и т. д.

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

После генерации системы сборки программное обеспечение можно скомпилировать, вызвав конкретный инструмент сборки. В случае генераторов 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

Создаёт двоичный пакет.

package_source

Создаёт исходный пакет.

Для систем на основе 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 способен читать makeфайлы 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).