Руководство по интеграции с 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. См. Опции для получения подробностей о том, как используется флаг -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.