Help/guide/ide-integration/index.rst

   1 IDE Integration Guide
   2 *********************
   3
   4 .. only:: html
   5
   6   .. contents::
   7
   8 Introduction
   9 ============
  10
  11 Integrated development environments (IDEs) may want to integrate with CMake to
  12 improve the development experience for CMake users. This document lays out the
  13 recommended best practices for such integration.
  14
  15 Bundling
  16 ========
  17
  18 Many IDE vendors will want to bundle a copy of CMake with their IDE. IDEs that
  19 bundle CMake should present the user with the option of using an external CMake
  20 installation instead of the bundled one, in case the bundled copy becomes
  21 outdated and the user wants to use a newer version.
  22
  23 While IDE vendors may be tempted to bundle different versions of CMake with
  24 their application, such practice is not recommended. CMake has strong
  25 guarantees of backwards compatibility, and there is no reason not to use a
  26 newer version of CMake than what a project requires, or indeed, the very latest
  27 version. Therefore, it is recommended that IDE vendors that bundle CMake with
  28 their application always include the very latest patch version of CMake
  29 available at the time of release.
  30
  31 As a suggestion, IDEs may also ship a copy of the Ninja buildsystem alongside
  32 CMake. Ninja is highly performant and well-supported on all platforms that
  33 support CMake. IDEs that bundle Ninja should use Ninja 1.10 or later, which
  34 contains features needed to support Fortran builds.
  35
  36 Presets
  37 =======
  38
  39 CMake supports a file format called ``CMakePresets.json``, and its
  40 user-specific counterpart, ``CMakeUserPresets.json``. This file contains
  41 information on the various configure presets that a user may want. Each preset
  42 may have a different compiler, build flags, etc. The details of this format are
  43 explained in the :manual:`cmake(1)` manual.
  44
  45 IDE vendors are encouraged to read and evaluate this file the same way CMake
  46 does, and present the user with the presets listed in the file. Users should be
  47 able to see (and possibly edit) the CMake cache variables, environment
  48 variables, and command line options that are defined for a given preset. The
  49 IDE should then construct the list of appropriate :manual:`cmake(1)` command
  50 line arguments based on these settings, rather than using the ``--preset=``
  51 option directly. The ``--preset=`` option is intended only as a convenient
  52 frontend for command line users, and should not be used by the IDE.
  53
  54 For example, if a preset named ``ninja`` specifies ``Ninja`` as the generator
  55 and ``${sourceDir}/build`` as the build directory, instead of running:
  56
  57 .. code-block:: console
  58
  59   cmake -S /path/to/source --preset=ninja
  60
  61 the IDE should instead calculate the settings of the ``ninja`` preset, and then
  62 run:
  63
  64 .. code-block:: console
  65
  66   cmake -S /path/to/source -B /path/to/source/build -G Ninja
  67
  68 In cases where a preset contains lots of cache variables, and passing all of
  69 them as ``-D`` flags would cause the command line length limit of the platform
  70 to be exceeded, the IDE should instead construct a temporary cache script and
  71 pass it with the ``-C`` flag. See :ref:`CMake Options` for details on how the
  72 ``-C`` flag is used.
  73
  74 While reading, parsing, and evaluating the contents of ``CMakePresets.json`` is
  75 straightforward, it is not trivial. In addition to the documentation, IDE
  76 vendors may also wish to refer to the CMake source code and test cases for a
  77 better understanding of how to implement the format.
  78 :download:`This file <../../manual/presets/schema.json>` provides a
  79 machine-readable JSON schema for the ``CMakePresets.json`` format that IDE
  80 vendors may find useful for validation and providing editing assistance.
  81
  82 Configuring
  83 ===========
  84
  85 IDEs that invoke :manual:`cmake(1)` to run the configure step may wish to
  86 receive information about the artifacts that the build will produce, as well
  87 as the include directories, compile definitions, etc. used to build the
  88 artifacts. Such information can be obtained by using the
  89 :manual:`File API <cmake-file-api(7)>`. The manual page for the File API
  90 contains more information about the API and how to invoke it.
  91 :manual:`Server mode <cmake-server(7)>` was removed as of CMake 3.20 and
  92 should not be used on CMake 3.14 or later.
  93
  94 IDEs should avoid creating more build trees than necessary, and only create
  95 multiple build trees if the user wishes to switch to a different compiler,
  96 use different compile flags, etc. In particular, IDEs should NOT create
  97 multiple single-config build trees which all have the same properties except
  98 for a differing :variable:`CMAKE_BUILD_TYPE`, effectively creating a
  99 multi-config environment. Instead, the :generator:`Ninja Multi-Config`
 100 generator, in conjunction with the :manual:`File API <cmake-file-api(7)>` to
 101 get the list of build configurations, should be used for this purpose.
 102
 103 IDEs should not use the "extra generators" with Makefile or Ninja generators,
 104 which generate IDE project files in addition to the Makefile or Ninja files.
 105 Instead the :manual:`File API <cmake-file-api(7)>` should be used to get the
 106 list of build artifacts.
 107
 108 Building
 109 ========
 110
 111 If a Makefile or Ninja generator is used to generate the build tree, it is not
 112 recommended to invoke ``make`` or ``ninja`` directly. Instead, it is
 113 recommended that the IDE invoke :manual:`cmake(1)` with the ``--build``
 114 argument, which will in turn invoke the appropriate build tool.
 115
 116 If an IDE project generator is used, such as :generator:`Xcode` or one of the
 117 Visual Studio generators, and the IDE understands the project format used, the
 118 IDE should read the project file and build it the same way it would otherwise.
 119
 120 The :manual:`File API <cmake-file-api(7)>` can be used to obtain a list of
 121 build configurations from the build tree, and the IDE should present this list
 122 to the user to select a build configuration.
 123
 124 Testing
 125 =======
 126
 127 :manual:`ctest(1)` supports outputting a JSON format with information about the
 128 available tests and test configurations. IDEs which want to run CTest should
 129 obtain this information and use it to present the user with a list of tests.
 130
 131 IDEs should not invoke the ``test`` target of the generated buildsystem.
 132 Instead, they should invoke :manual:`ctest(1)` directly.
 133
 134 IDEs with CMake integration
 135 ===========================
 136
 137 The following IDEs support CMake natively:
 138
 139 * `CLion`_
 140 * `KDevelop`_
 141 * `QtCreator`_
 142 * `Vim`_ (via a plugin)
 143 * `Visual Studio`_
 144 * `VSCode`_ (via a plugin)
 145
 146 .. _CLion: https://www.jetbrains.com/clion/
 147 .. _KDevelop: https://www.kdevelop.org/
 148 .. _QtCreator: https://www.qt.io/product/development-tools
 149 .. _Vim: https://www.vim.org/
 150 .. _Visual Studio: https://visualstudio.microsoft.com/
 151 .. _VSCode: https://code.visualstudio.com/
 152
 153 Additionally, CMake has builtin support for some IDEs:
 154
 155 * :ref:`IDE Build Tool Generators`:
 156   Generate IDE native build systems such as Visual Studio or Xcode.
 157 * :ref:`Extra Generators`:
 158   Extend :ref:`Command-Line Build Tool Generators` to generate IDE
 159   project files that hook into the command-line build system.
 160   Superseded by the :manual:`File API <cmake-file-api(7)>`.