Merge topic 'make-GENERATED-visible-from-any-scope'

573d51201a GENERATED prop: Set CMP0118 to NEW for some (unrelated) tests
6624b65b3f GENERATED prop: Add implementation for policy CMP0118 being set to NEW
b14fe704f8 GENERATED prop: Simplify determining the language of a source file
ca4ce458a3 GENERATED prop: Check CMP0118 policy and warn in certain situations
0eb30f175e GENERATED prop: Introducing policy CMP0118 and its documentation
78c8d95605 GENERATED prop: Add some tests before introducing changes with CMP0118
e01527619f Simplify code by calling a function directly instead of duplicating it
75cb8615e9 Fix typo in function name

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !5308

8 files changed, 56 insertions, 0 deletions

diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst
index 9ee7a4b..f77d8af 100644
--- a/Help/command/get_property.rst
+++ b/Help/command/get_property.rst
@@ -94,3 +94,8 @@ If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given then the variable is set to a
 string containing documentation for the requested property.  If
 documentation is requested for a property that has not been defined
 ``NOTFOUND`` is returned.
+
+.. note::
+
+  The :prop_sf:`GENERATED` source file property may be globally visible.
+  See its documentation for details.
diff --git a/Help/command/get_source_file_property.rst b/Help/command/get_source_file_property.rst
index 1e0ea9f..ae41565 100644
--- a/Help/command/get_source_file_property.rst
+++ b/Help/command/get_source_file_property.rst
@@ -40,3 +40,8 @@ file properties usually control how the file is built. One property that is
 always there is :prop_sf:`LOCATION`.
 
 See also the more general :command:`get_property` command.
+
+.. note::
+
+  The :prop_sf:`GENERATED` source file property may be globally visible.
+  See its documentation for details.
diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst
index 22e0301..bf437b4 100644
--- a/Help/command/set_property.rst
+++ b/Help/command/set_property.rst
@@ -105,3 +105,8 @@ directly set in the nominated scope, the command will behave as though
 
 See the :manual:`cmake-properties(7)` manual for a list of properties
 in each scope.
+
+.. note::
+
+  The :prop_sf:`GENERATED` source file property may be globally visible.
+  See its documentation for details.
diff --git a/Help/command/set_source_files_properties.rst b/Help/command/set_source_files_properties.rst
index f8b05ac..61c69a2 100644
--- a/Help/command/set_source_files_properties.rst
+++ b/Help/command/set_source_files_properties.rst
@@ -36,3 +36,8 @@ See also the :command:`set_property(SOURCE)` command.
 
 See :ref:`Source File Properties` for the list of properties known
 to CMake.
+
+.. note::
+
+  The :prop_sf:`GENERATED` source file property may be globally visible.
+  See its documentation for details.
diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 03eb93e..6f9a24a 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.20
 .. toctree::
    :maxdepth: 1
 
+   CMP0118: The GENERATED source file property is now visible in all directories. </policy/CMP0118>
    CMP0117: MSVC RTTI flag /GR is not added to CMAKE_CXX_FLAGS by default. </policy/CMP0117>
    CMP0116: Ninja generators transform DEPFILEs from add_custom_command(). </policy/CMP0116>
    CMP0115: Source file extensions must be explicit. </policy/CMP0115>
diff --git a/Help/policy/CMP0118.rst b/Help/policy/CMP0118.rst
new file mode 100644
index 0000000..8e71320
--- /dev/null
+++ b/Help/policy/CMP0118.rst
@@ -0,0 +1,17 @@
+CMP0118
+-------
+
+The :prop_sf:`GENERATED` source file property is now visible in all directories.
+
+Whether or not a source file is generated is an all-or-nothing global
+property of the source.  Consequently, the associated ``GENERATED``
+property is now visible from any directory scope, not only from the scope
+for which it was set.
+
+The ``OLD`` behavior of this policy is to only allow ``GENERATED`` to be
+visible from the directory scope for which it was set.  The ``NEW``
+behavior on the other hand allows it to be visible from any scope.
+
+This policy was introduced in CMake version 3.20.  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.
diff --git a/Help/prop_sf/GENERATED.rst b/Help/prop_sf/GENERATED.rst
index 48ff70c..6ef4580 100644
--- a/Help/prop_sf/GENERATED.rst
+++ b/Help/prop_sf/GENERATED.rst
@@ -3,6 +3,9 @@ GENERATED
 
 Is this source file generated as part of the build or CMake process.
 
+.. versionchanged:: 3.20
+  The GENERATED source file property is now visible in all directories.
+
 Tells the internal CMake engine that a source file is generated by an outside
 process such as another build step, or the execution of CMake itself.
 This information is then used to exempt the file from any existence or
@@ -34,3 +37,11 @@ or :prop_tgt:`AUTORCC` functionality, the :prop_gbl:`AUTOGEN_SOURCE_GROUP`,
 :prop_gbl:`AUTOMOC_SOURCE_GROUP` and :prop_gbl:`AUTORCC_SOURCE_GROUP` target
 properties may influence where the generated sources are grouped in the project's
 file lists.
+
+.. note::
+
+  Starting with CMake 3.20 the ``GENERATED`` source file property can be set
+  and retrieved from any directory scope. It is an all-or-nothing property.
+  It also can no longer be removed or unset if it was set to ``TRUE``. Policy
+  :policy:`CMP0118` was introduced to allow supporting the ``OLD`` behavior
+  for some time.
diff --git a/Help/release/dev/make-GENERATED-visible-from-any-scope.rst b/Help/release/dev/make-GENERATED-visible-from-any-scope.rst
new file mode 100644
index 0000000..7757175
--- /dev/null
+++ b/Help/release/dev/make-GENERATED-visible-from-any-scope.rst
@@ -0,0 +1,7 @@
+make-GENERATED-visible-from-any-scope
+-------------------------------------
+
+* The :prop_sf:`GENERATED` source-file property is now visible
+  from any directory scope, regardles in which scope or for what
+  scope it was set.
+  See policy :policy:`CMP0118`.