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

• Введение

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

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