Help: Clarify add_custom_command OUTPUT relative path behavior

Issue: #24372

1 files changed, 12 insertions, 3 deletions

diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst
index 9dd8b95..293d3f0 100644
--- a/Help/command/add_custom_command.rst
+++ b/Help/command/add_custom_command.rst
@@ -231,15 +231,24 @@ The options are:
 
 ``OUTPUT``
   Specify the output files the command is expected to produce.
-  If an output name is a relative path it will be interpreted
-  relative to the build tree directory corresponding to the
-  current source directory.
   Each output file will be marked with the :prop_sf:`GENERATED`
   source file property automatically.
   If the output of the custom command is not actually created
   as a file on disk it should be marked with the :prop_sf:`SYMBOLIC`
   source file property.
 
+  If an output file name is a relative path, its absolute path is
+  determined by interpreting it relative to:
+
+  1. the build directory corresponding to the current source directory
+     (:variable:`CMAKE_CURRENT_BINARY_DIR`), or
+
+  2. the current source directory (:variable:`CMAKE_CURRENT_SOURCE_DIR`).
+
+  The path in the build directory is preferred unless the path in the
+  source tree is mentioned as an absolute source file path elsewhere
+  in the current directory.
+
   .. versionadded:: 3.20
     Arguments to ``OUTPUT`` may use a restricted set of
     :manual:`generator expressions <cmake-generator-expressions(7)>`.