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