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