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

• Введение

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