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

• Введение

  • Инструмент 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 можно указать с помощью опции 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. Для Xcode и Visual Studio генераторов используется имя ALL_BUILD.

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).