Merge topic 'doc-src-bld-selection' into release-3.23

fea270d3ed Help: Document cmake source and binary dir selection rules

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !7076

1 files changed, 20 insertions, 0 deletions

diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index f7d4f6b6d0..9a2b2ef8fa 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -151,6 +151,26 @@ source and build trees and generate a buildsystem:
 
 In all cases the ``<options>`` may be zero or more of the `Options`_ below.
 
+The above styles for specifying the source and build trees may be mixed.
+Paths specified with ``-S`` or ``-B`` are always classified as source or
+build trees, respectively.  Paths specified with plain arguments are
+classified based on their content and the types of paths given earlier.
+If only one type of path is given, the current working directory (cwd)
+is used for the other.  For example:
+
+============================== ============ ===========
+ Command Line                   Source Dir   Build Dir
+============================== ============ ===========
+ ``cmake src``                  ``src``      `cwd`
+ ``cmake build`` (existing)     `loaded`     ``build``
+ ``cmake -S src``               ``src``      `cwd`
+ ``cmake -S src build``         ``src``      ``build``
+ ``cmake -S src -B build``      ``src``      ``build``
+ ``cmake -B build``             `cwd`        ``build``
+ ``cmake -B build src``         ``src``      ``build``
+ ``cmake -B build -S src``      ``src``      ``build``
+============================== ============ ===========
+
 After generating a buildsystem one may use the corresponding native
 build tool to build the project.  For example, after using the
 :generator:`Unix Makefiles` generator one may run ``make`` directly: