Руководство по интеграции с IDE

• Введение
• Сборка в пакет
• Пресеты
• Настройка
• Компиляция
• Тестирование
• IDE с интегрированной поддержкой CMake

Введение

Интегрированные среды разработки (IDE) могут захотеть интегрироваться с CMake, чтобы улучшить опыт разработки для пользователей CMake. Этот документ описывает рекомендуемые лучшие практики для такой интеграции.

Сборка в пакет

Многие поставщики IDE захотят включить копию CMake в свою IDE. IDE, которые собирают CMake в пакет, должны предоставить пользователю возможность использовать стороннюю установку CMake вместо включённой, в случае если включенная копия устареет, а пользователь захочет использовать новую версию.

Хотя поставщики IDE могут быть искушены включить в приложение разные версии CMake, такая практика не рекомендуется. CMake имеет сильные гарантии обратной совместимости, и нет причин не использовать более новую версию CMake, чем требуется проекту, или даже самую последнюю версию. Поэтому рекомендуется, чтобы поставщики IDE, которые включают CMake в своё приложение, всегда включали самую последнюю исправленную версию CMake, доступную на момент выпуска.

В качестве предложения IDE также могут поставлять копию системы сборки Ninja вместе с CMake. Ninja обладает высокой производительностью и хорошо поддерживается на всех платформах, поддерживающих CMake. IDE, которые включают Ninja, должны использовать Ninja 1.10 или более поздние версии, которые содержат функции, необходимые для поддержки сборки Fortran.

Пресеты

CMake поддерживает формат файла CMakePresets.json, и его аналог для пользователя, CMakeUserPresets.json. Этот файл содержит информацию о различных пресетах конфигурации, которые может захотеть пользователь. Каждый пресет может иметь другой компилятор, флаги сборки и т. д. Подробности этого формата описаны в руководстве cmake(1).

Поставщикам IDE рекомендуется читать и оценивать этот файл так же, как и CMake, и предоставлять пользователю список пресетов, перечисленных в файле. Пользователи должны иметь возможность видеть (и, возможно, редактировать) переменные кэша CMake, переменные среды и параметры командной строки, определённые для данного пресета. Затем IDE должна составить список соответствующих cmake(1) аргументов командной строки на основе этих настроек, а не использовать параметр --preset= непосредственно. Параметр --preset= предназначен только для удобства использования в командной строке и не должен использоваться IDE.

Например, если пресет с именем ninja задаёт Ninja в качестве генератора и ${sourceDir}/build в качестве каталога сборки, вместо выполнения:

cmake -S /path/to/source --preset=ninja

IDE должна вместо этого вычислить настройки пресета ninja и затем выполнить:

cmake -S /path/to/source -B /path/to/source/build -G Ninja

В тех случаях, когда пресет содержит много переменных кэша, и передача всех их в качестве флагов -D может превысить ограничение длины командной строки платформы, IDE должна вместо этого создать временный скрипт кэша и передать его с флагом -C.

Хотя чтение, разбор и оценка содержимого CMakePresets.json просты, это не тривиальная задача. Помимо документации, поставщики IDE также могут обратиться к исходному коду CMake и тестовым случаям для лучшего понимания того, как реализовать этот формат. This file предоставляет машиночитаемый JSON-схему для формата CMakePresets.json, которая может быть полезна поставщикам IDE для валидации и предоставления помощи при редактировании.

Настройка

IDE, которые вызывают cmake(1) для выполнения шага настройки, могут захотеть получить информацию о результатах сборки, а также о каталогах включения, определениях компиляции и т. д., используемых для сборки результатов. Такая информация может быть получена с помощью File API. В руководстве по API файлов содержится более подробная информация об API и о том, как его вызвать. Server mode был удалён с версии CMake 3.20 и не должен использоваться в CMake 3.14 или более поздних версиях.

IDE должны избегать создания большего числа деревьев сборки, чем необходимо, и создавать несколько деревьев сборки только в том случае, если пользователь хочет переключиться на другой компилятор, использовать другие флаги компиляции и т. д. В частности, IDE НЕ должны создавать несколько деревьев сборки с одинаковыми свойствами, за исключением отличающегося CMAKE_BUILD_TYPE, фактически создавая многоконфигурационную среду. Вместо этого следует использовать генератор Ninja Multi-Config в сочетании с File API для получения списка конфигураций сборки.

IDE не должны использовать «дополнительных генераторов» с генераторами Makefile или Ninja, которые генерируют файлы проектов IDE в дополнение к файлам Makefile или Ninja. Вместо этого следует использовать File API для получения списка результатов сборки.

Компиляция

Если для генерации дерева сборки используется генератор Makefile или Ninja, не рекомендуется вызывать make или ninja напрямую. Вместо этого рекомендуется, чтобы IDE вызывала cmake(1) с аргументом --build, который в свою очередь вызовет соответствующий инструмент сборки.

Если используется генератор проекта IDE, такой как Xcode или один из генераторов Visual Studio, и IDE понимает используемый формат проекта, IDE должна прочитать файл проекта и скомпилировать его так же, как она бы это сделала в противном случае.

Можно использовать File API для получения списка конфигураций сборки из дерева сборки, и IDE должна предоставить этот список пользователю для выбора конфигурации сборки.

Тестирование

ctest(1) поддерживает вывод в формате JSON с информацией о доступных тестах и конфигурациях тестов. IDE, которые хотят запустить CTest, должны получить эту информацию и использовать её для представления пользователю списка тестов.

IDE не должны вызывать целевой test сгенерированной системы сборки. Вместо этого они должны вызывать ctest(1) напрямую.

IDE с интегрированной поддержкой CMake

Следующие IDE поддерживают CMake по умолчанию:

• CLion
• KDevelop
• QtCreator
• Vim (через плагин)
• Visual Studio
• VSCode (через плагин)

Кроме того, CMake имеет встроенную поддержку некоторых IDE:

• Генераторы инструментов сборки IDE: генерируют собственные системы сборки IDE, такие как Visual Studio или Xcode.
• Дополнительные генераторы: расширяют Генераторы инструментов сборки командной строки для генерации файлов проектов IDE, которые подключаются к системе сборки командной строки. Заменён на File API.