Merge topic 'genex-LINK_LIBRARY-to-decorate-library'

2a6b0415d7 $<LINK_LIBRARY>: Add LINK_LIBRARY_OVERRIDE target property
42965799b4 Genex: Add $<LINK_LIBRARY:...>
78dd7d5292 cmRulePlaceholderExpander: add base class for placeholder expansion reuse
4b55828a9f cmExpandListWithBacktrace: add handling of empty elements.
28d7432468 cmComputeLinkInformation: use cmComputeLinkDepends::LinkEntry

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

12 files changed, 392 insertions, 0 deletions

diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst
index df13dd0..7c34671 100644
--- a/Help/manual/cmake-generator-expressions.7.rst
+++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -1113,6 +1113,83 @@ Output-Related Expressions
   property, perhaps via the :command:`target_link_libraries` command,
   to specify private link dependencies without other usage requirements.
 
+.. genex:: $<LINK_LIBRARY:feature,library-list>
+
+  .. versionadded:: 3.24
+
+  Manage how libraries are specified during the link step.
+  This expression may be used to specify how to link libraries in a target.
+  For example:
+
+  .. code-block:: cmake
+
+    add_library(lib1 STATIC ...)
+    add_library(lib2 ...)
+    target_link_libraries(lib2 PRIVATE $<LINK_LIBRARY:whole_archive,lib1>)
+
+  This specify to use the ``lib1`` target with feature ``whole_archive`` for
+  linking target ``lib2``. The feature must have be defined by
+  :variable:`CMAKE_<LANG>_LINK_USING_<FEATURE>` variable or, if
+  :variable:`CMAKE_<LANG>_LINK_USING_<FEATURE>_SUPPORTED` is false,
+  by :variable:`CMAKE_LINK_USING_<FEATURE>` variable.
+
+  .. note::
+
+    The evaluation of this generator expression will use, for the following
+    variables, the values defined at the level of the creation of the target:
+
+    * :variable:`CMAKE_<LANG>_LINK_USING_<FEATURE>_SUPPORTED`
+    * :variable:`CMAKE_<LANG>_LINK_USING_<FEATURE>`
+    * :variable:`CMAKE_LINK_USING_<FEATURE>_SUPPORTED`
+    * :variable:`CMAKE_LINK_USING_<FEATURE>`
+
+  This expression can only be used to specify link libraries (i.e. part of
+  :command:`link_libraries` or :command:`target_link_libraries` commands and
+  :prop_tgt:`LINK_LIBRARIES` or :prop_tgt:`INTERFACE_LINK_LIBRARIES` target
+  properties).
+
+  .. note::
+
+    If this expression appears in the :prop_tgt:`INTERFACE_LINK_LIBRARIES`
+    property of a target, it will be included in the imported target generated
+    by :command:`install(EXPORT)` command. It is the responsibility of the
+    environment consuming this import to define the link feature used by this
+    expression.
+
+  The ``library-list`` argument can hold CMake targets or external libraries.
+  Any ``CMake`` target of type :ref:`OBJECT <Object Libraries>` or
+  :ref:`INTERFACE <Interface Libraries>` will be ignored by this expression and
+  will be handled in the standard way.
+
+  Each target or external library involved in the link step must have only one
+  kind of feature (the absence of feature is also incompatible with any
+  feature). For example:
+
+  .. code-block:: cmake
+
+    add_library(lib1 ...)
+
+    add_library(lib2 ...)
+    target_link_libraries(lib2 PUBLIC $<LINK_LIBRARY:feature1,lib1>)
+
+    add_library(lib3 ...)
+    target_link_libraries(lib3 PRIVATE lib1 lib2)
+    # an error will be raised here because lib1 has two different features
+
+  To resolve such incompatibilities, the :prop_tgt:`LINK_LIBRARY_OVERRIDE`
+  and  :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties can be
+  used.
+
+  .. note::
+
+    This expression does not guarantee that the list of specified libraries
+    will be kept grouped. So, constructs like ``start-group`` and
+    ``end-group``, as supported by ``GNU ld``, cannot be used.
+
+  ``CMake`` pre-defines some features of general interest:
+
+  .. include:: ../variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt
+
 .. genex:: $<INSTALL_INTERFACE:...>
 
   Content of ``...`` when the property is exported using :command:`install(EXPORT)`,
diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 566eeae..65f9248 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -308,6 +308,8 @@ Properties on Targets
    /prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG
    /prop_tgt/LINK_LIBRARIES
    /prop_tgt/LINK_LIBRARIES_ONLY_TARGETS
+   /prop_tgt/LINK_LIBRARY_OVERRIDE
+   /prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY
    /prop_tgt/LINK_OPTIONS
    /prop_tgt/LINK_SEARCH_END_STATIC
    /prop_tgt/LINK_SEARCH_START_STATIC
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 59566b5..86e4d4c 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -440,6 +440,8 @@ Variables that Control the Build
    /variable/CMAKE_LANG_LINKER_LAUNCHER
    /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG
    /variable/CMAKE_LANG_LINK_LIBRARY_FLAG
+   /variable/CMAKE_LANG_LINK_USING_FEATURE
+   /variable/CMAKE_LANG_LINK_USING_FEATURE_SUPPORTED
    /variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG
    /variable/CMAKE_LANG_VISIBILITY_PRESET
    /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY
@@ -450,6 +452,8 @@ Variables that Control the Build
    /variable/CMAKE_LINK_INTERFACE_LIBRARIES
    /variable/CMAKE_LINK_LIBRARY_FILE_FLAG
    /variable/CMAKE_LINK_LIBRARY_FLAG
+   /variable/CMAKE_LINK_USING_FEATURE
+   /variable/CMAKE_LINK_USING_FEATURE_SUPPORTED
    /variable/CMAKE_LINK_WHAT_YOU_USE
    /variable/CMAKE_LINK_WHAT_YOU_USE_CHECK
    /variable/CMAKE_MACOSX_BUNDLE
