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

• Введение

  • Инструмент 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. Выбор используемой версии можно осуществить несколькими способами, но наиболее распространённые методы:

• Установление значения по умолчанию в настройках Xcode IDE.
• Установление значения по умолчанию через 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 для генерации файлов проекта для среды Xcode.

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