summaryrefslogtreecommitdiffstats
path: root/Help/dev/source.rst
blob: d0c19eba17bf703d8927d66d336fbe16ac70ebfc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
CMake Source Code Guide
***********************

The following is a guide to the CMake source code for developers.
See documentation on `CMake Development`_ for more information.

.. _`CMake Development`: README.rst

C++ Code Style
==============

We use `clang-format`_ version **3.8** to define our style for C++ code in
the CMake source tree.  See the `.clang-format`_ configuration file for our
style settings.  Use the `Utilities/Scripts/clang-format.bash`_ script to
format source code.  It automatically runs ``clang-format`` on the set of
source files for which we enforce style.  The script also has options to
format only a subset of files, such as those that are locally modified.

.. _`clang-format`: http://clang.llvm.org/docs/ClangFormat.html
.. _`.clang-format`: ../../.clang-format
.. _`Utilities/Scripts/clang-format.bash`: ../../Utilities/Scripts/clang-format.bash

C++ Subset Permitted
====================

CMake requires compiling as C++11 or above.  However, in order to support
building on older toolchains some constructs need to be handled with care:

* Do not use ``std::auto_ptr``.

  The ``std::auto_ptr`` template is deprecated in C++11. Use ``std::unique_ptr``.

* Use ``CM_DISABLE_COPY(Class)`` to mark classes as non-copyable.

  The ``CM_DISABLE_COPY`` macro should be used in the private section of a
  class to make sure that attempts to copy or assign an instance of the class
  lead to compiler errors even if the compiler does not support *deleted*
  functions.  As a guideline, all polymorphic classes should be made
  non-copyable in order to avoid slicing.  Classes that are composed of or
  derived from non-copyable classes must also be made non-copyable explicitly
  with ``CM_DISABLE_COPY``.

* Use ``size_t`` instead of ``std::size_t``.

  Various implementations have differing implementation of ``size_t``.
  When assigning the result of ``.size()`` on a container for example,
  the result should be assigned to ``size_t`` not to ``std::size_t``,
  ``unsigned int`` or similar types.

Source Tree Layout
==================

The CMake source tree is organized as follows.

* ``Auxiliary/``:
  Shell and editor integration files.

* ``Help/``:
  Documentation.

  * ``Help/dev/``:
    Developer documentation.

  * ``Help/release/dev/``:
    Release note snippets for development since last release.

* ``Licenses/``:
  License files for third-party libraries in binary distributions.

* ``Modules/``:
  CMake language modules installed with CMake.

* ``Packaging/``:
  Files used for packaging CMake itself for distribution.

* ``Source/``:
  Source code of CMake itself.

* ``Templates/``:
  Files distributed with CMake as implementation details for generators,
  packagers, etc.

* ``Tests/``:
  The test suite.  See `Tests/README.rst`_.

* ``Utilities/``:
  Scripts, third-party source code.

  * ``Utilities/Sphinx/``:
    Sphinx configuration to build CMake user documentation.

  * ``Utilities/Release/``:
    Scripts used to package CMake itself for distribution on ``cmake.org``.

.. _`Tests/README.rst`: ../../Tests/README.rst