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