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