From 540b4cdc2bd7cb824c6cf7403857844b4fce4d6e Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 19 Apr 2017 16:10:16 -0400 Subject: Help/dev: Add a CMake Source Code Guide placeholder Create a dedicated document to cover the CMake source code for developers. --- Help/dev/README.rst | 9 +++++++++ Help/dev/source.rst | 7 +++++++ 2 files changed, 16 insertions(+) create mode 100644 Help/dev/source.rst diff --git a/Help/dev/README.rst b/Help/dev/README.rst index 0dc512a..163be97 100644 --- a/Help/dev/README.rst +++ b/Help/dev/README.rst @@ -29,3 +29,12 @@ following documents: .. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake .. _`CMake Review Process`: review.rst .. _`CMake Testing Process`: testing.rst + +Developer Documentation +======================= + +CMake developer documentation is provided by the following documents: + +* The `CMake Source Code Guide`_. + +.. _`CMake Source Code Guide`: source.rst diff --git a/Help/dev/source.rst b/Help/dev/source.rst new file mode 100644 index 0000000..dfde290 --- /dev/null +++ b/Help/dev/source.rst @@ -0,0 +1,7 @@ +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 -- cgit v0.12 From 0fd255adf52592e6443c15a68c09cfa7fc26e85b Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 19 Apr 2017 16:19:55 -0400 Subject: Help/dev: Adopt clang-format instructions in coding guide Simplify the `CONTRIBUTING.rst` document by moving the code style section over to our dedicated coding guide and linking to it instead. --- CONTRIBUTING.rst | 14 ++------------ Help/dev/source.rst | 14 ++++++++++++++ 2 files changed, 16 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 434f0f4..e219763 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -25,6 +25,7 @@ To contribute patches: #. Fork the upstream `CMake Repository`_ into a personal account. #. Run `Utilities/SetupForDevelopment.sh`_ for local configuration. +#. See the `CMake Source Code Guide`_ for coding guidelines. #. Base all new work on the upstream ``master`` branch. #. Create commits making incremental, distinct, logically complete changes. #. Push a topic branch to a personal repository fork on GitLab. @@ -35,20 +36,9 @@ The merge request will enter the `CMake Review Process`_ for consideration. .. _`Kitware's GitLab Instance`: https://gitlab.kitware.com .. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake .. _`Utilities/SetupForDevelopment.sh`: Utilities/SetupForDevelopment.sh +.. _`CMake Source Code Guide`: Help/dev/source.rst .. _`CMake Review Process`: Help/dev/review.rst -Code Style -========== - -We use `clang-format`_ to define our style for C++ code in the CMake source -tree. See the `.clang-format`_ configuration file for our style settings. -Use ``clang-format`` version 3.8 or higher to format source files. -See also the `Utilities/Scripts/clang-format.bash`_ script. - -.. _`clang-format`: http://clang.llvm.org/docs/ClangFormat.html -.. _`.clang-format`: .clang-format -.. _`Utilities/Scripts/clang-format.bash`: Utilities/Scripts/clang-format.bash - License ======= diff --git a/Help/dev/source.rst b/Help/dev/source.rst index dfde290..f70e477 100644 --- a/Help/dev/source.rst +++ b/Help/dev/source.rst @@ -5,3 +5,17 @@ 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 -- cgit v0.12 From caabb6e1f3756f317a1b856ec43d77ea80295e04 Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 19 Apr 2017 16:33:28 -0400 Subject: Help/dev: Adopt C++ subset rules in coding guide Move the C++ subset rules from the `cmake-developer(7)` into our dedicated coding guide since they do not need to be in user-facing documentation. --- Help/dev/source.rst | 21 +++++++++++++++++++++ Help/manual/cmake-developer.7.rst | 24 ------------------------ 2 files changed, 21 insertions(+), 24 deletions(-) diff --git a/Help/dev/source.rst b/Help/dev/source.rst index f70e477..3ac9aca 100644 --- a/Help/dev/source.rst +++ b/Help/dev/source.rst @@ -19,3 +19,24 @@ 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 supports compiling as C++98 in addition to C++11 and C++14. +In order to support building on older toolchains some constructs +need to be handled with care: + +* Use ``CM_AUTO_PTR`` instead of ``std::auto_ptr``. + + The ``std::auto_ptr`` template is deprecated in C++11. We want to use it + so we can build on C++98 compilers but we do not want to turn off compiler + warnings about deprecated interfaces in general. Use the ``CM_AUTO_PTR`` + macro instead. + +* 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. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index f77d8c0..cd509ac 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -13,30 +13,6 @@ Introduction This manual is intended for reference by developers modifying the CMake source tree itself, and by those authoring externally-maintained modules. - -Permitted C++ Subset -==================== - -CMake is required to build with ancient C++ compilers and standard library -implementations. Some common C++ constructs may not be used in CMake in order -to build with such toolchains. - -std::auto_ptr -------------- - -The ``std::auto_ptr`` template is deprecated in C++11. We want to use it -so we can build on C++98 compilers but we do not want to turn off compiler -warnings about deprecated interfaces in general. Use the ``CM_AUTO_PTR`` -macro instead. - -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. - Adding Compile Features ======================= -- cgit v0.12