Merge topic 'imported-local-target-alias'

056489d567 add_library/add_executable: allow local alias to imported targets
254f2b9058 Help: add_executable: Add TOC

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

6 files changed, 61 insertions, 10 deletions

diff --git a/Help/command/add_executable.rst b/Help/command/add_executable.rst
index 0a7d7e1..e073228 100644
--- a/Help/command/add_executable.rst
+++ b/Help/command/add_executable.rst
@@ -1,8 +1,15 @@
 add_executable
 --------------
 
+.. only:: html
+
+  .. contents::
+
 Add an executable to the project using the specified source files.
 
+Normal Executables
+^^^^^^^^^^^^^^^^^^
+
 .. code-block:: cmake
 
   add_executable(<name> [WIN32] [MACOSX_BUNDLE]
@@ -45,7 +52,8 @@ See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are
 pre-processed, and you want to have the original sources reachable from
 within IDE.
 
---------------------------------------------------------------------------
+Imported Executables
+^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: cmake
 
@@ -65,7 +73,8 @@ whose names begin in ``IMPORTED_``.  The most important such property is
 the main executable file on disk.  See documentation of the ``IMPORTED_*``
 properties for more information.
 
---------------------------------------------------------------------------
+Alias Executables
+^^^^^^^^^^^^^^^^^
 
 .. code-block:: cmake
 
@@ -74,8 +83,13 @@ properties for more information.
 Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can
 be used to refer to ``<target>`` in subsequent commands.  The ``<name>``
 does not appear in the generated buildsystem as a make target.  The
-``<target>`` may not be a non-``GLOBAL``
-:ref:`Imported Target <Imported Targets>` or an ``ALIAS``.
+``<target>`` may not be an ``ALIAS``.
+
+An ``ALIAS`` to a non-``GLOBAL`` :ref:`Imported Target <Imported Targets>`
+has scope in the directory in which the alias is created and below.
+The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the
+alias is global or not.
+
 ``ALIAS`` targets can be used as targets to read properties
 from, executables for custom commands and custom targets.  They can also be
 tested for existence with the regular :command:`if(TARGET)` subcommand.
diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst
index 7274e44..01c415a 100644
--- a/Help/command/add_library.rst
+++ b/Help/command/add_library.rst
@@ -139,8 +139,13 @@ Alias Libraries
 Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
 used to refer to ``<target>`` in subsequent commands.  The ``<name>`` does
 not appear in the generated buildsystem as a make target.  The ``<target>``
-may not be a non-``GLOBAL`` :ref:`Imported Target <Imported Targets>` or an
-``ALIAS``.
+may not be an ``ALIAS``.
+
+An ``ALIAS`` to a non-``GLOBAL`` :ref:`Imported Target <Imported Targets>`
+has scope in the directory in which the alias is created and below.
+The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the
+alias is global or not.
+
 ``ALIAS`` targets can be used as linkable targets and as targets to
 read properties from.  They can also be tested for existence with the
 regular :command:`if(TARGET)` subcommand.  The ``<name>`` may not be used
diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index a68170a..7f7ed50 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -105,6 +105,7 @@ Properties on Targets
 
    /prop_tgt/ADDITIONAL_CLEAN_FILES
    /prop_tgt/AIX_EXPORT_ALL_SYMBOLS
+   /prop_tgt/ALIAS_GLOBAL
    /prop_tgt/ALIASED_TARGET
    /prop_tgt/ANDROID_ANT_ADDITIONAL_OPTIONS
    /prop_tgt/ANDROID_API
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).
diff --git a/Help/release/dev/alias-local-imported-target.rst b/Help/release/dev/alias-local-imported-target.rst
new file mode 100644
index 0000000..026d793
--- /dev/null
+++ b/Help/release/dev/alias-local-imported-target.rst
@@ -0,0 +1,6 @@
+alias-local-imported-target
+---------------------------
+
+* :command:`add_library` and :command:`add_executable` gain the capability
+  to create an ``ALIAS`` to
+  non-``GLOBAL`` :ref:`Imported Target <Imported Targets>`.