file(GENERATE): Add policy CMP0070 to define relative path behavior

Previously `file(GENERATE)` did not define any behavior for relative
paths given to the `OUTPUT` or `INPUT` arguments.  Define behavior
consistent with CMake conventions and add a policy to provide
compatibility for projects that relied on the old accidental behavior.

Fixes: #16786

4 files changed, 45 insertions, 0 deletions

diff --git a/Help/command/file.rst b/Help/command/file.rst
index b2e4eea..7afb715 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -291,6 +291,8 @@ from the input content to produce the output content.  The options are:
 
 ``INPUT <input-file>``
   Use the content from a given file as input.
+  A relative path is treated with respect to the value of
+  :variable:`CMAKE_CURRENT_SOURCE_DIR`.  See policy :policy:`CMP0070`.
 
 ``OUTPUT <output-file>``
   Specify the output file name to generate.  Use generator expressions
@@ -298,6 +300,9 @@ from the input content to produce the output content.  The options are:
   name.  Multiple configurations may generate the same output file only
   if the generated content is identical.  Otherwise, the ``<output-file>``
   must evaluate to an unique name for each configuration.
+  A relative path (after evaluating generator expressions) is treated
+  with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
+  See policy :policy:`CMP0070`.
 
 Exactly one ``CONTENT`` or ``INPUT`` option must be given.  A specific
 ``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``.
diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 7b85817..eb9af27 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -51,6 +51,14 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
 to determine whether to report an error on use of deprecated macros or
 functions.
 
+Policies Introduced by CMake 3.10
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   CMP0070: Define file(GENERATE) behavior for relative paths. </policy/CMP0070>
+
 Policies Introduced by CMake 3.9
 ================================
 
diff --git a/Help/policy/CMP0070.rst b/Help/policy/CMP0070.rst
new file mode 100644
index 0000000..0fb3617
--- /dev/null
+++ b/Help/policy/CMP0070.rst
@@ -0,0 +1,25 @@
+CMP0070
+-------
+
+Define :command:`file(GENERATE)` behavior for relative paths.
+
+CMake 3.10 and newer define that relative paths given to ``INPUT`` and
+``OUTPUT`` arguments of ``file(GENERATE)`` are interpreted relative to the
+current source and binary directories, respectively.  CMake 3.9 and lower did
+not define any behavior for relative paths but did not diagnose them either
+and accidentally treated them relative to the process working directory.
+Policy ``CMP0070`` provides compatibility with projects that used the old
+undefined behavior.
+
+This policy affects behavior of relative paths given to ``file(GENERATE)``.
+The ``OLD`` behavior for this policy is to treat the paths relative to the
+working directory of CMake.  The ``NEW`` behavior for this policy is to
+interpret relative paths with respect to the current source or binary
+directory of the caller.
+
+This policy was introduced in CMake version 3.10.  CMake version
+|release| warns when the policy is not set and uses ``OLD`` behavior.
+Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
+explicitly.
+
+.. include:: DEPRECATED.txt
diff --git a/Help/release/dev/file-generate-relative-paths.rst b/Help/release/dev/file-generate-relative-paths.rst
new file mode 100644
index 0000000..fdeb9e0e
--- /dev/null
+++ b/Help/release/dev/file-generate-relative-paths.rst
@@ -0,0 +1,7 @@
+file-generate-relative-paths
+----------------------------
+
+* The :command:`file(GENERATE)` command now interprets relative paths
+  given to its ``OUTPUT`` and ``INPUT`` arguments with respect to the
+  caller's current binary and source directories, respectively.
+  See policy :policy:`CMP0070`.