Add set_property option: DEPRECATION

Add a new property flag for a target which contains a message regarding
deprecation status.

Add a warning at "Generate" time if a linked target is marked as
deprecated.

Expand ExportImport test to ensure that new property is being set and
passed correctly.  Ensure that the message is shown during the
"Generate" step run of the ExportImport test.

Help/manual/cmake-properties.7.rst

@@ -183,6 +183,7 @@ Properties on Targets
    /prop_tgt/DEFINE_SYMBOL
    /prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY
    /prop_tgt/DEPLOYMENT_ADDITIONAL_FILES
+   /prop_tgt/DEPRECATION
    /prop_tgt/DISABLE_PRECOMPILE_HEADERS
    /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION
    /prop_tgt/EchoString

Help/prop_tgt/DEPRECATION.rst

@@ -0,0 +1,7 @@
+DEPRECATION
+-----------
+
+Deprecation message from imported target's developer.
+
+``DEPRECATION`` is the message regarding a deprecation status to be displayed
+to downstream users of a target.

Help/release/dev/add_target_deprecation.rst

@@ -0,0 +1,7 @@
+add_target_deprecation
+----------------------
+
+* A :prop_tgt:`DEPRECATION` target property was added to mark
+  a target as deprecated. If a linked target is marked as
+  deprecated, a warning with the deprecation message is issued
+  at generate time.

Source/cmExportFileGenerator.cxx

@@ -1062,6 +1062,12 @@ void cmExportFileGenerator::GenerateImportTargetCode(
   if (target->IsCFBundleOnApple()) {
     os << "set_property(TARGET " << targetName << " PROPERTY BUNDLE 1)\n";
   }
+
+  // generate DEPRECATION
+  if (target->IsDeprecated()) {
+    os << "set_property(TARGET " << targetName << " PROPERTY DEPRECATION "
+       << cmExportFileGeneratorEscape(target->GetDeprecation()) << ")\n";
+  }
   os << "\n";
 }
 

Source/cmGeneratorTarget.cxx

@@ -6354,6 +6354,21 @@ std::string cmGeneratorTarget::CheckCMP0004(std::string const& item) const
   return lib;
 }
 
