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