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

• Введение

  • Инструмент 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 могут выдавать предупреждения, предназначенные для поставщика программного обеспечения, а не для его потребителя. Такие предупреждения заканчиваются фразой "This warning is for project developers". Пользователи могут отключить такие предупреждения, передав флаг -Wno-author инструменту 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

Нажатие кнопки "Configure" открывает новое диалоговое окно для выбора генератора 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 с помощью кнопки "Add Entry". При нажатии открывается новое диалоговое окно для задания значения переменной.

В главном окне пользовательского интерфейса 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 для сохранения предустановок часто используемых параметров конфигурации. Эти предустановки могут задавать каталог сборки, генератор, переменные кэша, переменные окружения и другие параметры командной строки. Пользователь может переопределить любой из этих параметров. Полное описание формата предустановок CMake приведено в руководстве 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 можно выполнить базовый инструмент сборки. Например, после создания системы сборки с помощью генератора Unix Makefiles можно запустить make, а после создания системы сборки с помощью генератора Ninja — ninja и т. д. Системы сборки IDE обычно предоставляют инструменты командной строки для сборки проекта, которые также можно запускать.

Выбор цели

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

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

all

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

help

Выводит список доступных для сборки целей. Эта цель доступна при использовании генераторов Makefile или генераторов 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 умеет читать make-файлы в варианте NMake и выполнять сборку параллельно, тогда как инструмент nmake всегда выполняет сборку последовательно. После генерации с помощью генератора NMake Makefiles пользователь может запустить jom вместо nmake. Режим --build также использовал бы jom, если бы при использовании генератора NMake Makefiles переменная CMAKE_MAKE_PROGRAM была задана как jom. Для удобства предусмотрен генератор NMake Makefiles JOM, который находит jom обычным способом и использует его в качестве CMAKE_MAKE_PROGRAM. Для полноты картины: nmake — это альтернативный инструмент, способный обрабатывать вывод генератора NMake Makefiles JOM, однако это снизило бы производительность.

Установка программного обеспечения

Переменную CMAKE_INSTALL_PREFIX можно задать в кэше CMake, чтобы указать путь установки предоставляемого программного обеспечения. Если для него заданы правила установки с помощью команды install(), артефакты будут установлены в этот префикс. В Windows расположение установки по умолчанию соответствует системному каталогу ProgramFiles, который может зависеть от архитектуры. В Unix-системах расположением установки по умолчанию является /usr/local.

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

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