Руководство по интеграции IDE

• Введение
• Упаковки
• Настройки
• Настройка
• Компиляция
• Тестирование

Введение

Интегрированные среды разработки (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

Хотя чтение, разбор и оценка содержимого 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) напрямую.