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

• Введение

  • Инструмент 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.

Некоторые среды разработки, такие как KDevelop4, QtCreator и CLion, имеют встроенную поддержку систем сборки CMake. Эти среды предоставляют интерфейс для выбора используемого генератора, обычно выбор между генератором на основе 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 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, являются целью сборки, и система сборки может описывать пользовательские цели, как для внутреннего использования, так и для использования пользователем, например, для создания документации.

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