CMakeForceCompiler: Deprecate this module and its macros

We originally deprecated this module in commit v3.5.0-rc1~295^2
(CMakeForceCompiler: Deprecate this module and its macros, 2015-10-19).
Then a use case was found to still require the module so the deprecation
was reverted for CMake 3.5 by commit v3.5.0-rc3~4^2 (CMakeForceCompiler:
De-deprecate until more use cases have alternatives, 2016-02-17).  Since
then `CMAKE_TRY_COMPILE_TARGET_TYPE` was introduced to provide an
alternative solution for that use case.  Deprecate the module again.

3 files changed, 21 insertions, 11 deletions

diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst
index 7b294a8..390220c 100644
--- a/Help/manual/cmake-toolchains.7.rst
+++ b/Help/manual/cmake-toolchains.7.rst
@@ -138,9 +138,10 @@ a path on the host to install to. The :variable:`CMAKE_INSTALL_PREFIX` is always
 the runtime installation location, even when cross-compiling.
 
 The :variable:`CMAKE_<LANG>_COMPILER` variables may be set to full paths, or to
-names of compilers to search for in standard locations. In cases where CMake does
-not have enough information to extract information from the compiler, the
-:module:`CMakeForceCompiler` module can be used to bypass some of the checks.
+names of compilers to search for in standard locations.   For toolchains that
+do not support linking binaries without custom flags or scripts one may set
+the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable to ``STATIC_LIBRARY``
+to tell CMake not to try to link executables during its checks.
 
 CMake ``find_*`` commands will look in the sysroot, and the :variable:`CMAKE_FIND_ROOT_PATH`
 entries by default in all cases, as well as looking in the host system root prefix.
diff --git a/Help/release/dev/deprecate-CMakeForceCompiler.rst b/Help/release/dev/deprecate-CMakeForceCompiler.rst
new file mode 100644
index 0000000..dc6e817
--- /dev/null
+++ b/Help/release/dev/deprecate-CMakeForceCompiler.rst
@@ -0,0 +1,5 @@
+deprecate-CMakeForceCompiler
+----------------------------
+
+* The :module:`CMakeForceCompiler` module and its macros are now deprecated.
+  See module documentation for an explanation.
diff --git a/Modules/CMakeForceCompiler.cmake b/Modules/CMakeForceCompiler.cmake
index faa0dc5..d16d184 100644
--- a/Modules/CMakeForceCompiler.cmake
+++ b/Modules/CMakeForceCompiler.cmake
@@ -2,9 +2,7 @@
 # CMakeForceCompiler
 # ------------------
 #
-# Discouraged.  Avoid using this module if possible.  It will be deprecated
-# by a future version of CMake once alternatives have been provided for all
-# toolchain file use cases.
+# Deprecated.  Do not use.
 #
 # The macros provided by this module were once intended for use by
 # cross-compiling toolchain files when CMake was not able to automatically
@@ -14,11 +12,11 @@
 # CMake detects from a compiler is now too extensive to be provided by
 # toolchain files using these macros.
 #
-# The only known remaining use case for these macros is to write toolchain
-# files for cross-compilers that cannot link binaries without special flags or
-# custom linker scripts.  These macros cause CMake to skip checks it normally
-# performs as part of enabling a language and introspecting the toolchain.
-# However, skipping these checks may limit some generation functionality.
+# One common use case for this module was to skip CMake's checks for a
+# working compiler when using a cross-compiler that cannot link binaries
+# without special flags or custom linker scripts.  This case is now supported
+# by setting the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable in the
+# toolchain file instead.
 #
 # -------------------------------------------------------------------------
 #
@@ -78,6 +76,8 @@
 #  License text for the above reference.)
 
 macro(CMAKE_FORCE_C_COMPILER compiler id)
+  message(DEPRECATION "The CMAKE_FORCE_C_COMPILER macro is deprecated.  "
+    "Instead just set CMAKE_C_COMPILER and allow CMake to identify the compiler.")
   set(CMAKE_C_COMPILER "${compiler}")
   set(CMAKE_C_COMPILER_ID_RUN TRUE)
   set(CMAKE_C_COMPILER_ID ${id})
@@ -90,6 +90,8 @@ macro(CMAKE_FORCE_C_COMPILER compiler id)
 endmacro()
 
 macro(CMAKE_FORCE_CXX_COMPILER compiler id)
+  message(DEPRECATION "The CMAKE_FORCE_CXX_COMPILER macro is deprecated.  "
+    "Instead just set CMAKE_CXX_COMPILER and allow CMake to identify the compiler.")
   set(CMAKE_CXX_COMPILER "${compiler}")
   set(CMAKE_CXX_COMPILER_ID_RUN TRUE)
   set(CMAKE_CXX_COMPILER_ID ${id})
@@ -102,6 +104,8 @@ macro(CMAKE_FORCE_CXX_COMPILER compiler id)
 endmacro()
 
 macro(CMAKE_FORCE_Fortran_COMPILER compiler id)
+  message(DEPRECATION "The CMAKE_FORCE_Fortran_COMPILER macro is deprecated.  "
+    "Instead just set CMAKE_Fortran_COMPILER and allow CMake to identify the compiler.")
   set(CMAKE_Fortran_COMPILER "${compiler}")
   set(CMAKE_Fortran_COMPILER_ID_RUN TRUE)
   set(CMAKE_Fortran_COMPILER_ID ${id})