Help: Document conversion of PATH/FILEPATH cache values to absolute paths

Suggested-by: Roger Leigh <[email protected]>

Help/command/set.rst

@@ -70,6 +70,15 @@ Furthermore, any normal variable binding in the current scope will
 be removed to expose the newly cached value to any immediately
 following evaluation.
 
+It is possible for the cache entry to exist prior to the call but
+have no type set if it was created on the :manual:`cmake(1)` command
+line by a user through the ``-D<var>=<value>`` option without
+specifying a type.  In this case the ``set`` command will add the
+type.  Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH``
+and the ``<value>`` provided on the command line is a relative path,
+then the ``set`` command will treat the path as relative to the
+current working directory and convert it to an absolute path.
+
 Set Environment Variable
 ^^^^^^^^^^^^^^^^^^^^^^^^
 

Help/manual/OPTIONS_BUILD.txt

@@ -10,7 +10,7 @@
  containing SET commands that use the CACHE option, not a
  cache-format file.
 
-``-D <var>:<type>=<value>``
+``-D <var>:<type>=<value>, -D <var>=<value>``
  Create a cmake cache entry.
 
  When cmake is first run in an empty build tree, it creates a
@@ -19,6 +19,14 @@
  takes priority over the project's default value.  The option may be
  repeated for as many cache entries as desired.
 
+ If the ``:<type>`` portion is given it must be one of the types
+ specified by the :command:`set` command documentation for its
+ ``CACHE`` signature.
+ If the ``:<type>`` portion is omitted the entry will be created
+ with no type if it does not exist with a type already.  If a
+ command in the project sets the type to ``PATH`` or ``FILEPATH``
+ then the ``<value>`` will be converted to an absolute path.
+
 ``-U <globbing_expr>``
  Remove matching entries from CMake cache.