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

• Введение

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