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
  51 :option:`--preset= <cmake --preset>` option directly. The
  52 :option:`--preset= <cmake --preset>` option is intended only as a convenient
  53 frontend for command line users, and should not be used by the IDE.
  54
  55 For example, if a preset named ``ninja`` specifies ``Ninja`` as the generator
  56 and ``${sourceDir}/build`` as the build directory, instead of running:
  57
  58 .. code-block:: console
  59
  60   cmake -S /path/to/source --preset=ninja
  61
  62 the IDE should instead calculate the settings of the ``ninja`` preset, and then
  63 run:
  64
  65 .. code-block:: console
  66
  67   cmake -S /path/to/source -B /path/to/source/build -G Ninja
  68
  69 In cases where a preset contains lots of cache variables, and passing all of
  70 them as :option:`-D <cmake -D>` flags would cause the command line length limit
  71 of the platform to be exceeded, the IDE should instead construct a temporary
  72 cache script and pass it with the :option:`-C <cmake -C>` flag.
  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
 114 :option:`--build <cmake --build>` argument, which will in turn invoke the
 115 appropriate build tool.
 116
 117 If an IDE project generator is used, such as :generator:`Xcode` or one of the
 118 Visual Studio generators, and the IDE understands the project format used, the
 119 IDE should read the project file and build it the same way it would otherwise.
 120
 121 The :manual:`File API <cmake-file-api(7)>` can be used to obtain a list of
 122 build configurations from the build tree, and the IDE should present this list
 123 to the user to select a build configuration.
 124
 125 Testing
 126 =======
 127
 128 :manual:`ctest(1)` supports outputting a JSON format with information about the
 129 available tests and test configurations. IDEs which want to run CTest should
 130 obtain this information and use it to present the user with a list of tests.
 131
 132 IDEs should not invoke the ``test`` target of the generated buildsystem.
 133 Instead, they should invoke :manual:`ctest(1)` directly.
 134
 135 IDEs with CMake integration
 136 ===========================
 137
 138 The following IDEs support CMake natively:
 139
 140 * `CLion`_
 141 * `KDevelop`_
 142 * `QtCreator`_
 143 * `Vim`_ (via a plugin)
 144 * `Visual Studio`_
 145 * `VSCode`_ (via a plugin)
 146
 147 .. _CLion: https://www.jetbrains.com/clion/
 148 .. _KDevelop: https://www.kdevelop.org/
 149 .. _QtCreator: https://www.qt.io/product/development-tools
 150 .. _Vim: https://www.vim.org/
 151 .. _Visual Studio: https://visualstudio.microsoft.com/
 152 .. _VSCode: https://code.visualstudio.com/
 153
 154 Additionally, CMake has builtin support for some IDEs:
 155
 156 * :ref:`IDE Build Tool Generators`:
 157   Generate IDE native build systems such as Visual Studio or Xcode.
 158 * :ref:`Extra Generators`:
 159   Extend :ref:`Command-Line Build Tool Generators` to generate IDE
 160   project files that hook into the command-line build system.
 161   Superseded by the :manual:`File API <cmake-file-api(7)>`.