Руководство по интеграции с 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.