BundleUtilities: Disallow inclusion at configure time

This commit adds a new CMake policy, CMP0080, which prohibits the
inclusion of BundleUtilities at configure time. The old behavior is
to allow the inclusion.

Help/manual/cmake-policies.7.rst

@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.13
 .. toctree::
    :maxdepth: 1
 
+   CMP0080: BundleUtilities cannot be included at configure time. </policy/CMP0080>
    CMP0079: target_link_libraries allows use with targets in other directories. </policy/CMP0079>
    CMP0078: UseSWIG generates standard target names. </policy/CMP0078>
    CMP0077: option() honors normal variables. </policy/CMP0077>

Help/policy/CMP0080.rst

@@ -0,0 +1,25 @@
+CMP0080
+-------
+
+:module:`BundleUtilities` cannot be included at configure time.
+
+The macros provided by :module:`BundleUtilities` are intended to be invoked
+at install time rather than at configure time, because they depend on the
+listed targets already existing at the time they are invoked. If they are
+invoked at configure time, the targets haven't been built yet, and the
+commands will fail.
+
+This policy restricts the inclusion of :module:`BundleUtilities` to
+``cmake -P`` style scripts and install rules. Specifically, it looks for the
+presence of :variable:`CMAKE_GENERATOR` and throws a fatal error if it exists.
+
+The ``OLD`` behavior of this policy is to allow :module:`BundleUtilities` to
+be included at configure time. The ``NEW`` behavior of this policy is to
+disallow such inclusion.
+
+This policy was introduced in CMake version 3.13.  CMake version
+|release| warns when the policy is not set and uses ``OLD`` behavior.
+Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
+explicitly.
+
+.. include:: DEPRECATED.txt

Modules/BundleUtilities.cmake

@@ -224,6 +224,20 @@ that are already also in the bundle...  Anything that points to an
 external file causes this function to fail the verification.
 #]=======================================================================]
 
+# Do not include this module at configure time!
+if(DEFINED CMAKE_GENERATOR)
+  cmake_policy(GET CMP0080 _BundleUtilities_CMP0080)
+  if(_BundleUtilities_CMP0080 STREQUAL "NEW")
+    message(FATAL_ERROR "BundleUtilities cannot be included at configure time!")
+  elseif(NOT _BundleUtilities_CMP0080 STREQUAL "OLD")
+    message(AUTHOR_WARNING
+      "Policy CMP0080 is not set: BundleUtilities prefers not to be included at configure time. "
+      "Run \"cmake --help-policy CMP0080\" for policy details. "
+      "Use the cmake_policy command to set the policy and suppress this warning."
+      )
+  endif()
+endif()
+
 # The functions defined in this file depend on the get_prerequisites function
 # (and possibly others) found in:
 #

Source/cmPolicies.h

@@ -234,7 +234,10 @@ class cmMakefile;
   SELECT(                                                                     \
     POLICY, CMP0079,                                                          \
     "target_link_libraries allows use with targets in other directories.", 3, \
-    13, 0, cmPolicies::WARN)
+    13, 0, cmPolicies::WARN)                                                  \
+  SELECT(POLICY, CMP0080,                                                     \
+         "BundleUtilities cannot be included at configure time", 3, 13, 0,    \
+         cmPolicies::WARN)
 
 #define CM_SELECT_ID(F, A1, A2, A3, A4, A5, A6) F(A1)
 #define CM_FOR_EACH_POLICY_ID(POLICY)                                         \

Tests/RunCMake/BundleUtilities/CMP0080-COMMAND.cmake

@@ -0,0 +1,5 @@
+if(DEFINED CMP0080_VALUE)
+  cmake_policy(SET CMP0080 ${CMP0080_VALUE})
+endif()
+
+include(BundleUtilities)

Tests/RunCMake/BundleUtilities/CMP0080-NEW-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/BundleUtilities/CMP0080-NEW-stderr.txt

@@ -0,0 +1,2 @@
+CMake Error at .*/Modules/BundleUtilities\.cmake:[0-9]+ \(message\):
+  BundleUtilities cannot be included at configure time!

Tests/RunCMake/BundleUtilities/CMP0080-NEW.cmake

@@ -0,0 +1,2 @@
+cmake_policy(SET CMP0080 NEW)
+include(BundleUtilities)

Tests/RunCMake/BundleUtilities/CMP0080-OLD.cmake

@@ -0,0 +1,2 @@
+cmake_policy(SET CMP0080 OLD)
+include(BundleUtilities)

Tests/RunCMake/BundleUtilities/CMP0080-WARN-stderr.txt

@@ -0,0 +1,4 @@
+CMake Warning \(dev\) at .*/Modules/BundleUtilities\.cmake:[0-9]+ \(message\):
+  Policy CMP0080 is not set: BundleUtilities prefers not to be included at
+  configure time\.  Run "cmake --help-policy CMP0080" for policy details\.  Use
+  the cmake_policy command to set the policy and suppress this warning\.

Tests/RunCMake/BundleUtilities/CMP0080-WARN.cmake

@@ -0,0 +1 @@
+include(BundleUtilities)

Tests/RunCMake/BundleUtilities/CMakeLists.txt

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

Tests/RunCMake/BundleUtilities/RunCMakeTest.cmake

@@ -0,0 +1,11 @@
+cmake_minimum_required(VERSION 3.4)
+include(RunCMake)
+
+# TODO Migrate Tests/BundleUtilities here
+
+run_cmake(CMP0080-OLD)
+run_cmake(CMP0080-NEW)
+run_cmake(CMP0080-WARN)
+run_cmake_command(CMP0080-COMMAND-OLD ${CMAKE_COMMAND} -DCMP0080_VALUE:STRING=OLD -P ${RunCMake_SOURCE_DIR}/CMP0080-COMMAND.cmake)
+run_cmake_command(CMP0080-COMMAND-NEW ${CMAKE_COMMAND} -DCMP0080_VALUE:STRING=NEW -P ${RunCMake_SOURCE_DIR}/CMP0080-COMMAND.cmake)
+run_cmake_command(CMP0080-COMMAND-WARN ${CMAKE_COMMAND} -P ${RunCMake_SOURCE_DIR}/CMP0080-COMMAND.cmake)

Tests/RunCMake/CMakeLists.txt

@@ -251,6 +251,7 @@ add_RunCMake_test(separate_arguments)
 add_RunCMake_test(set_property)
 add_RunCMake_test(string)
 add_RunCMake_test(test_include_dirs)
+add_RunCMake_test(BundleUtilities)
 
 function(add_RunCMake_test_try_compile)
   if(CMAKE_VERSION VERSION_LESS 3.9.20170907 AND "x${CMAKE_CXX_COMPILER_ID}" STREQUAL "xMSVC")