Merge topic 'doc-CMP0111' into release-3.19

5c3a91c808 CMP0111: Clarify that the new error is on a missing property setting

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Alex Reinking <alex_reinking@berkeley.edu>
Merge-request: !5385

5 files changed, 25 insertions, 15 deletions

diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 0392325e83..fa10f664c4 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -60,7 +60,7 @@ Policies Introduced by CMake 3.19
    CMP0114: ExternalProject step targets fully adopt their steps. </policy/CMP0114>
    CMP0113: Makefile generators do not repeat custom commands from target dependencies. </policy/CMP0113>
    CMP0112: Target file component generator expressions do not add target dependencies. </policy/CMP0112>
-   CMP0111: An imported target with a missing location fails during generation. </policy/CMP0111>
+   CMP0111: An imported target missing its location property fails during generation. </policy/CMP0111>
    CMP0110: add_test() supports arbitrary characters in test names. </policy/CMP0110>
    CMP0109: find_program() requires permission to execute but not to read. </policy/CMP0109>
 
diff --git a/Help/policy/CMP0111.rst b/Help/policy/CMP0111.rst
index 37e5ad56b0..e32758354e 100644
--- a/Help/policy/CMP0111.rst
+++ b/Help/policy/CMP0111.rst
@@ -3,10 +3,17 @@ CMP0111
 
 .. versionadded:: 3.19
 
-An imported target with a missing location fails during generation.
+An imported target missing its location property fails during generation.
 
-Prior to this the location would be generated as ``<TARGET_NAME>-NOTFOUND``,
-which would result in build failures.
+:ref:`Imported Targets` for library files and executables require that
+their location on disk is specified in a target property such as
+:prop_tgt:`IMPORTED_LOCATION`, :prop_tgt:`IMPORTED_IMPLIB`, or a
+per-configuration equivalent.  If a needed location property is not set,
+CMake 3.18 and below generate the string ``<TARGET_NAME>-NOTFOUND`` in
+its place, which results in failures of the corresponding rules at build
+time.  CMake 3.19 and above prefer instead to raise an error during
+generation.  This policy provides compatibility for projects that have
+not been updated to expect the new behavior.
 
 The ``OLD`` behavior of this policy is to generate the location of an imported
 unknown, static or shared library target as ``<TARGET_NAME>-NOTFOUND`` if not
diff --git a/Help/release/3.19.rst b/Help/release/3.19.rst
index ea68594506..93e060e7c1 100644
--- a/Help/release/3.19.rst
+++ b/Help/release/3.19.rst
@@ -293,7 +293,7 @@ Other Changes
 * The :command:`find_program` command now requires permission to execute
   but not to read the file found.  See policy :policy:`CMP0109`.
 
-* An imported target with a missing location now fails during generation
+* An imported target missing its location property fails during generation
   if the location is used.  See policy :policy:`CMP0111`.
 
 * The following target-based generator expressions that query for directory or
diff --git a/Source/cmPolicies.h b/Source/cmPolicies.h
index 958d061041..18ce9c3f21 100644
--- a/Source/cmPolicies.h
+++ b/Source/cmPolicies.h
@@ -327,7 +327,7 @@ class cmMakefile;
          "add_test() supports arbitrary characters in test names.", 3, 19, 0, \
          cmPolicies::WARN)                                                    \
   SELECT(POLICY, CMP0111,                                                     \
-         "An imported target with a missing location fails during "           \
+         "An imported target missing its location property fails during "     \
          "generation.",                                                       \
          3, 19, 0, cmPolicies::WARN)                                          \
   SELECT(POLICY, CMP0112,                                                     \
diff --git a/Tests/RunCMake/CMP0111/CMP0111-WARN-stderr.txt b/Tests/RunCMake/CMP0111/CMP0111-WARN-stderr.txt
index 2fe6cc8ab4..3abca0ab05 100644
--- a/Tests/RunCMake/CMP0111/CMP0111-WARN-stderr.txt
+++ b/Tests/RunCMake/CMP0111/CMP0111-WARN-stderr.txt
@@ -1,25 +1,28 @@
 CMake Warning \(dev\) in CMakeLists.txt:
-  Policy CMP0111 is not set: An imported target with a missing location fails
-  during generation.  Run "cmake --help-policy CMP0111" for policy details.
-  Use the cmake_policy command to set the policy and suppress this warning.
+  Policy CMP0111 is not set: An imported target missing its location property
+  fails during generation.  Run "cmake --help-policy CMP0111" for policy
+  details.  Use the cmake_policy command to set the policy and suppress this
+  warning.
 
   IMPORTED_LOCATION not set for imported target "unknown_lib"( configuration
   ".+")?.
 This warning is for project developers.  Use -Wno-dev to suppress it.
 +
 CMake Warning \(dev\) in CMakeLists.txt:
-  Policy CMP0111 is not set: An imported target with a missing location fails
-  during generation.  Run "cmake --help-policy CMP0111" for policy details.
-  Use the cmake_policy command to set the policy and suppress this warning.
+  Policy CMP0111 is not set: An imported target missing its location property
+  fails during generation.  Run "cmake --help-policy CMP0111" for policy
+  details.  Use the cmake_policy command to set the policy and suppress this
+  warning.
 
   IMPORTED_LOCATION not set for imported target "static_lib"( configuration
   ".+")?.
 This warning is for project developers.  Use -Wno-dev to suppress it.
 +
 CMake Warning \(dev\) in CMakeLists.txt:
-  Policy CMP0111 is not set: An imported target with a missing location fails
-  during generation.  Run "cmake --help-policy CMP0111" for policy details.
-  Use the cmake_policy command to set the policy and suppress this warning.
+  Policy CMP0111 is not set: An imported target missing its location property
+  fails during generation.  Run "cmake --help-policy CMP0111" for policy
+  details.  Use the cmake_policy command to set the policy and suppress this
+  warning.
 
   IMPORTED_IMPLIB not set for imported target "shared_lib"( configuration
   ".+")?.