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

Разработчикам 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.

Хотя читать, разбирать и вычислять содержимое файлов предустановок CMake достаточно просто, это не тривиальная задача. Помимо документации, разработчикам IDE может быть полезно обратиться к исходному коду и тестам CMake, чтобы лучше понять, как реализовать этот формат. Файл This file содержит машиночитаемую схему JSON для формата файлов предустановок CMake, которая может пригодиться разработчикам IDE для проверки данных и реализации помощи при редактировании.

Настройка

IDE, вызывающим cmake(1) для выполнения этапа настройки, может потребоваться информация о создаваемых в ходе сборки артефактах, а также о каталогах включаемых файлов, определениях компиляции и т. д., используемых для их создания. Эти сведения можно получить с помощью File API. На странице руководства по File 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 понимает используемый формат проекта, ей следует прочитать файл проекта и собрать его обычным для этого формата способом.

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.