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 **6.0** 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 in order to support building on older toolchains. However, to facilitate development, some standard library features from more recent C++ standards are supported through a compatibility layer. These features are defined under the namespace ``cm`` and headers are accessible under the ``cm/`` directory. The headers under ``cm/`` can be used in place of the standard ones when extended features are needed. For example ```` can be used in place of ````. Available features are: * From ``C++14``: * ````: ``cm::quoted`` * ````: ``cm::make_reverse_iterator``, ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``, ``cm::crbegin``, ``cm::crend`` * ````: ``cm::make_unique`` * ````: ``cm::shared_lock`` * ````: ``cm::enable_if_t`` * From ``C++17``: * ````: ``cm::clamp`` * ``cm/filesystem>``: ``cm::filesystem::path`` * ````: ``cm::size``, ``cm::empty``, ``cm::data`` * ````: ``cm::nullopt_t``, ``cm::nullopt``, ``cm::optional``, ``cm::make_optional``, ``cm::bad_optional_access`` * ````: ``cm::shared_mutex`` * ````: ``cm::string_view`` * ````: ``cm::bool_constant``, ``cm::invoke_result_t``, ``cm::invoke_result``, ``cm::void_t`` * ````: ``cm::in_place_t``, ``cm::in_place`` * From ``C++20``: * ````: ``cm::erase``, ``cm::erase_if`` * ````: ``cm::erase``, ``cm::erase_if`` * ```` : ``cm::erase_if`` * ```` : ``cm::erase_if`` * ````: ``cm::erase``, ``cm::erase_if`` * ````: ``cm::erase_if`` * ````: ``cm::erase_if`` * ````: ``cm::erase``, ``cm::erase_if`` Additionally, some useful non-standard extensions to the C++ standard library are available in headers under the directory ``cmext/`` in namespace ``cm``. These are: * ````: * ``cm::append``: Append elements to a sequential container. * ``cm::contains``: Checks if element or key is contained in container. * ````: * ``cm::is_terator``: Checks if a type is an iterator type. * ``cm::is_input_iterator``: Checks if a type is an input iterator type. * ``cm::is_range``: Checks if a type is a range type: functions ``std::begin()`` and ``std::end()`` apply. * ``cm::is_input_range``: Checks if a type is an input range type: functions ``std::begin()`` and ``std::end()`` apply and return an input iterator. * ````: * ``cm::static_reference_cast``: Apply a ``static_cast`` to a smart pointer. * ``cm::dynamic_reference_cast``: Apply a ``dynamic_cast`` to a smart pointer. * ````: * ``cm::is_container``: Checks if a type is a container type. * ``cm::is_associative_container``: Checks if a type is an associative container type. * ``cm::is_unordered_associative_container``: Checks if a type is an unordered associative container type. * ``cm::is_sequence_container``: Checks if a type is a sequence container type. * ``cm::is_unique_ptr``: Checks if a type is a ``std::unique_ptr`` type. CMake assumes the compiler supports ``#pragma once``. Use this for all hand-written header files. Dynamic Memory Management ========================= To ensure efficient memory management, i.e. no memory leaks, it is required to use smart pointers. Any dynamic memory allocation must be handled by a smart pointer such as ``std::unique_ptr`` or ``std::shared_ptr``. It is allowed to pass raw pointers between objects to enable objects sharing. A raw pointer **must** not be deleted. Only the object(s) owning the smart pointer are allowed to delete dynamically allocated memory. Third Parties ============= To build CMake, some third parties are needed. Under ``Utilities`` directory, are versions of these third parties which can be used as an alternate to the ones provided by the system. To enable the selection of the third parties between the system and CMake ones, in CMake sources, third parties headers must be prefixed by ``cm3p/`` (for example: ````). These wrappers are located under ``Utilities/cm3p`` directory. Source Tree Layout ================== The CMake source tree is organized as follows. * ``Auxiliary/``: Shell and editor integration files. * ``Help/``: Documentation. See the `CMake Documentation Guide`_. * ``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/std/cm``: Support files for various C++ standards. * ``Utilities/std/cmext``: Extensions to the C++ STL. * ``Utilities/cm3p``: Public headers for third parties needed to build CMake. * ``Utilities/Sphinx/``: Sphinx configuration to build CMake user documentation. * ``Utilities/Release/``: Scripts used to package CMake itself for distribution on ``cmake.org``. See `Utilities/Release/README.rst`_. .. _`CMake Documentation Guide`: documentation.rst .. _`Tests/README.rst`: ../../Tests/README.rst .. _`Utilities/Release/README.rst`: ../../Utilities/Release/README.rst