Merging r351387, r351765, and r353374:

------------------------------------------------------------------------
r351387 | jfb | 2019-01-16 23:22:38 +0100 (Wed, 16 Jan 2019) | 7 lines

[NFC] Factor out + document build requirements

Summary: This change factors out compiler checking / warning, and documents LLVM_FORCE_USE_OLD_TOOLCHAIN. It doesn't introduce any functional changes nor policy changes, these will come late.

Subscribers: mgorny, jkorous, dexonsmith, llvm-commits

Differential Revision: https://reviews.llvm.org/D56799
------------------------------------------------------------------------

------------------------------------------------------------------------
r351765 | jfb | 2019-01-22 00:53:52 +0100 (Tue, 22 Jan 2019) | 24 lines

Document toolchain update policy

Summary:
Capture the current agreed-upon toolchain update policy based on the following
discussions:

  - LLVM dev meeting 2018 BoF "Migrating to C++14, and beyond!"
    llvm.org/devmtg/2018-10/talk-abstracts.html#bof3
  - A Short Policy Proposal Regarding Host Compilers
    lists.llvm.org/pipermail/llvm-dev/2018-May/123238.html
  - Using C++14 code in LLVM (2018)
    lists.llvm.org/pipermail/llvm-dev/2018-May/123182.html
  - Using C++14 code in LLVM (2017)
    lists.llvm.org/pipermail/llvm-dev/2017-October/118673.html
  - Using C++14 code in LLVM (2016)
    lists.llvm.org/pipermail/llvm-dev/2016-October/105483.html
  - Document and Enforce new Host Compiler Policy
    llvm.org/D47073
  - Require GCC 5.1 and LLVM 3.5 at a minimum
    llvm.org/D46723

Subscribers: jkorous, dexonsmith, llvm-commits

Differential Revision: https://reviews.llvm.org/D56819
------------------------------------------------------------------------

------------------------------------------------------------------------
r353374 | jfb | 2019-02-07 06:20:00 +0100 (Thu, 07 Feb 2019) | 12 lines

Bump minimum toolchain version

Summary:
The RFC on moving past C++11 got good traction:
  http://lists.llvm.org/pipermail/llvm-dev/2019-January/129452.html

This patch therefore bumps the toolchain versions according to our policy:
  llvm.org/docs/DeveloperPolicy.html#toolchain

Subscribers: mgorny, jkorous, dexonsmith, llvm-commits, mehdi_amini, jyknight, rsmith, chandlerc, smeenai, hans, reames, lattner, lhames, erichkeane

Differential Revision: https://reviews.llvm.org/D57264
------------------------------------------------------------------------

llvm-svn: 353512

Author: zmodem

llvm/CMakeLists.txt

@@ -383,9 +383,12 @@ option(LLVM_ENABLE_EXPENSIVE_CHECKS "Enable expensive checks" OFF)
 set(LLVM_ABI_BREAKING_CHECKS "WITH_ASSERTS" CACHE STRING
   "Enable abi-breaking checks.  Can be WITH_ASSERTS, FORCE_ON or FORCE_OFF.")
 
