cmake/Help/guide/ide-integration/index.rst

IDE Integration Guide
*********************

.. only:: html

  .. contents::

Introduction
============

Integrated development environments (IDEs) may want to integrate with CMake to
improve the development experience for CMake users. This document lays out the
recommended best practices for such integration.

Bundling
========

Many IDE vendors will want to bundle a copy of CMake with their IDE. IDEs that
bundle CMake should present the user with the option of using an external CMake
installation instead of the bundled one, in case the bundled copy becomes
outdated and the user wants to use a newer version.

While IDE vendors may be tempted to bundle different versions of CMake with
their application, such practice is not recommended. CMake has strong
guarantees of backwards compatibility, and there is no reason not to use a
newer version of CMake than what a project requires, or indeed, the very latest
version. Therefore, it is recommended that IDE vendors that bundle CMake with
their application always include the very latest patch version of CMake
available at the time of release.

As a suggestion, IDEs may also ship a copy of the Ninja buildsystem alongside
CMake. Ninja is highly performant and well-supported on all platforms that
support CMake. IDEs that bundle Ninja should use Ninja 1.10 or later, which
contains features needed to support Fortran builds.

Presets
=======

CMake supports a file format called ``CMakePresets.json``, and its
user-specific counterpart, ``CMakeUserPresets.json``. This file contains
information on the various configure presets that a user may want. Each preset
may have a different compiler, build flags, etc. The details of this format are
explained in the :manual:`cmake(1)` manual.

IDE vendors are encouraged to read and evaluate this file the same way CMake
does, and present the user with the presets listed in the file. Users should be
able to see (and possibly edit) the CMake cache variables, environment
variables, and command line options that are defined for a given preset. The
IDE should then construct the list of appropriate :manual:`cmake(1)` command
line arguments based on these settings, rather than using the ``--preset=``
option directly. The ``--preset=`` option is intended only as a convenient
frontend for command line users, and should not be used by the IDE.

For example, if a preset named ``ninja`` specifies ``Ninja`` as the generator
and ``${sourceDir}/build`` as the build directory, instead of running:

.. code-block:: console

  cmake -S /path/to/source --preset=ninja

the IDE should instead calculate the settings of the ``ninja`` preset, and then
run:

.. code-block:: console

  cmake -S /path/to/source -B /path/to/source/build -G Ninja

While reading, parsing, and evaluating the contents of ``CMakePresets.json`` is
straightforward, it is not trivial. In addition to the documentation, IDE
vendors may also wish to refer to the CMake source code and test cases for a
better understanding of how to implement the format.
:download:`This file <../../manual/presets/schema.json>` provides a
machine-readable JSON schema for the ``CMakePresets.json`` format that IDE
vendors may find useful for validation and providing editing assistance.

Configuring
===========

IDEs that invoke :manual:`cmake(1)` to run the configure step may wish to
receive information about the artifacts that the build will produce, as well
as the include directories, compile definitions, etc. used to build the
artifacts. Such information can be obtained by using the
:manual:`File API <cmake-file-api(7)>`. The manual page for the File API
contains more information about the API and how to invoke it.
:manual:`Server mode <cmake-server(7)>` was removed as of CMake 3.20 and
should not be used on CMake 3.14 or later.

IDEs should avoid creating more build trees than necessary, and only create
multiple build trees if the user wishes to switch to a different compiler,
use different compile flags, etc. In particular, IDEs should NOT create
multiple single-config build trees which all have the same properties except
for a differing :variable:`CMAKE_BUILD_TYPE`, effectively creating a
multi-config environment. Instead, the :generator:`Ninja Multi-Config`
generator, in conjunction with the :manual:`File API <cmake-file-api(7)>` to
get the list of build configurations, should be used for this purpose.

IDEs should not use the "extra generators" with Makefile or Ninja generators,
which generate IDE project files in addition to the Makefile or Ninja files.
Instead the :manual:`File API <cmake-file-api(7)>` should be used to get the
list of build artifacts.

Building
========

If a Makefile or Ninja generator is used to generate the build tree, it is not
recommended to invoke ``make`` or ``ninja`` directly. Instead, it is
recommended that the IDE invoke :manual:`cmake(1)` with the ``--build``
argument, which will in turn invoke the appropriate build tool.

If an IDE project generator is used, such as :generator:`Xcode` or one of the
Visual Studio generators, and the IDE understands the project format used, the
IDE should read the project file and build it the same way it would otherwise.

The :manual:`File API <cmake-file-api(7)>` can be used to obtain a list of
build configurations from the build tree, and the IDE should present this list
to the user to select a build configuration.

Testing
=======

:manual:`ctest(1)` supports outputting a JSON format with information about the
available tests and test configurations. IDEs which want to run CTest should
obtain this information and use it to present the user with a list of tests.

IDEs should not invoke the ``test`` target of the generated buildsystem.
Instead, they should invoke :manual:`ctest(1)` directly.