install: Teach CODE,SCRIPT modes to evaluate generator expressions

This also introduces CMP0087 which will keep the OLD behaviour of not
evaluating generator expressions

Fixes: #15785

4 files changed, 40 insertions, 0 deletions

diff --git a/Help/command/install.rst b/Help/command/install.rst
index 55c8485..a0e8c37 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -547,6 +547,11 @@ example, the code
 
 will print a message during installation.
 
+``<file>`` or ``<code>`` may use "generator expressions" with the syntax
+``$<...>`` (in the case of ``<file>``, this refers to their use in the file
+name, not the file's contents).  See the
+:manual:`cmake-generator-expressions(7)` manual for available expressions.
+
 Installing Exports
 ^^^^^^^^^^^^^^^^^^
 
diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index ed61ae0..40ec1ef 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.14
 .. toctree::
    :maxdepth: 1
 
+   CMP0087: install(SCRIPT | CODE) supports generator expressions. </policy/CMP0087>
    CMP0086: UseSWIG honors SWIG_MODULE_NAME via -module flag. </policy/CMP0086>
    CMP0085: IN_LIST generator expression handles empty list items. </policy/CMP0085>
    CMP0084: The FindQt module does not exist for find_package(). </policy/CMP0084>
diff --git a/Help/policy/CMP0087.rst b/Help/policy/CMP0087.rst
new file mode 100644
index 0000000..4c45b99
--- /dev/null
+++ b/Help/policy/CMP0087.rst
@@ -0,0 +1,29 @@
+CMP0087
+-------
+
+:command:`install(CODE)` and :command:`install(SCRIPT)` support generator
+expressions.
+
+In CMake 3.13 and earlier, :command:`install(CODE)` and
+:command:`install(SCRIPT)` did not evaluate generator expressions.  CMake 3.14
+and later will evaluate generator expressions for :command:`install(CODE)` and
+:command:`install(SCRIPT)`.
+
+The ``OLD`` behavior of this policy is for :command:`install(CODE)` and
+:command:`install(SCRIPT)` to not evaluate generator expressions.  The ``NEW``
+behavior is to evaluate generator expressions for :command:`install(CODE)` and
+:command:`install(SCRIPT)`.
+
+Note that it is the value of this policy setting at the end of the directory
+scope that is important, not its setting at the time of the call to
+:command:`install(CODE)` or :command:`install(SCRIPT)`.  This has implications
+for calling these commands from places that have their own policy scope but not
+their own directory scope (e.g. from files brought in via :command:`include()`
+rather than :command:`add_subdirectory()`).
+
+This policy was introduced in CMake version 3.14.  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/install-code-script-genex.rst b/Help/release/dev/install-code-script-genex.rst
new file mode 100644
index 0000000..a28a466
--- /dev/null
+++ b/Help/release/dev/install-code-script-genex.rst
@@ -0,0 +1,5 @@
+install-code-script-genex
+-------------------------
+
+* The :command:`install(CODE)` and :command:`install(SCRIPT)` commands
+  learned to support generator expressions.  See policy :policy:`CMP0087`.