diff --git a/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst
new file mode 100644
index 0000000..e9c76b0
--- /dev/null
+++ b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst
@@ -0,0 +1,54 @@
+LINK_LIBRARY_OVERRIDE
+---------------------
+
+.. versionadded:: 3.24
+
+To resolve incompatible features introduced by :genex:`LINK_LIBRARY` generator
+expression, this property offers the possibility to override, per ``link-item``
+(``CMake`` target or external library) involved in the link step, any defined
+features with a new one.
+
+This property takes a :ref:`;-list <CMake Language Lists>` of override
+declarations which have the following format:
+
+::
+
+  feature[,link-item]*
+
+For the list of ``link-item`` (``CMake`` target or external library) specified,
+the feature ``feature`` will be used in place of any declared feature. For
+example:
+
+.. code-block:: cmake
+
+  add_library(lib1 ...)
+  target_link_libraries(lib1 PUBLIC $<LINK_LIBRARY:feature1,external>)
+
+  add_library(lib2 ...)
+  target_link_libraries(lib2 PUBLIC $<LINK_LIBRARY:feature2,lib1>)
+
+  add_library(lib3 ...)
+  target_link_libraries(lib3 PRIVATE lib1 lib2)
+  # Here, lib1 has two different features which prevents to link lib3
+  # So, define LINK_LIBRARY_OVERRIDE property to ensure correct link
+  set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE "feature2,lib1,external")
+  # The lib1 and external will be used with FEATURE2 to link lib3
+
+It is also possible to override any feature with the pre-defined feature
+``DEFAULT`` to get the standard behavior (i.e. no feature):
+
+.. code-block:: cmake
+
+  set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE "DEFAULT,lib1"
+                                                          "feature2,external")
+  # The lib1 will be used without any feature and external will use feature2 to link lib3
+
+Contents of ``LINK_LIBRARY_OVERRIDE`` may use
+:manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+See also :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target property for
+a per linked target oriented approach to override features.
+
+For more information about features, see
+:variable:`CMAKE_<LANG>_LINK_USING_<FEATURE>`
+and :variable:`CMAKE_LINK_USING_<FEATURE>` variables.
diff --git a/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst
new file mode 100644
index 0000000..58141c9
--- /dev/null
+++ b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst
@@ -0,0 +1,45 @@
+LINK_LIBRARY_OVERRIDE_<LIBRARY>
+-------------------------------
+
+.. versionadded:: 3.24
+
+To resolve incompatible features introduced by :genex:`LINK_LIBRARY` generator
+expression, this property offers the possibility to override, for a
+``link-item`` (``CMake`` target or external library) involved in the link step,
+any defined features with a new one.
+
+This property takes a ``feature`` name which will be applied to the
+``link-item`` specified by ``<LIBRARY>`` suffix property. For example:
+
+.. code-block:: cmake
+
+  add_library(lib1 ...)
+  target_link_libraries(lib1 PUBLIC $<LINK_LIBRARY:feature1,external>)
+
+  add_library(lib2 ...)
+  target_link_libraries(lib2 PUBLIC $<LINK_LIBRARY:feature2,lib1>)
+
+  add_library(lib3 ...)
+  target_link_libraries(lib3 PRIVATE lib1 lib2)
+  # Here, lib1 has two different features which prevents to link lib3
+  # So, define LINK_LIBRARY_OVERRIDE_lib1 property to ensure correct link
+  set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 feature2)
+  # The lib1 will be used with feature2 to link lib3
+
+It is also possible to override any feature with the pre-defined feature
+``DEFAULT`` to get the standard behavior (i.e. no feature):
+
+.. code-block:: cmake
+
+  set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 DEFAULT)
+  # The lib1 will be used without any feature to link lib3
+
+Contents of ``LINK_LIBRARY_OVERRIDE_<LIBRARY>`` may use
+:manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+This property takes precedence over :prop_tgt:`LINK_LIBRARY_OVERRIDE`
+target property.
+
+For more information about features, see
+:variable:`CMAKE_<LANG>_LINK_USING_<FEATURE>`
+and :variable:`CMAKE_LINK_USING_<FEATURE>` variables.
diff --git a/Help/release/dev/Genex-LINK_LIBRARY.rst b/Help/release/dev/Genex-LINK_LIBRARY.rst
new file mode 100644
index 0000000..3234acb
--- /dev/null
+++ b/Help/release/dev/Genex-LINK_LIBRARY.rst
@@ -0,0 +1,11 @@
+Genex-LINK_LIBRARY
+------------------
+
+* The :genex:`LINK_LIBRARY` generator expression was added to manage how
+  libraries are specified during the link step. The variables
+  :variable:`CMAKE_<LANG>_LINK_USING_<FEATURE>` and
+  :variable:`CMAKE_LINK_USING_<FEATURE>` are used to define features usable by
+  the :genex:`LINK_LIBRARY` generator expression. Moreover, the
+  :prop_tgt:`LINK_LIBRARY_OVERRIDE` and
+  :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties are available
+  to resolve incompatible features.
diff --git a/Help/variable/CMAKE_LANG_LINK_USING_FEATURE.rst b/Help/variable/CMAKE_LANG_LINK_USING_FEATURE.rst
new file mode 100644
index 0000000..9d7f87a
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_LINK_USING_FEATURE.rst
@@ -0,0 +1,26 @@
+CMAKE_<LANG>_LINK_USING_<FEATURE>
+---------------------------------
+
+.. versionadded:: 3.24
+
+This variable defines, for the specified ``<FEATURE>`` and the linker language
+``<LANG>``, the expression expected by the linker when libraries are specified
+using :genex:`LINK_LIBRARY` generator expression.
+
+.. note::
+
+  Feature names defined in all uppercase are reserved to CMake.
+
+See also the associated variable
+:variable:`CMAKE_<LANG>_LINK_USING_<FEATURE>_SUPPORTED` and
+:variable:`CMAKE_LINK_USING_<FEATURE>` variable for the definition of features
+independent from the link language.
+
+.. include:: CMAKE_LINK_USING_FEATURE.txt
+
+Predefined Features
+^^^^^^^^^^^^^^^^^^^
+
+``CMake`` pre-defines some features of general interest:
+
+.. include:: LINK_LIBRARY_PREDEFINED_FEATURES.txt
diff --git a/Help/variable/CMAKE_LANG_LINK_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LANG_LINK_USING_FEATURE_SUPPORTED.rst
new file mode 100644
index 0000000..5794b15
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_LINK_USING_FEATURE_SUPPORTED.rst
@@ -0,0 +1,13 @@
+CMAKE_<LANG>_LINK_USING_<FEATURE>_SUPPORTED
+-------------------------------------------
+
+.. versionadded:: 3.24
+
+Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable
+:variable:`CMAKE_<LANG>_LINK_USING_<FEATURE>`, is supported for the linker
+language ``<LANG>``.
+
+.. note::
+
+  This variable is evaluated before the more generic variable
+  :variable:`CMAKE_LINK_USING_<FEATURE>_SUPPORTED`.
diff --git a/Help/variable/CMAKE_LINK_USING_FEATURE.rst b/Help/variable/CMAKE_LINK_USING_FEATURE.rst
new file mode 100644
index 0000000..0c9cadc
--- /dev/null
+++ b/Help/variable/CMAKE_LINK_USING_FEATURE.rst
@@ -0,0 +1,30 @@
+CMAKE_LINK_USING_<FEATURE>
+--------------------------
+
+.. versionadded:: 3.24
+
+This variable defines, for the specified ``FEATURE``, the expression expected
+by the linker, regardless the linker language, when libraries are specified
+using :genex:`LINK_LIBRARY` generator expression.
+
+.. note::
+
+  Feature names defined in all uppercase are reserved to CMake.
+
+See also the associated variable
+:variable:`CMAKE_LINK_USING_<FEATURE>_SUPPORTED` and
+:variable:`CMAKE_<LANG>_LINK_USING_<FEATURE>` variable for the definition of
+features dependent from the link language.
+
+This variable will be used by :genex:`LINK_LIBRARY` generator expression if,
+for the linker language, the variable
+:variable:`CMAKE_<LANG>_LINK_USING_<FEATURE>_SUPPORTED` is false or not set.
+
+.. include:: CMAKE_LINK_USING_FEATURE.txt
+
+Predefined Features
+^^^^^^^^^^^^^^^^^^^
+
+``CMake`` pre-defines some features of general interest:
+
+.. include:: LINK_LIBRARY_PREDEFINED_FEATURES.txt
diff --git a/Help/variable/CMAKE_LINK_USING_FEATURE.txt b/Help/variable/CMAKE_LINK_USING_FEATURE.txt
new file mode 100644
index 0000000..92fc92d
--- /dev/null
+++ b/Help/variable/CMAKE_LINK_USING_FEATURE.txt
@@ -0,0 +1,111 @@
+
+It can contain one or three elements.
+
+::
+
+  [<PREFIX>] <LIBRARY_EXPRESSION> [<SUFFIX>]
+
+When ``<PREFIX>`` and/or ``<SUFFIX>`` are specified, they encapsulate the list
+of libraries.
+
+.. note::
+
+  Even if ``<PREFIX>`` and ``<SUFFIX>`` are specified, there is not guarantee
+  that the list of specified libraries, as part of :genex:`LINK_LIBRARY`
+  generator expression, will be kept grouped. So, constructs like
+  ``start-group`` and ``end-group``, as supported by ``GNU ld``, cannot be
+  used.
+
+``<LIBRARY_EXPRESSION>`` is used to specify the decoration for each
+library. For that purpose, the patterns ``<LIBRARY>``, ``<LINK_ITEM>``, and
+``<LIB_ITEM>`` are available:
+
+* ``<LIBRARY>`` is expanded to the library as computed by CMake.
+* ``<LINK_ITEM>`` is expanded to the same expression as if the library was
+  specified in the standard way.
+* ``<LIB_ITEM>`` is equivalent to ``<LIBRARY>`` for CMake targets and is
+  expanded to the item specified by the user for external libraries.
+
+Moreover, it is possible to have different decorations for paths (CMake targets
+and external libraries specified with absolute paths) and other items specified
+by name. For that purpose, ``PATH{}`` and ``NAME{}`` wrappers can be used.
+
+For all three elements of this variable, the ``LINKER:`` prefix can be used:
+
+  .. include:: ../command/LINK_OPTIONS_LINKER.txt
+    :start-line: 3
+
+Examples
+^^^^^^^^
+
+Loading a whole static library
+""""""""""""""""""""""""""""""
+
+A common need is the capability to load a whole static library. This capability
+is offered by various environments but with a specific syntax:
+
+.. code-block:: cmake
+
+  set(CMAKE_C_LINK_USING_whole_archive_SUPPORTED TRUE)
+  if(CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
+    set(CMAKE_C_LINK_USING_whole_archive "-force_load <LIB_ITEM>")
+  elseif(CMAKE_C_COMPILER_ID STREQUAL "GNU"
+         AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
+    set(CMAKE_C_LINK_USING_whole_archive "LINKER:--push-state,--whole-archive"
+                                         "<LINK_ITEM>"
+                                         "LINKER:--pop-state")
+  elseif(CMAKE_C_COMPILER_ID STREQUAL "MSVC")
+    set(CMAKE_C_LINK_USING_whole_archive "/WHOLEARCHIVE:<LIBRARY>")
+  else()
+    # feature not yet supported for the other environments
+    set(CMAKE_C_LINK_USING_whole_archive_SUPPORTED FALSE)
+  endif()
+
+  add_library(lib1 STATIC ...)
+
+  add_library(lib2 SHARED ...)
+  if(CMAKE_C_LINK_USING_whole_archive_SUPPORTED)
+    target_link_libraries(lib2 PRIVATE
+      $<LINK_LIBRARY:whole_archive,lib1,$<IF:$<LINK_LANG_AND_ID:C,Clang>,libexternal.a,external>>)
+  else()
+    target_link_libraries(lib2 PRIVATE lib1 external)
+  endif()
+
+CMake will generate the following link expressions:
+
+* ``Clang``: ``-force_load /path/to/lib1.a -force_load libexternal.a``
+* ``GNU``: ``-Wl,--whole-archive /path/to/lib1.a -lexternal -Wl,--no-whole-archive``
+* ``MSVC``: ``/WHOLEARCHIVE:/path/to/lib1.lib /WHOLEARCHIVE:external.lib``
+
+CMake will ensure, when possible, that ``<PREFIX>`` and ``<SUFFIX>`` are
+not repeated for each library.
+
+In case of ``Clang``, the pattern ``<LIB_ITEM>`` is used because we need to
+specify the library as defined by the user, not the name computed by CMake
+(in that case ``external``).
+
+Linking a library as weak
+"""""""""""""""""""""""""
+
+On MacOS, it is possible to link a library in weak mode (the library and all
+references are marked as weak imports), but different flags must be used for a
+library specified by path and by name. This constraint by be solved by using
+``PATH{}`` and ``NAME{}`` wrappers:
+
+.. code-block:: cmake
+
+  if (CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
+    set(CMAKE_LINK_USING_weak_library "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}")
+    set(CMAKE_LINK_USING_weak_library_SUPPORTED TRUE)
+  endif()
+
+  add_library(lib SHARED ...)
+  add_executable(main ...)
+  if(CMAKE_LINK_USING_weak_library_SUPPORTED)
+    target_link_libraries(main PRIVATE $<LINK_LIBRARY:weak_library,lib,external>)
+  else()
+    target_link_libraries(main PRIVATE lib external)
+  endif()
+
+CMake will generate the following link expression:
+``-weak_library /path/to/lib -Xlinker -weak-lexternal``
diff --git a/Help/variable/CMAKE_LINK_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LINK_USING_FEATURE_SUPPORTED.rst
new file mode 100644
index 0000000..31c3108
--- /dev/null
+++ b/Help/variable/CMAKE_LINK_USING_FEATURE_SUPPORTED.rst
@@ -0,0 +1,14 @@
+CMAKE_LINK_USING_<FEATURE>_SUPPORTED
+------------------------------------
+
+.. versionadded:: 3.24
+
+Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable
+:variable:`CMAKE_LINK_USING_<FEATURE>`, is supported regardless the linker
+language.
+
+.. note::
+
+  This variable is evaluated if, and only if, the variable
+  :variable:`CMAKE_<LANG>_LINK_USING_<FEATURE>_SUPPORTED` evaluates to
+  ``FALSE``.
diff --git a/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt
new file mode 100644
index 0000000..dd22e14
--- /dev/null
+++ b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt
@@ -0,0 +1,5 @@
+**Features available in all environments**
+
+* ``DEFAULT``: This feature enables default link expression. This is mainly
+  useful with :prop_tgt:`LINK_LIBRARY_OVERRIDE` and
+  :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties.