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