Add new target-property `IMPORTED_GLOBAL`.

The purpose of this new `IMPORTED_GLOBAL` target-property is to prolong
the lifetime and scope of `IMPORTED` targets in such a way as if they
had been created with the keyword `GLOBAL` in the first place.

* It can only be set to `TRUE`. That means, a local `IMPORTED` target
  can be promoted to global scope but a global `IMPORTED` target cannot
  be degraded to local scope!
* Setting it to `TRUE` only succeeds if done from within the same
  directory in which the `IMPORTED` target was created in the first
  place.

Fixes #17256.

3 files changed, 38 insertions, 0 deletions

diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 13b22f8..2c63c4b 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -184,6 +184,7 @@ Properties on Targets
    /prop_tgt/HAS_CXX
    /prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
    /prop_tgt/IMPORTED_CONFIGURATIONS
+   /prop_tgt/IMPORTED_GLOBAL
    /prop_tgt/IMPORTED_IMPLIB_CONFIG
    /prop_tgt/IMPORTED_IMPLIB
    /prop_tgt/IMPORTED_LIBNAME_CONFIG
diff --git a/Help/prop_tgt/IMPORTED_GLOBAL.rst b/Help/prop_tgt/IMPORTED_GLOBAL.rst
new file mode 100644
index 0000000..1feca04
--- /dev/null
+++ b/Help/prop_tgt/IMPORTED_GLOBAL.rst
@@ -0,0 +1,22 @@
+IMPORTED_GLOBAL
+---------------
+
+Indication of whether an :ref:`IMPORTED target <Imported Targets>` is
+globally visible.
+
+The boolean value of this property is True for targets created with the
+``IMPORTED`` ``GLOBAL`` options to :command:`add_executable()` or
+:command:`add_library()`. It is always False for targets built within the
+project.
+
+For targets created with the ``IMPORTED`` option to
+:command:`add_executable()` or :command:`add_library()` but without the
+additional option ``GLOBAL`` this is False, too. However, setting this
+property for such a locally ``IMPORTED`` target to True promotes that
+target to global scope. This promotion can only be done in the same
+directory where that ``IMPORTED`` target was created in the first place.
+
+Once an imported target has been made global, it cannot be changed back to
+non-global. Therefore, if a project sets this property, it may only
+provide a value of True. CMake will issue an error if the project tries to
+set the property to a non-True value, even if the value was already False.
diff --git a/Help/release/dev/imported-promotion.rst b/Help/release/dev/imported-promotion.rst
new file mode 100644
index 0000000..d184178
--- /dev/null
+++ b/Help/release/dev/imported-promotion.rst
@@ -0,0 +1,15 @@
+imported-promotion
+------------------
+
+* Added new target-property :prop_tgt:`IMPORTED_GLOBAL` which
+  indicates if an :ref:`IMPORTED target <Imported Targets>` is
+  globally visible.
+  It will be set automatically if such an imported target is
+  created with the ``GLOBAL`` flag.
+
+* Additionally, it is now also possible to promote a local imported
+  target to become globally visible by setting its
+  :prop_tgt:`IMPORTED_GLOBAL` property to `TRUE`. (However, this
+  promotion can only succeed if it is done from within the same
+  directory where the imported target was created in the first
+  place.) Setting it to `FALSE` is not supported!