Document toolchain update policy

[jfb]

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

See the corresponding RFC: http://lists.llvm.org/pipermail/llvm-dev/2019-January/129241.html

[jfb]

Please see the corresponding RFC: http://lists.llvm.org/pipermail/llvm-dev/2019-January/129241.html

[efriedma]

GettingStarted.rst is probably not the best place to put the policy for updating the required version. I mean, I guess it's sort of convenient because it's right next to the actual versions, but we don't want to force new users to wade through it.

[jfb]

In D56819#1360731, @efriedma wrote:

GettingStarted.rst is probably not the best place to put the policy for updating the required version. I mean, I guess it's sort of convenient because it's right next to the actual versions, but we don't want to force new users to wade through it.

Where would a better place be?

[craig.topper]

docs/GettingStarted.rst

270

Was "fewer" here supposed to be "newer"? Or is just the "fewer ones" doesn't read very well?

[jfb]

docs/GettingStarted.rst

270

Maybe it's my ESL, I definitely mean "fewer" as in "fewer versions than a 3 year loopback would otherwise capture". I'm happy to clarify however you think would make sense.

[craig.topper]

docs/GettingStarted.rst

270

Maybe just change "ones" to "versions"?

[efriedma]

DeveloperPolicy.rst, maybe?

[aprantl]

docs/GettingStarted.rst

227–229

why currently?

[jfb]

• Minor comments.

docs/GettingStarted.rst

227–229

Obviously we'll move to JavaScript in the future 🤡

[jfb]

• Move to DeveloperPolicy

[jfb]

In D56819#1360780, @efriedma wrote:

DeveloperPolicy.rst, maybe?

Oh nice, that's indeed much better. Updated.

[jfb]

• Remove extra space.

[Eugene.Zelenko]

docs/DeveloperPolicy.rst

671

top-of-tree

[serge-sans-paille]

docs/GettingStarted.rst

234

Visual Studio is mentionned here, but not in the

Generally, try to support LLVM and GCC versions from the last 3 years at a minimum

Sentence around line 651 in docs/DeveloperPolicy.rst. maybe we should harmonize that?

[jfb]

• Nit

[jfb]

docs/GettingStarted.rst

234

The prior discussions were mostly worried about 2 things:

• Distros come with GCC preinstalled, and people want to avoid building a new GCC to build clang. The policy tries to reduce bootstrapping work when possible, and a proposal has to look at which versions of GCC we're phasing out from which distros.
• Clang bootstrap is another worry: how many times would one need to compile clang?

In general, the feeling from the conversations was that updating MSVC hasn't been too much of an issue for people in the discussion. Further, while recent MSVC has amazing C++ support, older ones don't. That's why there's no guidance on MSVC. It doesn't mean "ignore MSVC", it just means there's no ballpark guidance *right now*, but a proposal to bump minimum MSVC versions should still consider what bumping MSVC means.

To be clear: "the policy doesn't say anything about X" doesn't mean we can ignore X.

A future revision of this policy could obviously have guidance for MSVC.

[lhames]

This looks great. Thanks JF!

[hubert.reinterpretcast]

docs/DeveloperPolicy.rst

677

The suggested wording implies that consensus for updating version requirements for some generic toolchains is consensus to update the set of language features to "whatever falls out of the support provided by those toolchain versions". I think that this step in the proposed process should instead be to identify the features that are now available by the minimum versions of the popular toolchains, and begin a discussion on what features we will start using.

[jfb]

docs/DeveloperPolicy.rst

677

An earlier point says:

• 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. allow LLVM to use newer C++ language or library features; avoid miscompiles in particular compiler versions, etc).
  • Detail downsides on important platforms (e.g. Ubuntu LTS status).

If you think that wording is unclear, please provide concrete alternatives.

[hubert.reinterpretcast]

docs/DeveloperPolicy.rst

657

<del>allow</del><ins>potential for</ins> LLVM to use newer C++ language or library features

677

Motivations for a version increase should not be confused with the results of a version increase. If a non-motivating feature is "unlocked" by the version increase, for example, that feature would not necessarily have been mentioned prior to reaching this step. I do not see why such a feature then automatically becomes "fair game".

An explicit discussion of the language support necessary allows users of compilers other than the "popular toolchains" to evaluate the requirements and communicate with their vendors.

[jfb]

• Clarify how new language features get in.

[jfb]

docs/DeveloperPolicy.rst

677

That's a pretty adversarial reading of the policy... I've clarified the wording to avoid that pitfall.

[smeenai]

docs/DeveloperPolicy.rst

648

Grammar nit: You either want a "Since" before the "Requiring", or a "so" after the comma and before the "it", otherwise the sentence flows weirdly.

[hubert.reinterpretcast]

docs/DeveloperPolicy.rst

670

I believe we should be clear as to whether this means one release cycle where the soft-error has been present since the last release branched, or if we mean that the soft-error made it into one release branch (no matter how late the soft-error was added).

For example: If the soft-error is added late in the development cycle of a release (say, to 10.0 in December), does the proposed process imply that top-of-tree can have the hard-error by next January with a soft-error only added over the holiday season?

674

This does mean that release-bound developers (who do not look at top-of-tree, release candidates, or the mailing list) will, on discovering that they might not be able to move to the next release (thanks to the warning), find that top-of-tree has already been unusable for them for around 2-3 months (or whatever amount of time it took for the release to ship after being branched from trunk). Which is to say that the warning truly is just telling them, and not really asking them.

677

Thanks; this addresses the point I raised.

[hubert.reinterpretcast]

docs/DeveloperPolicy.rst

648

I believe both since and so would be redundant with therefore. The flow can be fixed by using "; therefore, it will" instead of ", it will therefore".

[jfb]

• gramer

[jfb]

docs/DeveloperPolicy.rst

670

That's really up to the release manager, I don't think we need to nail down every single eventuality. In particular, to really figure out the right thing to do we'd need to know when people compile clang branches: do they do so early or late, or only when the branch is deemed "done"? If say a Linux distro only takes the branch once "done", then your point is totally moot. And say they get bit by something, and decide to start compiling them earlier, then whatever policy is now based on outdated facts.

There's so many eventualities that I really don't think we need to decide on a policy. The release manager is smart, let's trust them. @hans WDYT?

674

Correct.

[lattner]

Looks great!

[michaelplatings]

docs/DeveloperPolicy.rst

671

It still says tip-of-tree. I think tip-of-tree is better as tip has a particular meaning in Git, but either way it should be consistent with "Keep the t[io]p of tree as stable as possible." on line 25.

[hans]

docs/DeveloperPolicy.rst

670

I think the text as proposed here is fine.

[jfb]

• top

[jfb]

Address typo correctly this time!

[jfb]

So far we have ✅ from @erichkeane @lhames @lattner on this review, and +1 / LGTM on the llvm-dev RFC from @reames @jyknight @chandlerc @JonasToth @mehdi_amini. I haven't seen any pushback, and I think I've properly addressed all suggestions received so far. I'll leave the patch here over the weekend, and will commit on Monday assuming nobody else chimes in. I'll then send a follow-up RFC proposing that we migrate LLVM past C++11, following the process outlined here. Thanks all!

[lebedev.ri]

Looks good to me too. (don't think i should formally accept this though)

docs/DeveloperPolicy.rst

660

Passing-by remark: it may be a good idea to consider debian stable too.

[jfb]

docs/DeveloperPolicy.rst

660

I don't want a list here because over time what matters will likely change. "e.g." is just an example. I expect us to be smart about this and not need everything spelled out in details.

In the follow-up RFC I'll send next week, I plan to use the same table of *nix distros that I had in my BoF: RHEL, Debian, OpenBSD, Ubuntu (as well as GCC, LLVM, and MSVC mentions). I'd expect future RFCs to use a similar list, adding / removing as appropriate.

[erichkeane]

docs/DeveloperPolicy.rst

660

No change in this patch, but I'd suggest that the first successful example of this happening be linked here. It would be wonderful if said RFC had a fairly easy to update "Form" that'll make future updates more clear to review.

[jfb]

docs/DeveloperPolicy.rst

660

That's a great idea. That makes me think that the RFC should conclude with a summary of what was decided, which can be the template for the next time around (and we'd link to it from this doc).

[jfb]

Thanks all for the comments! I'll work on sending out and RFC which follows this new policy.

[jfb]

For future reference:

• RFC proposing that we migrate past C++11: http://lists.llvm.org/pipermail/llvm-dev/2019-January/129452.html
• Patch which applies the soft-error: https://reviews.llvm.org/D57264

cmake/modules/CheckCompilerVersion.cmake

 # 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)
 
 set(GCC_MIN 4.8)
 set(GCC_WARN 4.8)
 set(CLANG_MIN 3.1)
 set(CLANG_WARN 3.1)
 set(APPLECLANG_MIN 3.1)

docs/DeveloperPolicy.rst

 LLDB, libc++, etc.
 
 This policy is also designed to accomplish the following objectives:
 
 #. Attract both users and developers to the LLVM project.
 
 #. 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.
 
 This policy is aimed at frequent contributors to LLVM. People interested in
 contributing one-off patches can do so in an informal way by sending them to the
 `llvm-commits mailing list
 <http://lists.llvm.org/mailman/listinfo/llvm-commits>`_ and engaging another

 * Degradation in support, documentation or test coverage will make the target as
   nuisance to other targets and be considered a candidate for deprecation and
   ultimately removed.
 
 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, it will
+therefore 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 tip-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
 ===============================
 
 .. note::
 
    This section deals with legal matters but does not provide legal advice.  We

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.
-
-For the most popular host toolchains we check for specific minimum versions in
-our build systems:
+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.
+
+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.1
+* Apple 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 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.

 
 Getting a Modern Host C++ Toolchain
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This section mostly applies to Linux and older BSDs. On Mac OS X, you should
 have a sufficiently modern Xcode, or you will likely need to upgrade until you
 do. Windows does not have a "system compiler", so you must install either Visual
 Studio 2015 or a recent version of mingw64. FreeBSD 10.0 and newer have a modern
 Clang as the system compiler.
 
 However, some Linux distributions and some other or older BSDs sometimes have
 extremely old versions of GCC. These steps attempt to help you upgrade you
 compiler even on such a system. However, if at all possible, we encourage you
 to use a recent version of a distribution with a modern system compiler that
 meets these requirements. Note that it is tempting to install a prior
 version of Clang and libc++ to be the host compiler, however libc++ was not
 well tested or set up to build on Linux until relatively recently. As
.. code-block:: console
   % cd build
   % CC=$HOME/toolchains/bin/gcc CXX=$HOME/toolchains/bin/g++ \
     cmake .. -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$HOME/toolchains/lib64 -L$HOME/toolchains/lib64"
 
 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,
 or install Clang into the same prefix (``$HOME/toolchains`` above) as GCC.
 Clang will look within its own prefix for libstdc++ and use it if found. You
 can also add an explicit prefix for Clang to look in for a GCC toolchain with
 the ``--gcc-toolchain=/opt/my/gcc/prefix`` flag, passing it to both compile and
 link commands when using your just-built-Clang to bootstrap.