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