Help: Presets read by --preset must be in the source directory

Issue: #21911

1 files changed, 21 insertions, 15 deletions

diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index 621c005..afabb75 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -507,27 +507,33 @@ Options
 
 .. option:: --preset <preset>, --preset=<preset>
 
- Reads a :manual:`preset <cmake-presets(7)>` from
- ``<path-to-source>/CMakePresets.json`` and
- ``<path-to-source>/CMakeUserPresets.json``. The preset may specify the
- generator and the build directory, and a list of variables and other
- arguments to pass to CMake. The current working directory must contain
- CMake preset files. The :manual:`CMake GUI <cmake-gui(1)>` can
- also recognize ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. For
- full details on these files, see :manual:`cmake-presets(7)`.
-
- The presets are read before all other command line options. The options
- specified by the preset (variables, generator, etc.) can all be overridden by
- manually specifying them on the command line. For example, if the preset sets
- a variable called ``MYVAR`` to ``1``, but the user sets it to ``2`` with a
- ``-D`` argument, the value ``2`` is preferred.
+ Reads a :manual:`preset <cmake-presets(7)>` from ``CMakePresets.json`` and
+ ``CMakeUserPresets.json`` files, which must be located in the same directory
+ as the top level ``CMakeLists.txt`` file. The preset may specify the
+ generator, the build directory, a list of variables, and other arguments to
+ pass to CMake. At least one of ``CMakePresets.json`` or
+ ``CMakeUserPresets.json`` must be present.
+ The :manual:`CMake GUI <cmake-gui(1)>` also recognizes and supports
+ ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. For full details
+ on these files, see :manual:`cmake-presets(7)`.
+
+ The presets are read before all other command line options, although the
+ :option:`-S <cmake -S>` option can be used to specify the source directory
+ containing the ``CMakePresets.json`` and ``CMakeUserPresets.json`` files.
+ If :option:`-S <cmake -S>` is not given, the current directory is assumed to
+ be the top level source directory and must contain the presets files. The
+ options specified by the chosen preset (variables, generator, etc.) can all
+ be overridden by manually specifying them on the command line. For example,
+ if the preset sets a variable called ``MYVAR`` to ``1``, but the user sets
+ it to ``2`` with a ``-D`` argument, the value ``2`` is preferred.
 
 .. option:: --list-presets[=<type>]
 
  Lists the available presets of the specified ``<type>``.  Valid values for
  ``<type>`` are ``configure``, ``build``, ``test``, ``package``, or ``all``.
  If ``<type>`` is omitted, ``configure`` is assumed.  The current working
- directory must contain CMake preset files.
+ directory must contain CMake preset files unless the :option:`-S <cmake -S>`
+ option is used to specify a different top level source directory.
 
 .. option:: --debugger