+bool cmGeneratorTarget::IsDeprecated() const
+{
+  const char* deprecation = this->GetProperty("DEPRECATION");
+  return deprecation && *deprecation;
+}
+
+std::string cmGeneratorTarget::GetDeprecation() const
+{
+  // find DEPRECATION property
+  if (const char* deprecation = this->GetProperty("DEPRECATION")) {
+    return deprecation;
+  }
+  return std::string();
+}
+
 void cmGeneratorTarget::GetLanguages(std::set<std::string>& languages,
                                      const std::string& config) const
 {
@@ -6624,6 +6639,19 @@ cmLinkItem cmGeneratorTarget::ResolveLinkItem(
     return cmLinkItem(resolved.String, bt);
   }
 
+  // Check deprecation, issue message with `bt` backtrace.
+  if (resolved.Target->IsDeprecated()) {
+    std::ostringstream w;
+    /* clang-format off */
+    w <<
+      "The library that is being linked to, "  << resolved.Target->GetName() <<
+      ", is marked as being deprecated by the owner.  The message provided by "
+      "the developer is: \n" << resolved.Target->GetDeprecation() << "\n";
+    /* clang-format on */
+    this->LocalGenerator->GetCMakeInstance()->IssueMessage(
+      MessageType::AUTHOR_WARNING, w.str(), bt);
+  }
+
   // Skip targets that will not really be linked.  This is probably a
   // name conflict between an external library and an executable
   // within the project.

Source/cmGeneratorTarget.h

@@ -250,6 +250,13 @@ public:
   std::string GetAppBundleDirectory(const std::string& config,
                                     BundleDirectoryLevel level) const;
 
+  /** Return whether this target is marked as deprecated by the
+      maintainer  */
+  bool IsDeprecated() const;
+
+  /** Returns the deprecation message provided by the maintainer */
+  std::string GetDeprecation() const;
+
   /** Return whether this target is an executable Bundle, a framework
       or CFBundle on Apple.  */
   bool IsBundleOnApple() const;

Source/cmTargetPropertyComputer.cxx

@@ -62,6 +62,7 @@ bool cmTargetPropertyComputer::WhiteListedInterfaceProperty(
     "COMPATIBLE_INTERFACE_NUMBER_MAX",
     "COMPATIBLE_INTERFACE_NUMBER_MIN",
     "COMPATIBLE_INTERFACE_STRING",
+    "DEPRECATION",
     "EXPORT_NAME",
     "EXPORT_PROPERTIES",
     "IMPORTED",

Tests/ExportImport/Export/CMakeLists.txt

@@ -240,6 +240,10 @@ set_property(TARGET testLibRequired APPEND PROPERTY
 )
 include(GenerateExportHeader)
 
+# Test deprecation of imported library
+add_library(testLibDeprecation STATIC testLib1.c)
+set_property(TARGET testLibDeprecation PROPERTY DEPRECATION "Deprecated version. Please use latest version")
+
 add_subdirectory(renamed)
 
 add_library(testSharedLibRequired SHARED testSharedLibRequired.cpp)
@@ -515,6 +519,7 @@ install(
   testExe2lib testLib4lib testLib4libdbg testLib4libopt
   testLib6 testLib7 testLib8
   testLib9
+  testLibDeprecation
   testLibCycleA testLibCycleB
   testLibNoSONAME
   cmp0022NEW cmp0022OLD
@@ -585,6 +590,7 @@ export(TARGETS testExe1 testLib1 testLib2 testLib3
 export(TARGETS testExe2 testLib4 testLib5 testLib6 testLib7 testExe3 testExe4 testExe2lib
   testLib8
   testLib9 testLib9ObjPub testLib9ObjPriv testLib9ObjIface
+  testLibDeprecation
   testLib4lib testLib4libdbg testLib4libopt
   testLibCycleA testLibCycleB
   testLibNoSONAME

Tests/ExportImport/Import/A/CMakeLists.txt

@@ -51,6 +51,12 @@ checkForProperty(bld_testLib4 "EXPORTED_PROPERTY2"  "EXPORTING_TESTLIB4_1")
 checkForProperty(exp_testLib4 "EXPORTED_PROPERTY2"  "EXPORTING_TESTLIB4_1")
 checkForProperty(bld_testLib4 "EXPORTED_PROPERTY3"  "EXPORTING_TESTLIB4_2")
 checkForProperty(exp_testLib4 "EXPORTED_PROPERTY3"  "EXPORTING_TESTLIB4_2")
+checkForProperty(bld_testLibDeprecation "DEPRECATION"  "Deprecated version. Please use latest version")
+checkForProperty(exp_testLibDeprecation "DEPRECATION"  "Deprecated version. Please use latest version")
+
+# Try linking to a deprecated library
+target_link_libraries(imp_testExe1 exp_testLibDeprecation)
+
 
 # Try linking to a library imported from the install tree.
 target_link_libraries(imp_testExe1

Tests/RunCMake/CMakeLists.txt

@@ -217,6 +217,7 @@ add_RunCMake_test(ScriptMode)
 add_RunCMake_test(Swift -DCMAKE_Swift_COMPILER=${CMAKE_Swift_COMPILER})
 add_RunCMake_test(TargetObjects)
 add_RunCMake_test(TargetSources)
+add_RunCMake_test(TargetProperties)
 add_RunCMake_test(ToolchainFile)
 add_RunCMake_test(find_dependency)
 add_RunCMake_test(CompileDefinitions)

Tests/RunCMake/TargetProperties/CMakeLists.txt

@@ -0,0 +1,3 @@
+cmake_minimum_required(VERSION 2.8.4)
+project(${RunCMake_TEST})
+include(${RunCMake_TEST}.cmake)

Tests/RunCMake/TargetProperties/Deprecation-stderr.txt

@@ -0,0 +1,9 @@
+^CMake Warning \(dev\) at Deprecation\.cmake:[0-9]+ \(target_link_libraries\):
+  The library that is being linked to, testLibDeprecation, is marked as being
+  deprecated by the owner\.  The message provided by the developer is:
+
+  Deprecated version\.  Please use latest version
+
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:[0-9]+ \(include\)
+This warning is for project developers\.  Use -Wno-dev to suppress it.

Tests/RunCMake/TargetProperties/Deprecation.cmake

@@ -0,0 +1,5 @@
+add_library(testLibDeprecation STATIC empty.cpp)
+set_property(TARGET testLibDeprecation PROPERTY DEPRECATION "Deprecated version. Please use latest version")
+
+add_executable(testExe1 empty.cpp)
+target_link_libraries(testExe1 testLibDeprecation)

Tests/RunCMake/TargetProperties/RunCMakeTest.cmake

@@ -0,0 +1,3 @@
+include(RunCMake)
+
+run_cmake(Deprecation)

Tests/RunCMake/TargetProperties/empty.cpp

@@ -0,0 +1,4 @@
+int empty()
+{
+  return 0;
+}