-option(LLVM_FORCE_USE_OLD_HOST_TOOLCHAIN
+option(LLVM_FORCE_USE_OLD_TOOLCHAIN
        "Set to ON to force using an old, unsupported host toolchain." OFF)
 
+option(LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN
+       "Set to ON to only warn when using a toolchain which is about to be deprecated, instead of emitting an error." OFF)
+
 option(LLVM_USE_INTEL_JITEVENTS
   "Use Intel JIT API to inform Intel(R) VTune(TM) Amplifier XE 2011 about JIT code"
   OFF)

llvm/cmake/modules/CheckCompilerVersion.cmake

@@ -1,52 +1,94 @@
-# 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.
+# These versions are updated based on the following policy:
+#   llvm.org/docs/DeveloperPolicy.html#toolchain
 
 include(CheckCXXSourceCompiles)
 
-if(NOT DEFINED LLVM_COMPILER_CHECKED)
-  set(LLVM_COMPILER_CHECKED ON)
+set(GCC_MIN 4.8)
+set(GCC_SOFT_ERROR 5.1)
+set(CLANG_MIN 3.1)
+set(CLANG_SOFT_ERROR 3.5)
+set(APPLECLANG_MIN 3.1)
+set(APPLECLANG_SOFT_ERROR 6.0)
+set(MSVC_MIN 19.00.24213.1)
+set(MSVC_SOFT_ERROR 19.1)
 
-  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!")
-      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!")
-      endif()
+# Map the above GCC versions to dates: https://gcc.gnu.org/develop.html#timeline
+set(GCC_MIN_DATE 20130322)
+set(GCC_SOFT_ERROR_DATE 20150422)
 
-      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)
-        # Otherwise, test that we aren't using too old of a version of libstdc++
-        # with the Clang compiler. This is tricky as there is no real way to
-        # check the version of libstdc++ directly. Instead we test for a known
-        # bug in libstdc++4.6 that is fixed in libstdc++4.7.
-        set(OLD_CMAKE_REQUIRED_FLAGS ${CMAKE_REQUIRED_FLAGS})
-        set(OLD_CMAKE_REQUIRED_LIBRARIES ${CMAKE_REQUIRED_LIBRARIES})
-        set(CMAKE_REQUIRED_FLAGS "${CMAKE_REQUIRED_FLAGS} -std=c++0x")
-        check_cxx_source_compiles("
-#include <atomic>
-std::atomic<float> x(0.0f);
-int main() { return (float)x; }"
-          LLVM_NO_OLD_LIBSTDCXX)
-        if(NOT LLVM_NO_OLD_LIBSTDCXX)
-          message(FATAL_ERROR "Host Clang must be able to find libstdc++4.8 or newer!")
-        endif()
-        set(CMAKE_REQUIRED_FLAGS ${OLD_CMAKE_REQUIRED_FLAGS})
-        set(CMAKE_REQUIRED_LIBRARIES ${OLD_CMAKE_REQUIRED_LIBRARIES})
-      endif()
-    elseif(CMAKE_CXX_COMPILER_ID MATCHES "MSVC")
-      if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS 19.0)
-        message(FATAL_ERROR "Host Visual Studio must be at least 2015")
-      elseif(CMAKE_CXX_COMPILER_VERSION VERSION_LESS 19.00.24213.1)
-        message(WARNING "Host Visual Studio should at least be 2015 Update 3 (MSVC 19.00.24213.1)"
-          "  due to miscompiles from earlier versions")
+
+if(DEFINED LLVM_COMPILER_CHECKED)
+  return()
+endif()
+set(LLVM_COMPILER_CHECKED ON)
+
+if(LLVM_FORCE_USE_OLD_TOOLCHAIN)
+  return()
+endif()
+
+function(check_compiler_version NAME NICE_NAME MINIMUM_VERSION SOFT_ERROR_VERSION)
+  if(NOT CMAKE_CXX_COMPILER_ID STREQUAL NAME)
+    return()
+  endif()
+  if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS MINIMUM_VERSION)
+    message(FATAL_ERROR "Host ${NICE_NAME} version must be at least ${MINIMUM_VERSION}, your version is ${CMAKE_CXX_COMPILER_VERSION}.")
+  elseif(CMAKE_CXX_COMPILER_VERSION VERSION_LESS SOFT_ERROR_VERSION)
+    if(LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN)
+      message(WARNING "Host ${NICE_NAME} version should be at least ${SOFT_ERROR_VERSION} because LLVM will soon use new C++ features which your toolchain version doesn't support. Your version is ${CMAKE_CXX_COMPILER_VERSION}. Ignoring because you've set LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN, but very soon your toolchain won't be supported.")
+    else()
+      message(FATAL_ERROR "Host ${NICE_NAME} version should be at least ${SOFT_ERROR_VERSION} because LLVM will soon use new C++ features which your toolchain version doesn't support. Your version is ${CMAKE_CXX_COMPILER_VERSION}. You can temporarily opt out using LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN, but very soon your toolchain won't be supported.")
+    endif()
+  endif()
+endfunction(check_compiler_version)
+
+check_compiler_version("GNU" "GCC" ${GCC_MIN} ${GCC_SOFT_ERROR})
+check_compiler_version("Clang" "Clang" ${CLANG_MIN} ${CLANG_SOFT_ERROR})
+check_compiler_version("AppleClang" "Apple Clang" ${APPLECLANG_MIN} ${APPLECLANG_SOFT_ERROR})
+check_compiler_version("MSVC" "Visual Studio" ${MSVC_MIN} ${MSVC_SOFT_ERROR})
+
+if(CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
+  if (CMAKE_CXX_SIMULATE_ID MATCHES "MSVC")
+    if (CMAKE_CXX_SIMULATE_VERSION VERSION_LESS MSVC_MIN)
+      message(FATAL_ERROR "Host Clang must have at least -fms-compatibility-version=${MSVC_MIN}, your version is ${CMAKE_CXX_COMPILER_VERSION}.")
+    endif()
+    set(CLANG_CL 1)
+  elseif(NOT LLVM_ENABLE_LIBCXX)
+    # Test that we aren't using too old of a version of libstdc++.
+    set(OLD_CMAKE_REQUIRED_FLAGS ${CMAKE_REQUIRED_FLAGS})
+    set(OLD_CMAKE_REQUIRED_LIBRARIES ${CMAKE_REQUIRED_LIBRARIES})
+    set(CMAKE_REQUIRED_FLAGS "${CMAKE_REQUIRED_FLAGS} -std=c++0x")
+    check_cxx_source_compiles("
+#include <iosfwd>
+#if defined(__GLIBCXX__)
+#if __GLIBCXX__ < ${GCC_MIN_DATE}
+#error Unsupported libstdc++ version
+#endif
+#endif
+int main() { return 0; }
+"
+      LLVM_LIBSTDCXX_MIN)
+    if(NOT LLVM_LIBSTDCXX_MIN)
+      message(FATAL_ERROR "libstdc++ version must be at least ${GCC_MIN}.")
+    endif()
+    check_cxx_source_compiles("
+#include <iosfwd>
+#if defined(__GLIBCXX__)
+#if __GLIBCXX__ < ${GCC_SOFT_ERROR_DATE}
+#error Unsupported libstdc++ version
+#endif
+#endif
+int main() { return 0; }
+"
+      LLVM_LIBSTDCXX_SOFT_ERROR)
+    if(NOT LLVM_LIBSTDCXX_SOFT_ERROR)
+      if(LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN)
+        message(WARNING "libstdc++ version should be at least ${GCC_SOFT_ERROR} because LLVM will soon use new C++ features which your toolchain version doesn't support. Ignoring because you've set LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN, but very soon your toolchain won't be supported.")
+      else()
+        message(FATAL_ERROR "libstdc++ version should be at least ${GCC_SOFT_ERROR} because LLVM will soon use new C++ features which your toolchain version doesn't support. You can temporarily opt out using LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN, but very soon your toolchain won't be supported.")
       endif()
     endif()
+    set(CMAKE_REQUIRED_FLAGS ${OLD_CMAKE_REQUIRED_FLAGS})
+    set(CMAKE_REQUIRED_LIBRARIES ${OLD_CMAKE_REQUIRED_LIBRARIES})
   endif()
 endif()

llvm/docs/CMake.rst

@@ -573,6 +573,15 @@ LLVM-specific variables
   options, which are passed to the CCACHE_MAXSIZE and CCACHE_DIR environment
   variables, respectively.
 
+**LLVM_FORCE_USE_OLD_TOOLCHAIN**:BOOL
+  If enabled, the compiler and standard library versions won't be checked. LLVM
+  may not compile at all, or might fail at runtime due to known bugs in these
+  toolchains.
+
+**LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN**:BOOL
+  If enabled, the compiler version check will only warn when using a toolchain
+  which is about to be deprecated, instead of emitting an error.
+
 CMake Caches
 ============
 

llvm/docs/DeveloperPolicy.rst

@@ -22,7 +22,7 @@ This policy is also designed to accomplish the following objectives:
 
 #. Make life as simple and easy for contributors as possible.
 
-#. Keep the tip of tree as stable as possible.
+#. Keep the top of tree as stable as possible.
 
 #. Establish awareness of the project's :ref:`copyright, license, and patent
    policies <copyright-license-patents>` with contributors to the project.
@@ -638,6 +638,47 @@ In essences, these rules are necessary for targets to gain and retain their
 status, but also markers to define bit-rot, and will be used to clean up the
 tree from unmaintained targets.
 
+.. _toolchain:
+
+Updating Toolchain Requirements
+-------------------------------
+
+We intend to require newer toolchains as time goes by. This means LLVM's
+codebase can use newer versions of C++ as they get standardized. Requiring newer
+toolchains to build LLVM can be painful for those building LLVM; therefore, it
+will only be done through the following process:
+
+  * Generally, try to support LLVM and GCC versions from the last 3 years at a
+    minimum. This time-based guideline is not strict: we may support much older
+    compilers, or decide to support fewer versions.
+
+  * An RFC is sent to the `llvm-dev mailing list <http://lists.llvm.org/mailman/listinfo/llvm-dev>`_
+
+    - Detail upsides of the version increase (e.g. which newer C++ language or
+      library features LLVM should use; avoid miscompiles in particular compiler
+      versions, etc).
+    - Detail downsides on important platforms (e.g. Ubuntu LTS status).
+
+  * Once the RFC reaches consensus, update the CMake toolchain version checks as
+    well as the :doc:`getting started<GettingStarted>` guide. We want to
+    soft-error when developers compile LLVM. We say "soft-error" because the
+    error can be turned into a warning using a CMake flag. This is an important
+    step: LLVM still doesn't have code which requires the new toolchains, but it
+    soon will. If you compile LLVM but don't read the mailing list, we should
+    tell you!
+
+  * Ensure that at least one LLVM release has had this soft-error. Not all
+    developers compile LLVM top-of-tree. These release-bound developers should
+    also be told about upcoming changes.
+
+  * Turn the soft-error into a hard-error after said LLVM release has branched.
+
+  * Update the :doc:`coding standards<CodingStandards>` to allow the new
+    features we've explicitly approved in the RFC.
+
+  * Start using the new features in LLVM's codebase.
+
+
 .. _copyright-license-patents:
 
 Copyright, License, and Patents

llvm/docs/GettingStarted.rst

@@ -170,7 +170,7 @@ uses the package and provides other details.
 Package                                                     Version      Notes
 =========================================================== ============ ==========================================
 `GNU Make <http://savannah.gnu.org/projects/make>`_         3.79, 3.79.1 Makefile/build processor
-`GCC <http://gcc.gnu.org/>`_                                >=4.8.0      C/C++ compiler\ :sup:`1`
+`GCC <http://gcc.gnu.org/>`_                                >=5.1.0      C/C++ compiler\ :sup:`1`
 `python <http://www.python.org/>`_                          >=2.7        Automated test suite\ :sup:`2`
 `zlib <http://zlib.net>`_                                   >=1.2.3.4    Compression library\ :sup:`3`
 =========================================================== ============ ==========================================
@@ -220,15 +220,25 @@ 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:
+LLVM is written using the subset of C++ documented in :doc:`coding
+standards<CodingStandards>`. To enforce this language version, we check the most
+popular host toolchains for specific minimum versions in our build systems:
+
+* Clang 3.5
+* Apple Clang 6.0
+* GCC 5.1
+* Visual Studio 2017
+
+The below versions currently soft-error as we transition to the new compiler
+versions listed above. The LLVM codebase is currently known to compile correctly
+with the following compilers, though this will change in the near future:
 
 * Clang 3.1
+* Apple Clang 3.1
 * GCC 4.8
 * Visual Studio 2015 (Update 3)
 
@@ -282,41 +292,44 @@ The first step is to get a recent GCC toolchain installed. The most common
 distribution on which users have struggled with the version requirements is
 Ubuntu Precise, 12.04 LTS. For this distribution, one easy option is to install
 the `toolchain testing PPA`_ and use it to install a modern GCC. There is
-a really nice discussions of this on the `ask ubuntu stack exchange`_. However,
-not all users can use PPAs and there are many other distributions, so it may be
-necessary (or just useful, if you're here you *are* doing compiler development
-after all) to build and install GCC from source. It is also quite easy to do
-these days.
+a really nice discussions of this on the `ask ubuntu stack exchange`_ and a
+`github gist`_ with updated commands. However, not all users can use PPAs and
+there are many other distributions, so it may be necessary (or just useful, if
+you're here you *are* doing compiler development after all) to build and install
+GCC from source. It is also quite easy to do these days.
 
 .. _toolchain testing PPA:
   https://launchpad.net/~ubuntu-toolchain-r/+archive/test
 .. _ask ubuntu stack exchange:
-  http://askubuntu.com/questions/271388/how-to-install-gcc-4-8-in-ubuntu-12-04-from-the-terminal
+  https://askubuntu.com/questions/466651/how-do-i-use-the-latest-gcc-on-ubuntu/581497#58149
+.. _github gist:
+  https://gist.github.com/application2000/73fd6f4bf1be6600a2cf9f56315a2d91
 
-Easy steps for installing GCC 4.8.2:
+Easy steps for installing GCC 5.1.0:
 
 .. code-block:: console
 
-  % wget https://ftp.gnu.org/gnu/gcc/gcc-4.8.2/gcc-4.8.2.tar.bz2
-  % wget https://ftp.gnu.org/gnu/gcc/gcc-4.8.2/gcc-4.8.2.tar.bz2.sig
+  % gcc_version=5.1.0
+  % wget https://ftp.gnu.org/gnu/gcc/gcc-${gcc_version}/gcc-${gcc_version}.tar.bz2
+  % wget https://ftp.gnu.org/gnu/gcc/gcc-${gcc_version}/gcc-${gcc_version}.tar.bz2.sig
   % wget https://ftp.gnu.org/gnu/gnu-keyring.gpg
-  % signature_invalid=`gpg --verify --no-default-keyring --keyring ./gnu-keyring.gpg gcc-4.8.2.tar.bz2.sig`
+  % signature_invalid=`gpg --verify --no-default-keyring --keyring ./gnu-keyring.gpg gcc-${gcc_version}.tar.bz2.sig`
   % if [ $signature_invalid ]; then echo "Invalid signature" ; exit 1 ; fi
-  % tar -xvjf gcc-4.8.2.tar.bz2
-  % cd gcc-4.8.2
+  % tar -xvjf gcc-${gcc_version}.tar.bz2
+  % cd gcc-${gcc_version}
   % ./contrib/download_prerequisites
   % cd ..
-  % mkdir gcc-4.8.2-build
-  % cd gcc-4.8.2-build
-  % $PWD/../gcc-4.8.2/configure --prefix=$HOME/toolchains --enable-languages=c,c++
+  % mkdir gcc-${gcc_version}-build
+  % cd gcc-${gcc_version}-build
+  % $PWD/../gcc-${gcc_version}/configure --prefix=$HOME/toolchains --enable-languages=c,c++
   % make -j$(nproc)
   % make install
 
 For more details, check out the excellent `GCC wiki entry`_, where I got most
 of this information from.
 
 .. _GCC wiki entry:
-  http://gcc.gnu.org/wiki/InstallingGCC
+  https://gcc.gnu.org/wiki/InstallingGCC
 
 Once you have a GCC toolchain, configure your build of LLVM to use the new
 toolchain for your host compiler and C++ standard library. Because the new
@@ -336,7 +349,7 @@ If you fail to set rpath, most LLVM binaries will fail on startup with a message
 from the loader similar to ``libstdc++.so.6: version `GLIBCXX_3.4.20' not
 found``. This means you need to tweak the -rpath linker flag.
 
-When you build Clang, you will need to give *it* access to modern C++11
+When you build Clang, you will need to give *it* access to modern C++
 standard library in order to use it as your new host in part of a bootstrap.
 There are two easy ways to do this, either build (and install) libc++ along
 with Clang and then use it with the ``-stdlib=libc++`` compile and link flag,