Help/dev/source.rst

   1 CMake Source Code Guide
   2 ***********************
   3
   4 The following is a guide to the CMake source code for developers.
   5 See documentation on `CMake Development`_ for more information.
   6
   7 .. _`CMake Development`: README.rst
   8
   9 C++ Code Style
  10 ==============
  11
  12 We use `clang-format`_ version **6.0** to define our style for C++ code in
  13 the CMake source tree.  See the `.clang-format`_ configuration file for our
  14 style settings.  Use the `Utilities/Scripts/clang-format.bash`_ script to
  15 format source code.  It automatically runs ``clang-format`` on the set of
  16 source files for which we enforce style.  The script also has options to
  17 format only a subset of files, such as those that are locally modified.
  18
  19 .. _`clang-format`: http://clang.llvm.org/docs/ClangFormat.html
  20 .. _`.clang-format`: ../../.clang-format
  21 .. _`Utilities/Scripts/clang-format.bash`: ../../Utilities/Scripts/clang-format.bash
  22
  23 C++ Subset Permitted
  24 ====================
  25
  26 CMake requires compiling as C++11 in order to support building on older
  27 toolchains.  However, to facilitate development, some standard library
  28 features from more recent C++ standards are supported through a compatibility
  29 layer.  These features are defined under the namespace ``cm`` and headers
  30 are accessible under the ``cm/`` directory.  The headers under ``cm/`` can
  31 be used in place of the standard ones when extended features are needed.
  32 For example ``<cm/memory>`` can be used in place of ``<memory>``.
  33
  34 Available features are:
  35
  36 * From ``C++14``:
  37
  38   * ``<cm/array>``:
  39     ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
  40     ``cm::crbegin``, ``cm::crend``
  41
  42   * ``<cm/deque>``:
  43     ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
  44     ``cm::crbegin``, ``cm::crend``
  45
  46   * ``<cm/forward_list>``:
  47     ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
  48     ``cm::crbegin``, ``cm::crend``
  49
  50   * ``<cm/iomanip>``:
  51     ``cm::quoted``
  52
  53   * ``<cm/iterator>``:
  54     ``cm::make_reverse_iterator``, ``cm::cbegin``, ``cm::cend``,
  55     ``cm::rbegin``, ``cm::rend``, ``cm::crbegin``, ``cm::crend``
  56
  57   * ``<cm/list>``:
  58     ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
  59     ``cm::crbegin``, ``cm::crend``
  60
  61   * ``<cm/map>``:
  62     ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
  63     ``cm::crbegin``, ``cm::crend``
  64
  65   * ``<cm/memory>``:
  66     ``cm::make_unique``
  67
  68   * ``<cm/set>``:
  69     ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
  70     ``cm::crbegin``, ``cm::crend``
  71
  72   * ``<cm/string>``:
  73     ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
  74     ``cm::crbegin``, ``cm::crend``
  75
  76   * ``<cm/string_view>``:
  77     ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
  78     ``cm::crbegin``, ``cm::crend``
  79
  80   * ``<cm/shared_mutex>``:
  81     ``cm::shared_lock``
  82
  83   * ``<cm/type_traits>``:
  84     ``cm::enable_if_t``
  85
  86   * ``<cm/unordered_map>``:
  87     ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
  88     ``cm::crbegin``, ``cm::crend``
  89
  90   * ``<cm/unordered_set>``:
  91     ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
  92     ``cm::crbegin``, ``cm::crend``
  93
  94   * ``<cm/vector>``:
  95     ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
  96     ``cm::crbegin``, ``cm::crend``
  97
  98 * From ``C++17``:
  99
 100   * ``<cm/algorithm>``:
 101     ``cm::clamp``
 102
 103   * ``<cm/array>``:
 104     ``cm::size``, ``cm::empty``, ``cm::data``
 105
 106   * ``<cm/deque>``:
 107     ``cm::size``, ``cm::empty``, ``cm::data``
 108
 109   * ``cm/filesystem>``:
 110     ``cm::filesystem::path``
 111
 112   * ``<cm/forward_list>``:
 113     ``cm::size``, ``cm::empty``, ``cm::data``
 114
 115   * ``<cm/iterator>``:
 116     ``cm::size``, ``cm::empty``, ``cm::data``
 117
 118   * ``<cm/list>``:
 119     ``cm::size``, ``cm::empty``, ``cm::data``
 120
 121   * ``<cm/map>``:
 122     ``cm::size``, ``cm::empty``, ``cm::data``
 123
 124   * ``<cm/optional>``:
 125     ``cm::nullopt_t``, ``cm::nullopt``, ``cm::optional``,
 126     ``cm::make_optional``, ``cm::bad_optional_access``
 127
 128   * ``<cm/set>``:
 129     ``cm::size``, ``cm::empty``, ``cm::data``
 130
 131   * ``<cm/shared_mutex>``:
 132     ``cm::shared_mutex``
 133
 134   * ``<cm/string>``:
 135     ``cm::size``, ``cm::empty``, ``cm::data``
 136
 137   * ``<cm/string_view>``:
 138     ``cm::string_view``, ``cm::size``, ``cm::empty``, ``cm::data``
 139
 140   * ``<cm/type_traits>``:
 141     ``cm::bool_constant``, ``cm::invoke_result_t``, ``cm::invoke_result``,
 142     ``cm::void_t``
 143
 144   * ``<cm/unordered_map>``:
 145     ``cm::size``, ``cm::empty``, ``cm::data``
 146
 147   * ``<cm/unordered_set>``:
 148     ``cm::size``, ``cm::empty``, ``cm::data``
 149
 150   * ``<cm/utility>``:
 151     ``cm::in_place_t``, ``cm::in_place``
 152
 153   * ``<cm/vector>``:
 154     ``cm::size``, ``cm::empty``, ``cm::data``
 155
 156 * From ``C++20``:
 157
 158   * ``<cm/array>``:
 159     ``cm::ssize``
 160
 161   * ``<cm/deque>``:
 162     ``cm::erase``, ``cm::erase_if``, ``cm::ssize``
 163
 164   * ``<cm/forward_list>``:
 165     ``cm::ssize``
 166
 167   * ``<cm/iterator>``:
 168     ``cm::ssize``
 169
 170   * ``<cm/list>``:
 171     ``cm::erase``, ``cm::erase_if``, ``cm::ssize``
 172
 173   * ``<cm/map>`` :
 174     ``cm::erase_if``, ``cm::ssize``
 175
 176   * ``<cm/set>`` :
 177     ``cm::erase_if``, ``cm::ssize``
 178
 179   * ``<cm/string_view>``:
 180     ``cm::ssize``
 181
 182   * ``<cm/string>``:
 183     ``cm::erase``, ``cm::erase_if``, ``cm::ssize``
 184
 185   * ``<cm/unordered_map>``:
 186     ``cm::erase_if``, ``cm::ssize``
 187
 188   * ``<cm/unordered_set>``:
 189     ``cm::erase_if``, ``cm::ssize``
 190
 191   * ``<cm/vector>``:
 192     ``cm::erase``, ``cm::erase_if``, ``cm::ssize``
 193
 194 Additionally, some useful non-standard extensions to the C++ standard library
 195 are available in headers under the directory ``cmext/`` in namespace ``cm``.
 196 These are:
 197
 198 * ``<cmext/algorithm>``:
 199
 200   * ``cm::append``:
 201     Append elements to a sequential container.
 202
 203   * ``cm::contains``:
 204     Checks if element or key is contained in container.
 205
 206 * ``<cmext/enum_set>``
 207
 208   * ``cm::enum_set``:
 209     Container to manage set of elements from an ``enum class`` definition.
 210
 211 * ``<cmext/iterator>``:
 212
 213   * ``cm::is_terator``:
 214     Checks if a type is an iterator type.
 215
 216   * ``cm::is_input_iterator``:
 217     Checks if a type is an input iterator type.
 218
 219   * ``cm::is_range``:
 220     Checks if a type is a range type: functions ``std::begin()`` and
 221     ``std::end()`` apply.
 222
 223   * ``cm::is_input_range``:
 224     Checks if a type is an input range type: functions ``std::begin()`` and
 225     ``std::end()`` apply and return an input iterator.
 226
 227 * ``<cmext/memory>``:
 228
 229   * ``cm::static_reference_cast``:
 230     Apply a ``static_cast`` to a smart pointer.
 231
 232   * ``cm::dynamic_reference_cast``:
 233     Apply a ``dynamic_cast`` to a smart pointer.
 234
 235 * ``<cmext/type_traits>``:
 236
 237   * ``cm::is_container``:
 238     Checks if a type is a container type.
 239
 240   * ``cm::is_associative_container``:
 241     Checks if a type is an associative container type.
 242
 243   * ``cm::is_unordered_associative_container``:
 244     Checks if a type is an unordered associative container type.
 245
 246   * ``cm::is_sequence_container``:
 247     Checks if a type is a sequence container type.
 248
 249   * ``cm::is_unique_ptr``:
 250     Checks if a type is a ``std::unique_ptr`` type.
 251
 252 CMake assumes the compiler supports ``#pragma once``. Use this for all
 253 hand-written header files.
 254
 255 Dynamic Memory Management
 256 =========================
 257
 258 To ensure efficient memory management, i.e. no memory leaks, it is required
 259 to use smart pointers.  Any dynamic memory allocation must be handled by a
 260 smart pointer such as ``std::unique_ptr`` or ``std::shared_ptr``.
 261
 262 It is allowed to pass raw pointers between objects to enable objects sharing.
 263 A raw pointer **must** not be deleted. Only the object(s) owning the smart
 264 pointer are allowed to delete dynamically allocated memory.
 265
 266 Third Parties
 267 =============
 268
 269 To build CMake, some third parties are needed. Under ``Utilities``
 270 directory, are versions of these third parties which can be used as an
 271 alternate to the ones provided by the system.
 272
 273 To enable the selection of the third parties between the system and CMake ones,
 274 in CMake sources, third parties headers must be prefixed by ``cm3p/``
 275 (for example: ``<cm3p/json/reader.h>``). These wrappers are located under
 276 ``Utilities/cm3p`` directory.
 277
 278 Source Tree Layout
 279 ==================
 280
 281 The CMake source tree is organized as follows.
 282
 283 * ``Auxiliary/``:
 284   Shell and editor integration files.
 285
 286 * ``Help/``:
 287   Documentation.  See the `CMake Documentation Guide`_.
 288
 289   * ``Help/dev/``:
 290     Developer documentation.
 291
 292   * ``Help/release/dev/``:
 293     Release note snippets for development since last release.
 294
 295 * ``Licenses/``:
 296   License files for third-party libraries in binary distributions.
 297
 298 * ``Modules/``:
 299   CMake language modules installed with CMake.
 300
 301 * ``Packaging/``:
 302   Files used for packaging CMake itself for distribution.
 303
 304 * ``Source/``:
 305   Source code of CMake itself.
 306
 307 * ``Templates/``:
 308   Files distributed with CMake as implementation details for generators,
 309   packagers, etc.
 310
 311 * ``Tests/``:
 312   The test suite.  See `Tests/README.rst`_.
 313
 314 * ``Utilities/``:
 315   Scripts, third-party source code.
 316
 317   * ``Utilities/std/cm``:
 318     Support files for various C++ standards.
 319
 320   * ``Utilities/std/cmext``:
 321     Extensions to the C++ STL.
 322
 323   * ``Utilities/cm3p``:
 324     Public headers for third parties needed to build CMake.
 325
 326   * ``Utilities/Sphinx/``:
 327     Sphinx configuration to build CMake user documentation.
 328
 329   * ``Utilities/Release/``:
 330     Scripts used to package CMake itself for distribution on ``cmake.org``.
 331     See `Utilities/Release/README.rst`_.
 332
 333 .. _`CMake Documentation Guide`: documentation.rst
 334 .. _`Tests/README.rst`: ../../Tests/README.rst
 335 .. _`Utilities/Release/README.rst`: ../../Utilities/Release/README.rst