Merge topic 'max-recursion-depth'

a6982cff0d cmMakefile: Impose maximum recursion limit

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Juraj Oršulić <juraj.orsulic@fer.hr>
Merge-request: !2746

Help/manual/cmake-variables.7.rst

@@ -190,6 +190,7 @@ Variables that Change Behavior
    /variable/CMAKE_LIBRARY_PATH
    /variable/CMAKE_LINK_DIRECTORIES_BEFORE
    /variable/CMAKE_MFC_FLAG
+   /variable/CMAKE_MAXIMUM_RECURSION_DEPTH
    /variable/CMAKE_MODULE_PATH
    /variable/CMAKE_NOT_USING_CONFIG_FLAGS
    /variable/CMAKE_POLICY_DEFAULT_CMPNNNN

Help/release/dev/max-recursion-depth.rst

@@ -0,0 +1,6 @@
+max-recursion-depth
+-------------------
+
+* CMake now imposes a maximum recursion limit to prevent a stack overflow on
+  scripts that recurse infinitely. The limit can be adjusted at runtime with
+  :variable:`CMAKE_MAXIMUM_RECURSION_DEPTH`.

Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst

@@ -0,0 +1,33 @@
+CMAKE_MAXIMUM_RECURSION_DEPTH
+-----------------------------
+
+Maximum recursion depth for CMake scripts. It is intended to be set on the
+command line with ``-DCMAKE_MAXIMUM_RECURSION_DEPTH=<x>``, or within
+``CMakeLists.txt`` by projects that require a large recursion depth. Projects
+that set this variable should provide the user with a way to override it. For
+example:
+
+.. code-block:: cmake
+
+  # About to perform deeply recursive actions
+  if(NOT CMAKE_MAXIMUM_RECURSION_DEPTH)
+    set(CMAKE_MAXIMUM_RECURSION_DEPTH 2000)
+  endif()
+
+If it is not set, or is set to a non-integer value, a sensible default limit is
+used. If the recursion limit is reached, the script terminates immediately with
+a fatal error.
+
+Calling any of the following commands increases the recursion depth:
+
+* :command:`include`
+* :command:`find_package`
+* :command:`add_subdirectory`
+* :command:`try_compile`
+* :command:`ctest_read_custom_files`
+* :command:`ctest_run_script` (unless ``NEW_PROCESS`` is specified)
+* User-defined :command:`function`'s and :command:`macro`'s (note that
+  :command:`function` and :command:`macro` themselves don't increase recursion
+  depth)
+* Reading or writing variables that are being watched by a
+  :command:`variable_watch`