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

• Введение

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

Пресеты

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

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