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.

15 files changed, 94 insertions, 0 deletions

diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index b9db12d..10a0c7c 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/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
diff --git a/Help/prop_tgt/DEPRECATION.rst b/Help/prop_tgt/DEPRECATION.rst
new file mode 100644
index 0000000..fef2e2e
--- /dev/null
+++ b/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.
diff --git a/Help/release/dev/add_target_deprecation.rst b/Help/release/dev/add_target_deprecation.rst
new file mode 100644
index 0000000..b91eca9
--- /dev/null
+++ b/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.
diff --git a/Source/cmExportFileGenerator.cxx b/Source/cmExportFileGenerator.cxx
index aeef602..7a4b887 100644
--- a/Source/cmExportFileGenerator.cxx
+++ b/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";
 }
 
diff --git a/Source/cmGeneratorTarget.cxx b/Source/cmGeneratorTarget.cxx
index 19d5b4d..927364d 100644
--- a/Source/cmGeneratorTarget.cxx
+++ b/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.
diff --git a/Source/cmGeneratorTarget.h b/Source/cmGeneratorTarget.h
index eabd3fa9..0a72cbe 100644
--- a/Source/cmGeneratorTarget.h
+++ b/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;
diff --git a/Source/cmTargetPropertyComputer.cxx b/Source/cmTargetPropertyComputer.cxx
index baab8da..f37995c 100644
--- a/Source/cmTargetPropertyComputer.cxx
+++ b/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",
diff --git a/Tests/ExportImport/Export/CMakeLists.txt b/Tests/ExportImport/Export/CMakeLists.txt
index 4d411a9..7c81aea 100644
--- a/Tests/ExportImport/Export/CMakeLists.txt
+++ b/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
diff --git a/Tests/ExportImport/Import/A/CMakeLists.txt b/Tests/ExportImport/Import/A/CMakeLists.txt
index c5304da..3cb3833 100644
--- a/Tests/ExportImport/Import/A/CMakeLists.txt
+++ b/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
diff --git a/Tests/RunCMake/CMakeLists.txt b/Tests/RunCMake/CMakeLists.txt
index 10e4c6f..3b456db 100644
--- a/Tests/RunCMake/CMakeLists.txt
+++ b/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)
diff --git a/Tests/RunCMake/TargetProperties/CMakeLists.txt b/Tests/RunCMake/TargetProperties/CMakeLists.txt
new file mode 100644
index 0000000..be9d403
--- /dev/null
+++ b/Tests/RunCMake/TargetProperties/CMakeLists.txt
@@ -0,0 +1,3 @@
+cmake_minimum_required(VERSION 2.8.4)
+project(${RunCMake_TEST})
+include(${RunCMake_TEST}.cmake)
diff --git a/Tests/RunCMake/TargetProperties/Deprecation-stderr.txt b/Tests/RunCMake/TargetProperties/Deprecation-stderr.txt
new file mode 100644
index 0000000..11a4cd8
--- /dev/null
+++ b/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.
diff --git a/Tests/RunCMake/TargetProperties/Deprecation.cmake b/Tests/RunCMake/TargetProperties/Deprecation.cmake
new file mode 100644
index 0000000..9361273
--- /dev/null
+++ b/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)
diff --git a/Tests/RunCMake/TargetProperties/RunCMakeTest.cmake b/Tests/RunCMake/TargetProperties/RunCMakeTest.cmake
new file mode 100644
index 0000000..5af31da
--- /dev/null
+++ b/Tests/RunCMake/TargetProperties/RunCMakeTest.cmake
@@ -0,0 +1,3 @@
+include(RunCMake)
+
+run_cmake(Deprecation)
diff --git a/Tests/RunCMake/TargetProperties/empty.cpp b/Tests/RunCMake/TargetProperties/empty.cpp
new file mode 100644
index 0000000..4086dcc
--- /dev/null
+++ b/Tests/RunCMake/TargetProperties/empty.cpp
@@ -0,0 +1,4 @@
+int empty()
+{
+  return 0;
+}