Alternative wording/organization for the new policy

[mehdi_amini]

Summary

This *not* a patch intended to be submitted, it is a stripped-down version of how I'd phrase the policy change proposed here: https://reviews.llvm.org/D47073

This intentionally left out any compiler minimum bump out of the policy upgrade change, as these are conceptually separate change anyway.

[mehdi_amini]

llvm/cmake/modules/CheckCompilerVersion.cmake

10

Note in this version: the _MIN can't be ignored, the _WARN can be ignored and is only here to support the "one release cycle deprecation".

llvm/docs/GettingStarted.rst

241

Added explicit policy that we'll give a one release cycle.

[jfb]

llvm/cmake/modules/CheckCompilerVersion.cmake

10

How did you choose these numbers? Which version of C++ do they allow moving to?

[mehdi_amini]

llvm/cmake/modules/CheckCompilerVersion.cmake

10

I don't know if I understand your question correctly?
As I mentioned in the description: "This intentionally left out any compiler minimum bump out of the policy upgrade change, as these are conceptually separate change anyway."

So these numbers are exactly the same as the current one, this diff is *only* setting the structure for the change, not settling the question of which numbers to pick.

[jfb]

llvm/cmake/modules/CheckCompilerVersion.cmake

10

That's the important part of D47073! The version bump was chosen through extensive discussion, which I've linked to. I appreciate that you're clarifying your suggestion with code, but please read up on that discussion.

llvm/CMakeLists.txt

if(NOT DEFINED LLVM_VERSION_MINOR)
   set(LLVM_VERSION_MINOR 0)
 endif()
 if(NOT DEFINED LLVM_VERSION_PATCH)
   set(LLVM_VERSION_PATCH 0)
 endif()
 if(NOT DEFINED LLVM_VERSION_SUFFIX)
   set(LLVM_VERSION_SUFFIX svn)
 endif()
+if (NOT DEFINED LLVM_IGNORE_HOST_COMPILER_VERSION_CHECK)
+  set(LLVM_IGNORE_HOST_COMPILER_VERSION_CHECK OFF)
+endif()
 
 if (NOT PACKAGE_VERSION)
   set(PACKAGE_VERSION
     "${LLVM_VERSION_MAJOR}.${LLVM_VERSION_MINOR}.${LLVM_VERSION_PATCH}${LLVM_VERSION_SUFFIX}")
 endif()
 
 if ((CMAKE_GENERATOR MATCHES "Visual Studio") AND (CMAKE_GENERATOR_TOOLSET STREQUAL ""))
   message(WARNING "Visual Studio generators use the x86 host compiler by "

llvm/cmake/modules/CheckCompilerVersion.cmake

-# Check if the host compiler is new enough. LLVM requires at least GCC 4.8,
-# MSVC 2015 (Update 3), or Clang 3.1.
-
+# Check if the host compiler is new enough.
+# See docs/GettingStarted.rst for the policy to update the minimum requirements
 include(CheckCXXSourceCompiles)
 
+# These should be identical, except for one release cycle where we "warn"
+# about the coming change in requirement in the following release.
+set(GCC_MIN 4.8)
+set(GCC_WARN 4.8)
+set(CLANG_MIN 3.1)
+set(CLANG_WARN 3.1)
+
 if(NOT DEFINED LLVM_COMPILER_CHECKED)
   set(LLVM_COMPILER_CHECKED ON)
 
   if(NOT LLVM_FORCE_USE_OLD_TOOLCHAIN)
     if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
-      if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS 4.8)
-        message(FATAL_ERROR "Host GCC version must be at least 4.8!")
+      if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS GCC_MIN)
+        message(FATAL_ERROR "GCC ${CMAKE_CXX_COMPILER_VERSION} is unsupported "
+                "(minimum version is GCC ${GCC_MIN}).
+      elseif(CMAKE_CXX_COMPILER_VERSION VERSION_LESS GCC_WARN
+         AND NOT LLVM_IGNORE_HOST_COMPILER_VERSION_CHECK)
+        message(FATAL_ERROR "GCC ${CMAKE_CXX_COMPILER_VERSION} will be unsupported"
+                " in the next release, the future requirement will be GCC ${GCC_WARN}."
+                " This warning can be ignored with the cmake option LLVM_IGNORE_HOST_COMPILER_VERSION_CHECK.")
       endif()
     elseif(CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
-      if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS 3.1)
-        message(FATAL_ERROR "Host Clang version must be at least 3.1!")
+      if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS CLANG_MIN)
+        message(WARNING "Clang ${CMAKE_CXX_COMPILER_VERSION} is unsupported "
+                "(minimum version is Clang ${CLANG_MIN}).")
+      elseif(CMAKE_CXX_COMPILER_VERSION VERSION_LESS CLANG_WARN
+         AND NOT LLVM_IGNORE_HOST_COMPILER_VERSION_CHECK)
+        message(FATAL_ERROR "Clang ${CMAKE_CXX_COMPILER_VERSION} will be unsupported"
+                " in the next release, the future requirement will be GCC ${GCC_WARN}."
+                " This warning can be ignored with the cmake option LLVM_IGNORE_HOST_COMPILER_VERSION_CHECK.")"
       endif()
 
       if (CMAKE_CXX_SIMULATE_ID MATCHES "MSVC")
         if (CMAKE_CXX_SIMULATE_VERSION VERSION_LESS 19.0)
           message(FATAL_ERROR "Host Clang must have at least -fms-compatibility-version=19.0")
         endif()
         set(CLANG_CL 1)
       elseif(NOT LLVM_ENABLE_LIBCXX)

