add_library/add_executable: allow local alias to imported targets

Fixes: #20641

2 files changed, 29 insertions, 4 deletions

diff --git a/Help/prop_tgt/ALIAS_GLOBAL.rst b/Help/prop_tgt/ALIAS_GLOBAL.rst
new file mode 100644
index 0000000..8854f57
--- /dev/null
+++ b/Help/prop_tgt/ALIAS_GLOBAL.rst
@@ -0,0 +1,17 @@
+ALIAS_GLOBAL
+------------
+
+Read-only property indicating of whether an :ref:`ALIAS target <Alias Targets>`
+is globally visible.
+
+The boolean value of this property is ``TRUE`` for aliases to
+:ref:`IMPORTED targets <Imported Targets>` created
+with the ``GLOBAL`` options to :command:`add_executable()` or
+:command:`add_library()`, ``FALSE`` otherwise. It is undefined for
+targets built within the project.
+
+.. note::
+
+  Promoting an :ref:`IMPORTED target <Imported Targets>` from ``LOCAL``
+  to ``GLOBAL`` scope by changing the value or :prop_tgt:`IMPORTED_GLOBAL`
+  target property do not change the scope of local aliases.
diff --git a/Help/prop_tgt/IMPORTED_GLOBAL.rst b/Help/prop_tgt/IMPORTED_GLOBAL.rst
index 1feca04..1a9129f 100644
--- a/Help/prop_tgt/IMPORTED_GLOBAL.rst
+++ b/Help/prop_tgt/IMPORTED_GLOBAL.rst
@@ -16,7 +16,15 @@ 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.
+.. note::
+
+  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.
+
+.. note::
+
+  Local :ref:`ALIAS targets <Alias Targets>` created before promoting an
+  :ref:`IMPORTED target <Imported Targets>` from ``LOCAL`` to ``GLOBAL``, keep
+  their initial scope (see :prop_tgt:`ALIAS_GLOBAL` target property).