Add usage requirements to update direct link dependencies

Link line construction starts with `LINK_LIBRARIES` and appends
dependencies from the transitive closure of `INTERFACE_LINK_LIBRARIES`.
Only the entries of `LINK_LIBRARIES` are considered direct link
dependencies.  In some advanced use cases, particularly involving static
libraries and static plugins, usage requirements need to update the list
of direct link dependencies.  This may mean adding new items, removing
existing items, or both.

Add target properties to encode these usage requirements:

* INTERFACE_LINK_LIBRARIES_DIRECT
* INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE

Fixes: #22496

6 files changed, 203 insertions, 26 deletions

diff --git a/Source/cmExportFileGenerator.cxx b/Source/cmExportFileGenerator.cxx
index 896240c..412d104 100644
--- a/Source/cmExportFileGenerator.cxx
+++ b/Source/cmExportFileGenerator.cxx
@@ -2,6 +2,7 @@
    file Copyright.txt or https://cmake.org/licensing for details.  */
 #include "cmExportFileGenerator.h"
 
+#include <array>
 #include <cassert>
 #include <cstring>
 #include <sstream>
@@ -175,18 +176,24 @@ bool cmExportFileGenerator::PopulateInterfaceLinkLibrariesProperty(
   if (!target->IsLinkable()) {
     return false;
   }
-  cmValue input = target->GetProperty("INTERFACE_LINK_LIBRARIES");
-  if (input) {
-    std::string prepro =
-      cmGeneratorExpression::Preprocess(*input, preprocessRule);
-    if (!prepro.empty()) {
-      this->ResolveTargetsInGeneratorExpressions(
-        prepro, target, missingTargets, ReplaceFreeTargets);
-      properties["INTERFACE_LINK_LIBRARIES"] = prepro;
-      return true;
+  static const std::array<std::string, 3> linkIfaceProps = {
+    { "INTERFACE_LINK_LIBRARIES", "INTERFACE_LINK_LIBRARIES_DIRECT",
+      "INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE" }
+  };
+  bool hadINTERFACE_LINK_LIBRARIES = false;
+  for (std::string const& linkIfaceProp : linkIfaceProps) {
+    if (cmValue input = target->GetProperty(linkIfaceProp)) {
+      std::string prepro =
+        cmGeneratorExpression::Preprocess(*input, preprocessRule);
+      if (!prepro.empty()) {
+        this->ResolveTargetsInGeneratorExpressions(
+          prepro, target, missingTargets, ReplaceFreeTargets);
+        properties[linkIfaceProp] = prepro;
+        hadINTERFACE_LINK_LIBRARIES = true;
+      }
     }
   }
-  return false;
+  return hadINTERFACE_LINK_LIBRARIES;
 }
 
 static bool isSubDirectory(std::string const& a, std::string const& b)
diff --git a/Source/cmExportTryCompileFileGenerator.cxx b/Source/cmExportTryCompileFileGenerator.cxx
index db9b05b..e98aa05 100644
--- a/Source/cmExportTryCompileFileGenerator.cxx
+++ b/Source/cmExportTryCompileFileGenerator.cxx
@@ -111,6 +111,8 @@ void cmExportTryCompileFileGenerator::PopulateProperties(
   std::vector<std::string> props = target->GetPropertyKeys();
   // Include special properties that might be relevant here.
   props.emplace_back("INTERFACE_LINK_LIBRARIES");
+  props.emplace_back("INTERFACE_LINK_LIBRARIES_DIRECT");
+  props.emplace_back("INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE");
   for (std::string const& p : props) {
     cmValue v = target->GetProperty(p);
     if (!v) {
diff --git a/Source/cmGeneratorExpressionDAGChecker.cxx b/Source/cmGeneratorExpressionDAGChecker.cxx
index 187db73..d4b02a5 100644
--- a/Source/cmGeneratorExpressionDAGChecker.cxx
+++ b/Source/cmGeneratorExpressionDAGChecker.cxx
@@ -189,6 +189,8 @@ bool cmGeneratorExpressionDAGChecker::EvaluatingLinkLibraries(
   }
 
   return prop == "LINK_LIBRARIES"_s || prop == "INTERFACE_LINK_LIBRARIES"_s ||
+    prop == "INTERFACE_LINK_LIBRARIES_DIRECT"_s ||
+    prop == "INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE"_s ||
     prop == "LINK_INTERFACE_LIBRARIES"_s ||
     prop == "IMPORTED_LINK_INTERFACE_LIBRARIES"_s ||
     cmHasLiteralPrefix(prop, "LINK_INTERFACE_LIBRARIES_") ||
diff --git a/Source/cmGeneratorTarget.cxx b/Source/cmGeneratorTarget.cxx
index 8a17476..8624362 100644
--- a/Source/cmGeneratorTarget.cxx
+++ b/Source/cmGeneratorTarget.cxx
@@ -58,6 +58,10 @@ using LinkInterfaceFor = cmGeneratorTarget::LinkInterfaceFor;
 const cmsys::RegularExpression FrameworkRegularExpression(
   "^(.*/)?([^/]*)\\.framework/(.*)$");
 const std::string kINTERFACE_LINK_LIBRARIES = "INTERFACE_LINK_LIBRARIES";
+const std::string kINTERFACE_LINK_LIBRARIES_DIRECT =
+  "INTERFACE_LINK_LIBRARIES_DIRECT";
+const std::string kINTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE =
+  "INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE";
 }
 
 template <>
@@ -6661,12 +6665,10 @@ cm::optional<cmLinkItem> cmGeneratorTarget::LookupLinkItem(
   return maybeItem;
 }
 
-void cmGeneratorTarget::ExpandLinkItems(std::string const& prop,
-                                        cmBTStringRange entries,
-                                        std::string const& config,
-                                        cmGeneratorTarget const* headTarget,
-                                        LinkInterfaceFor interfaceFor,
-                                        cmLinkInterface& iface) const
+void cmGeneratorTarget::ExpandLinkItems(
+  std::string const& prop, cmBTStringRange entries, std::string const& config,
+  cmGeneratorTarget const* headTarget, LinkInterfaceFor interfaceFor,
+  LinkInterfaceField field, cmLinkInterface& iface) const
 {
   if (entries.empty()) {
     return;
@@ -6690,9 +6692,19 @@ void cmGeneratorTarget::ExpandLinkItems(std::string const& prop,
                     this, headTarget->LinkerLanguage));
     for (std::string const& lib : libs) {
       if (cm::optional<cmLinkItem> maybeItem = this->LookupLinkItem(
-            lib, cge->GetBacktrace(), &scope, LookupSelf::No)) {
+            lib, cge->GetBacktrace(), &scope,
+            field == LinkInterfaceField::Libraries ? LookupSelf::No
+                                                   : LookupSelf::Yes)) {
         cmLinkItem item = std::move(*maybeItem);
 
+        if (field == LinkInterfaceField::HeadInclude) {
+          iface.HeadInclude.emplace_back(std::move(item));
+          continue;
+        }
+        if (field == LinkInterfaceField::HeadExclude) {
+          iface.HeadExclude.emplace_back(std::move(item));
+          continue;
+        }
         if (!item.Target) {
           // Report explicitly linked object files separately.
           std::string const& maybeObj = item.AsStr();
@@ -7163,7 +7175,9 @@ void cmGeneratorTarget::ComputeLinkInterfaceLibraries(
                            this->GetPolicyStatusCMP0022() != cmPolicies::WARN);
   if (cmp0022NEW) {
     // CMP0022 NEW behavior is to use INTERFACE_LINK_LIBRARIES.
-    haveExplicitLibraries = !this->Target->GetLinkInterfaceEntries().empty();
+    haveExplicitLibraries = !this->Target->GetLinkInterfaceEntries().empty() ||
+      !this->Target->GetLinkInterfaceDirectEntries().empty() ||
+      !this->Target->GetLinkInterfaceDirectExcludeEntries().empty();
   } else {
     // CMP0022 OLD behavior is to use LINK_INTERFACE_LIBRARIES if set on a
     // shared lib or executable.
@@ -7228,15 +7242,24 @@ void cmGeneratorTarget::ComputeLinkInterfaceLibraries(
   if (cmp0022NEW) {
     // The interface libraries are specified by INTERFACE_LINK_LIBRARIES.
     // Use its special representation directly to get backtraces.
-    this->ExpandLinkItems(kINTERFACE_LINK_LIBRARIES,
-                          this->Target->GetLinkInterfaceEntries(), config,
-                          headTarget, interfaceFor, iface);
+    this->ExpandLinkItems(
+      kINTERFACE_LINK_LIBRARIES, this->Target->GetLinkInterfaceEntries(),
+      config, headTarget, interfaceFor, LinkInterfaceField::Libraries, iface);
+    this->ExpandLinkItems(kINTERFACE_LINK_LIBRARIES_DIRECT,
+                          this->Target->GetLinkInterfaceDirectEntries(),
+                          config, headTarget, interfaceFor,
+                          LinkInterfaceField::HeadInclude, iface);
+    this->ExpandLinkItems(kINTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE,
+                          this->Target->GetLinkInterfaceDirectExcludeEntries(),
+                          config, headTarget, interfaceFor,
+                          LinkInterfaceField::HeadExclude, iface);
   } else if (explicitLibrariesCMP0022OLD) {
     // The interface libraries have been explicitly set in pre-CMP0022 style.
     std::vector<BT<std::string>> entries;
     entries.emplace_back(*explicitLibrariesCMP0022OLD);
     this->ExpandLinkItems(linkIfacePropCMP0022OLD, cmMakeRange(entries),
-                          config, headTarget, interfaceFor, iface);
+                          config, headTarget, interfaceFor,
+                          LinkInterfaceField::Libraries, iface);
   }
 
   // If the link interface is explicit, do not fall back to the link impl.
@@ -7256,7 +7279,8 @@ void cmGeneratorTarget::ComputeLinkInterfaceLibraries(
       cmLinkInterface ifaceNew;
       this->ExpandLinkItems(kINTERFACE_LINK_LIBRARIES,
                             this->Target->GetLinkInterfaceEntries(), config,
-                            headTarget, interfaceFor, ifaceNew);
+                            headTarget, interfaceFor,
+                            LinkInterfaceField::Libraries, ifaceNew);
       if (ifaceNew.Libraries != iface.Libraries) {
         std::string oldLibraries = cmJoin(impl->Libraries, ";");
         std::string newLibraries = cmJoin(ifaceNew.Libraries, ";");
@@ -7396,8 +7420,17 @@ const cmLinkInterface* cmGeneratorTarget::GetImportLinkInterface(
     iface.LibrariesDone = true;
     iface.Multiplicity = info->Multiplicity;
     cmExpandList(info->Languages, iface.Languages);
+    this->ExpandLinkItems(kINTERFACE_LINK_LIBRARIES_DIRECT,
+                          cmMakeRange(info->LibrariesHeadInclude), config,
+                          headTarget, interfaceFor,
+                          LinkInterfaceField::HeadInclude, iface);
+    this->ExpandLinkItems(kINTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE,
+                          cmMakeRange(info->LibrariesHeadExclude), config,
+                          headTarget, interfaceFor,
+                          LinkInterfaceField::HeadExclude, iface);
     this->ExpandLinkItems(info->LibrariesProp, cmMakeRange(info->Libraries),
-                          config, headTarget, interfaceFor, iface);
+                          config, headTarget, interfaceFor,
+                          LinkInterfaceField::Libraries, iface);
     std::vector<std::string> deps = cmExpandedList(info->SharedDeps);
     LookupLinkItemScope scope{ this->LocalGenerator };
     for (std::string const& dep : deps) {
@@ -7490,6 +7523,14 @@ void cmGeneratorTarget::ComputeImportInfo(std::string const& desired_config,
       }
     }
   }
+  for (BT<std::string> const& entry :
+       this->Target->GetLinkInterfaceDirectEntries()) {
+    info.LibrariesHeadInclude.emplace_back(entry);
+  }
+  for (BT<std::string> const& entry :
+       this->Target->GetLinkInterfaceDirectExcludeEntries()) {
+    info.LibrariesHeadExclude.emplace_back(entry);
+  }
   if (this->GetType() == cmStateEnums::INTERFACE_LIBRARY) {
     if (loc) {
       info.LibName = *loc;
@@ -7923,6 +7964,112 @@ bool cmGeneratorTarget::IsNullImpliedByLinkLibraries(
   return cm::contains(this->LinkImplicitNullProperties, p);
 }
 
+namespace {
+class TransitiveLinkImpl
+{
+  cmGeneratorTarget const* Self;
+  std::string const& Config;
+  cmLinkImplementation& Impl;
+
+  std::set<cmLinkItem> Emitted;
+  std::set<cmLinkItem> Excluded;
+  std::unordered_set<cmGeneratorTarget const*> Followed;
+
+  void Follow(cmGeneratorTarget const* target);
+
+public:
+  TransitiveLinkImpl(cmGeneratorTarget const* self, std::string const& config,
+                     cmLinkImplementation& impl)
+    : Self(self)
+    , Config(config)
+    , Impl(impl)
+  {
+  }
+
+  void Compute();
+};
+
+void TransitiveLinkImpl::Follow(cmGeneratorTarget const* target)
+{
+  if (!target || !this->Followed.insert(target).second ||
+      target->GetPolicyStatusCMP0022() == cmPolicies::OLD ||
+      target->GetPolicyStatusCMP0022() == cmPolicies::WARN) {
+    return;
+  }
+
+  // Get this target's usage requirements.
+  cmLinkInterfaceLibraries const* iface = target->GetLinkInterfaceLibraries(
+    this->Config, this->Self, LinkInterfaceFor::Usage);
+  if (!iface) {
+    return;
+  }
+  if (iface->HadContextSensitiveCondition) {
+    this->Impl.HadContextSensitiveCondition = true;
+  }
+
+  // Process 'INTERFACE_LINK_LIBRARIES_DIRECT' usage requirements.
+  for (cmLinkItem const& item : iface->HeadInclude) {
+    // Inject direct dependencies from the item's usage requirements
+    // before the item itself.
+    this->Follow(item.Target);
+
+    // Add the item itself, but at most once.
+    if (this->Emitted.insert(item).second) {
+      this->Impl.Libraries.emplace_back(item, /* checkCMP0027= */ false);
+    }
+  }
+
+  // Follow transitive dependencies.
+  for (cmLinkItem const& item : iface->Libraries) {
+    this->Follow(item.Target);
+  }
+
+  // Record exclusions from 'INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE'
+  // usage requirements.
+  for (cmLinkItem const& item : iface->HeadExclude) {
+    this->Excluded.insert(item);
+  }
+}
+
+void TransitiveLinkImpl::Compute()
+{
+  // Save the original items and start with an empty list.
+  std::vector<cmLinkImplItem> original = std::move(this->Impl.Libraries);
+
+  // Avoid injecting any original items as usage requirements.
+  // This gives LINK_LIBRARIES final control over the order
+  // if it explicitly lists everything.
+  this->Emitted.insert(original.cbegin(), original.cend());
+
+  // Process each original item.
+  for (cmLinkImplItem& item : original) {
+    // Inject direct dependencies listed in 'INTERFACE_LINK_LIBRARIES_DIRECT'
+    // usage requirements before the item itself.
+    this->Follow(item.Target);
+
+    // Add the item itself.
+    this->Impl.Libraries.emplace_back(std::move(item));
+  }
+
+  // Remove items listed in 'INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE'
+  // usage requirements found through any dependency above.
+  this->Impl.Libraries.erase(
+    std::remove_if(this->Impl.Libraries.begin(), this->Impl.Libraries.end(),
+                   [this](cmLinkImplItem const& item) {
+                     return this->Excluded.find(item) != this->Excluded.end();
+                   }),
+    this->Impl.Libraries.end());
+}
+
+void ComputeLinkImplTransitive(cmGeneratorTarget const* self,
+                               std::string const& config,
+                               cmLinkImplementation& impl)
+{
+  TransitiveLinkImpl transitiveLinkImpl(self, config, impl);
+  transitiveLinkImpl.Compute();
+}
+}
+
 void cmGeneratorTarget::ComputeLinkImplementationLibraries(
   const std::string& config, cmOptionalLinkImplementation& impl,
   cmGeneratorTarget const* head) const
@@ -8029,6 +8176,11 @@ void cmGeneratorTarget::ComputeLinkImplementationLibraries(
     cge->GetMaxLanguageStandard(this, this->MaxLanguageStandards);
   }
 
+  // Update the list of direct link dependencies from usage requirements.
+  if (head == this) {
+    ComputeLinkImplTransitive(this, config, impl);
+  }
+
   // Get the list of configurations considered to be DEBUG.
   std::vector<std::string> debugConfigs =
     this->Makefile->GetCMakeInstance()->GetDebugConfigs();
diff --git a/Source/cmGeneratorTarget.h b/Source/cmGeneratorTarget.h
index f36e2be..0dbc940 100644
--- a/Source/cmGeneratorTarget.h
+++ b/Source/cmGeneratorTarget.h
@@ -1001,8 +1001,10 @@ private:
     std::string ImportLibrary;
     std::string LibName;
     std::string Languages;
-    std::vector<BT<std::string>> Libraries;
     std::string LibrariesProp;
+    std::vector<BT<std::string>> Libraries;
+    std::vector<BT<std::string>> LibrariesHeadInclude;
+    std::vector<BT<std::string>> LibrariesHeadExclude;
     std::string SharedDeps;
   };
 
@@ -1063,10 +1065,16 @@ private:
   bool IsLinkLookupScope(std::string const& n,
                          cmLocalGenerator const*& lg) const;
 
+  enum class LinkInterfaceField
+  {
+    Libraries,
+    HeadExclude,
+    HeadInclude,
+  };
   void ExpandLinkItems(std::string const& prop, cmBTStringRange entries,
                        std::string const& config,
                        const cmGeneratorTarget* headTarget,
-                       LinkInterfaceFor interfaceFor,
+                       LinkInterfaceFor interfaceFor, LinkInterfaceField field,
                        cmLinkInterface& iface) const;
 
   struct LookupLinkItemScope
diff --git a/Source/cmLinkItem.h b/Source/cmLinkItem.h
index e715659..262728b 100644
--- a/Source/cmLinkItem.h
+++ b/Source/cmLinkItem.h
@@ -70,6 +70,12 @@ struct cmLinkInterfaceLibraries
   // Object files listed in the interface.
   std::vector<cmLinkItem> Objects;
 
+  // Items to be included as if directly linked by the head target.
+  std::vector<cmLinkItem> HeadInclude;
+
+  // Items to be excluded from direct linking by the head target.
+  std::vector<cmLinkItem> HeadExclude;
+
   // Whether the list depends on a genex referencing the head target.
   bool HadHeadSensitiveCondition = false;