From: JF Bastien Date: Mon, 21 Jan 2019 23:53:52 +0000 (+0000) Subject: Document toolchain update policy X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=d1086040f5c3e84405061a7ffaeaf41f0e2107ce;p=llvm 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 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@351765 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/cmake/modules/CheckCompilerVersion.cmake b/cmake/modules/CheckCompilerVersion.cmake index bd491fe053c..67f533f9aba 100644 --- a/cmake/modules/CheckCompilerVersion.cmake +++ b/cmake/modules/CheckCompilerVersion.cmake @@ -1,6 +1,6 @@ # Check if the host compiler is new enough. # These versions are updated based on the following policy: -# llvm.org/docs/GettingStarted.html#host-c-toolchain-both-compiler-and-standard-library +# llvm.org/docs/DeveloperPolicy.html#toolchain include(CheckCXXSourceCompiles) diff --git a/docs/DeveloperPolicy.rst b/docs/DeveloperPolicy.rst index a9cd4df2d95..d896192ebef 100644 --- a/docs/DeveloperPolicy.rst +++ b/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 ` 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 `_ + + - 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` 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` 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 diff --git a/docs/GettingStarted.rst b/docs/GettingStarted.rst index b714cc6601a..d2a5b13a0a2 100644 --- a/docs/GettingStarted.rst +++ b/docs/GettingStarted.rst @@ -220,15 +220,16 @@ 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`. To enforce this language version, we check the most +popular host toolchains for specific minimum versions in our build systems: * Clang 3.1 +* Apple Clang 3.1 * GCC 4.8 * Visual Studio 2015 (Update 3) @@ -336,7 +337,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,