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

• Введение

  • Инструмент cmake командной строки
  • Инструмент cmake-gui

• Генерация системы сборки

  • Среда командной строки
  • Опция командной строки -G
  • Выбор генератора в cmake-gui

• Установка переменных сборки

  • Установка переменных в командной строке
  • Установка переменных с помощью cmake-gui
  • Кэш CMake

• Вызов системы сборки

  • Выбор цели
  • Указание программы сборки
• Установка программного обеспечения
• Запуск тестов

Введение

Когда программный пакет предоставляет систему сборки 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 и инструмента сборки.

Опция командной строки -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 можно указать с помощью опции -T:

$ # Build with the clang-cl toolset
$ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T LLVM
$ # 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(). Эта команда создаёт запись в кэше, которая имеет текст справки и значение по умолчанию. Такие записи в кэше, как правило, специфичны для предоставляемого программного обеспечения и влияют на конфигурацию сборки, например, на то, строятся ли тесты и примеры, включается ли обработка исключений и т.д.

Вызов системы сборки

После генерации системы сборки программное обеспечение можно скомпилировать, вызвав соответствующий инструмент сборки. В случае генераторов 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

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