llvm/docs/CMake.rst

 **LLVM_CCACHE_BUILD**:BOOL
   If enabled and the ``ccache`` program is available, then LLVM will be
   built using ``ccache`` to speed up rebuilds of LLVM and its components.
   Defaults to OFF.  The size and location of the cache maintained
   by ``ccache`` can be adjusted via the LLVM_CCACHE_MAXSIZE and LLVM_CCACHE_DIR
   options, which are passed to the CCACHE_MAXSIZE and CCACHE_DIR environment
   variables, respectively.
 
+**LLVM_IGNORE_HOST_COMPILER_VERSION_CHECK**:BOOL
+  If enabled, the CMake checks for Clang and GCC minimum host compiler versions
+  will be ignored. This flag will likely be removed for LLVM 9.0 due to a bump
+  in the required C++ version. This defaults to OFF.
+
 CMake Caches
 ============
 
 Recently LLVM and Clang have been adding some more complicated build system
 features. Utilizing these new features often involves a complicated chain of
 CMake variables passed on the command line. Clang provides a collection of CMake
 cache scripts to make these features more approachable.
 

llvm/docs/GettingStarted.rst

 
 .. _below:
 .. _check here:
 
 Host C++ Toolchain, both Compiler and Standard Library
 ------------------------------------------------------
 
 LLVM is very demanding of the host C++ compiler, and as such tends to expose
-bugs in the compiler. We are also planning to follow improvements and
-developments in the C++ language and library reasonably closely. As such, we
-require a modern host C++ toolchain, both compiler and standard library, in
-order to build LLVM.
+bugs in the compiler. We also attempt to follow improvements and developments in
+the C++ language and library reasonably closely. As such, we require a modern
+host C++ toolchain, both compiler and standard library, in order to build LLVM.
 
 For the most popular host toolchains we check for specific minimum versions in
 our build systems:
 
 * Clang 3.1
 * GCC 4.8
 * Visual Studio 2015 (Update 3)
 
-Anything older than these toolchains *may* work, but will require forcing the
-build system with a special option and is not really a supported host platform.
-Also note that older versions of these compilers have often crashed or
-miscompiled LLVM.
+For GCC and Clang, LLVM's guideline is to support all major compiler versions
+released at least 3 years from the date in which the previous version was
+branched. Before dropping support for an older version of a compiler, we will
+consider the benefits in terms of features available for development with the
+availability of more recent versions on the most widely used platforms (for
+example considering Ubuntu LTS, etc.). When we decide to bump the minimum
+version of any compiler, we will issue a cmake warning for one release cycle
+before enforcing the new minimum.
 
 For less widely used host toolchains such as ICC or xlC, be aware that a very
 recent version may be required to support all of the C++ features used in LLVM.
 
 We track certain versions of software that are *known* to fail when used as
 part of the host toolchain. These even include linkers at times.
 
 **GNU ld 2.16.X**. Some 2.16.X versions of the ld linker will produce very long