diff options
Diffstat (limited to 'Help/dev')
| -rw-r--r-- | Help/dev/review.rst | 86 | ||||
| -rw-r--r-- | Help/dev/source.rst | 162 | ||||
| -rw-r--r-- | Help/dev/testing.rst | 2 |
3 files changed, 207 insertions, 43 deletions
diff --git a/Help/dev/review.rst b/Help/dev/review.rst index 8ec41d29c..6c7e92cf8 100644 --- a/Help/dev/review.rst +++ b/Help/dev/review.rst @@ -28,7 +28,7 @@ request is accepted" option when creating the MR or by editing it. This will cause the MR topic branch to be automatically removed from the user's fork during the `Merge`_ step. -.. _`CMake Merge Requests Page`: https://gitlab.kitware.com/cmake/cmake/merge_requests +.. _`CMake Merge Requests Page`: https://gitlab.kitware.com/cmake/cmake/-/merge_requests .. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake Workflow Status @@ -60,7 +60,7 @@ in GitLab to track the state of a MR: The workflow status labels are intended to be mutually exclusive, so please remove any existing workflow label when adding one. -.. _`CMake GitLab Project Developers`: https://gitlab.kitware.com/cmake/cmake/settings/members +.. _`CMake GitLab Project Developers`: https://gitlab.kitware.com/cmake/cmake/-/settings/members Robot Review ============ @@ -278,42 +278,52 @@ merging. Topic Testing ============= -CMake has a `buildbot`_ instance watching for merge requests to test. -`CMake GitLab Project Developers`_ may activate buildbot on a MR by -adding a comment with a command among the `comment trailing lines`_:: +CMake uses `GitLab CI`_ to test merge requests, configured by the top-level +``.gitlab-ci.yml`` file. Results may be seen both on the merge request's +pipeline page and on the `CMake CDash Page`_. Filtered CDash results +showing just the pipeline's jobs can be reached by selecting the ``cdash`` +job in the ``External`` stage of the pipeline. - Do: test +Lint and documentation build jobs run automatically after every push. +Heavier jobs require a manual trigger to run: -``@kwrobot`` will add an award emoji to the comment to indicate that it -was processed and also inform buildbot about the request. The buildbot -user (``@buildbot``) will schedule builds and respond with a comment -linking to the `CMake CDash Page`_ with a filter for results associated -with the topic test request. If the MR topic branch is updated by a -push a new ``Do: test`` command is needed to activate testing again. - -The ``Do: test`` command accepts the following arguments: - -* ``--stop``: clear the list of commands for the merge request -* ``--clear``: clear previous commands before adding this command -* ``--regex-include <arg>`` or ``-i <arg>``: only build on builders - matching ``<arg>`` (a Python regular expression) -* ``--regex-exclude <arg>`` or ``-e <arg>``: exclude builds on builders - matching ``<arg>`` (a Python regular expression) - -Builder names follow the pattern ``project-host-os-buildtype-generator``: - -* ``project``: always ``cmake`` for CMake builds -* ``host``: the buildbot host -* ``os``: one of ``windows``, ``osx``, or ``linux`` -* ``buildtype``: ``release`` or ``debug`` -* ``generator``: ``ninja``, ``makefiles``, ``vs<year>``, - or ``lint-iwyu-tidy`` - -The special ``lint-<tools>`` generator name is a builder that builds -CMake using lint tools but does not run the test suite (so the actual -generator does not matter). - -.. _`buildbot`: http://buildbot.net +* Merge request authors may visit their merge request's pipeline and click the + "Play" button on one or more jobs manually. If the merge request has the + "Allow commits from members who can merge to the target branch" check box + enabled, CMake maintainers may use the "Play" button too. + +* `CMake GitLab Project Developers`_ may trigger CI on a merge request by + adding a comment with a command among the `comment trailing lines`_:: + + Do: test + + ``@kwrobot`` will add an award emoji to the comment to indicate that it + was processed and also trigger all manual jobs in the merge request's + pipeline. + + The ``Do: test`` command accepts the following arguments: + + * ``--named <regex>``, ``-n <regex>``: Trigger jobs matching ``<regex>`` + anywhere in their name. Job names may be seen on the merge request's + pipeline page. + * ``--stage <stage>``, ``-s <stage>``: Only affect jobs in a given stage. + Stage names may be seen on the merge request's pipeline page. Note that + the names are determined by what is in the ``.gitlab-ci.yml`` file and may + be capitalized in the web page, so lowercasing the webpage's display name + for stages may be required. + * ``--action <action>``, ``-a <action>``: The action to perform on the jobs. + Possible actions: + + * ``manual`` (the default): Start jobs awaiting manual interaction. + * ``unsuccessful``: Start or restart jobs which have not completed + successfully. + * ``failed``: Restart jobs which have completed, but without success. + * ``completed``: Restart all completed jobs. + +If the merge request topic branch is updated by a push, a new manual trigger +using one of the above methods is needed to start CI again. + +.. _`GitLab CI`: https://gitlab.kitware.com/help/ci/README.md .. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake Integration Testing @@ -454,8 +464,8 @@ comment instead): The ``-t`` option to a ``Do: merge`` command overrides any topic rename set in the MR description. -.. _`CMake GitLab Project Masters`: https://gitlab.kitware.com/cmake/cmake/settings/members -.. _`backport instructions`: https://gitlab.kitware.com/utils/git-workflow/wikis/Backport-topics +.. _`CMake GitLab Project Masters`: https://gitlab.kitware.com/cmake/cmake/-/settings/members +.. _`backport instructions`: https://gitlab.kitware.com/utils/git-workflow/-/wikis/Backport-topics .. _`git rev-parse`: https://git-scm.com/docs/git-rev-parse Close diff --git a/Help/dev/source.rst b/Help/dev/source.rst index 0f7488be0..0ccb8f42d 100644 --- a/Help/dev/source.rst +++ b/Help/dev/source.rst @@ -23,12 +23,157 @@ format only a subset of files, such as those that are locally modified. 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: +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 ``<cm/memory>`` can be used in place of ``<memory>``. -* Do not use ``std::auto_ptr``. +Available features are: - The ``std::auto_ptr`` template is deprecated in C++11. Use ``std::unique_ptr``. +* From ``C++14``: + + * ``<cm/iterator>``: + ``cm::make_reverse_iterator``, ``cm::cbegin``, ``cm::cend``, + ``cm::rbegin``, ``cm::rend``, ``cm::crbegin``, ``cm::crend`` + + * ``<cm/memory>``: + ``cm::make_unique`` + + * ``<cm/shared_mutex>``: + ``cm::shared_lock`` + + * ``<cm/type_traits>``: + ``cm::enable_if_t`` + +* From ``C++17``: + + * ``<cm/algorithm>``: + ``cm::clamp`` + + * ``<cm/iterator>``: + ``cm::size``, ``cm::empty``, ``cm::data`` + + * ``<cm/optional>``: + ``cm::nullopt_t``, ``cm::nullopt``, ``cm::optional``, + ``cm::make_optional``, ``cm::bad_optional_access`` + + * ``<cm/shared_mutex>``: + ``cm::shared_mutex`` + + * ``<cm/string_view>``: + ``cm::string_view`` + + * ``<cm/type_traits>``: + ``cm::bool_constant``, ``cm::invoke_result_t``, ``cm::invoke_result``, + ``cm::void_t`` + + * ``<cm/utility>``: + ``cm::in_place_t``, ``cm::in_place`` + +* From ``C++20``: + + * ``<cm/deque>``: + ``cm::erase``, ``cm::erase_if`` + + * ``<cm/list>``: + ``cm::erase``, ``cm::erase_if`` + + * ``<cm/map>`` : + ``cm::erase_if`` + + * ``<cm/set>`` : + ``cm::erase_if`` + + * ``<cm/string>``: + ``cm::erase``, ``cm::erase_if`` + + * ``<cm/unordered_map>``: + ``cm::erase_if`` + + * ``<cm/unordered_set>``: + ``cm::erase_if`` + + * ``<cm/vector>``: + ``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: + +* ``<cmext/algorithm>``: + + * ``cm::append``: + Append elements to a sequential container. + + * ``cm::contains``: + Checks if element or key is contained in container. + +* ``<cmext/iterator>``: + + * ``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. + +* ``<cmext/memory>``: + + * ``cm::static_reference_cast``: + Apply a ``static_cast`` to a smart pointer. + + * ``cm::dynamic_reference_cast``: + Apply a ``dynamic_cast`` to a smart pointer. + +* ``<cmext/type_traits>``: + + * ``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. + +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: ``<cm3p/json/reader.h>``). These wrappers are located under +``Utilities/cm3p`` directory. Source Tree Layout ================== @@ -69,6 +214,15 @@ The CMake source tree is organized as follows. * ``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. diff --git a/Help/dev/testing.rst b/Help/dev/testing.rst index 23d0ca3f2..279e4b29f 100644 --- a/Help/dev/testing.rst +++ b/Help/dev/testing.rst @@ -33,7 +33,7 @@ CTest script with local settings and include ``cmake_common.cmake``. .. _`CMake Review Process`: review.rst .. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake .. _`CMake Dashboard Scripts Repository`: https://gitlab.kitware.com/cmake/dashboard-scripts -.. _`cmake_common.cmake`: https://gitlab.kitware.com/cmake/dashboard-scripts/blob/master/cmake_common.cmake +.. _`cmake_common.cmake`: https://gitlab.kitware.com/cmake/dashboard-scripts/-/blob/master/cmake_common.cmake Nightly Start Time ------------------ |