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