[libc++][docs] Update documentation to reflect libc++'s compiler support policy

[ldionne]

Summary

In https://lists.llvm.org/pipermail/llvm-dev/2021-March/148881.html, we
discussed updating the compiler support policy for libc++ to match more
closely what we do actually support.

This commit enshrines that policy decision in libc++'s documentation.

[ldionne]

Adding folks who might want to see this as a heads up, and folks who posted in the original LLVM-dev thread (https://lists.llvm.org/pipermail/llvm-dev/2021-March/148881.html).

I'm going to land this once the CI is green, since the discussion has been had in March. After this change, we will finally document the support that we actually provide.

[ldionne]

libcxx/docs/index.rst

116

@dim Would it be possible to set up a FreeBSD bot? I'm happy to help you with that, but we need one if we don't want to be lying here.

[phosek]

libcxx/docs/index.rst

113

I'd be interested in including Fuchsia here but we don't have bots yet, it's something we plan to work on in H2 2021.

115

Since we're distinguishing 32-bit and 64-bit x86, shall we also do the same for ARM, that is have ARM and ARM64?

117

FWIW we're using libc++ on ARM64 and we even run lib++ tests on ARM64 machines in our downstream CI so I'm pretty confident about Linux support for ARM64.

[mstorsjo]

libcxx/docs/index.rst

113

Windows is missing in this list. In practice it works for i386, x86_64, ARM and ARM64, but the CI setup covers x86_64. In my downstream usage it practically runs fine on all of them (but I haven't run full testsuite rounds on other than x86_64 and arm64).

[Mordante]

Thanks for updating the documentation!

libcxx/docs/index.rst

117

We have build bots running for AArch64, Armv7, and Armv8.

[rnk]

libcxx/docs/index.rst

115

I think Chrome still builds libc++ statically for 10.11:
https://source.chromium.org/chromium/chromium/src/+/main:build/config/mac/mac_sdk.gni;l=21

Some time in the next year or two it will likely be raised, but I can't commit to a timeline. If someone lands changes that don't work on 10.11, someone from our team will try to put together a workaround patch for 10.11. The audience for this document is probably libc++ developers, so if they want to minimize the amount of post-commit code review work, it might be less work to use 10.11 here.

[emaste]

libcxx/docs/index.rst

116

I'll take this on.

[zoecarver]

Thanks, Louis! Does this mean we officially no longer support Clang 10 (for example) on main? Or does this only come into effect after llvm 13 is released?

[ldionne]

libcxx/docs/index.rst

113

@phosek Awesome, I'll be looking forward to helping you setup Fuchsia build bots and then adding it to the list.

@mstorsjo I'll add Windows to the list. I based this off of the list we had previously, but I guess it makes sense to complete it. Are there any plans to add real CI for Windows / arm64?

115

Oh yeah, you're right. Adjusting.

116

Awesome, thanks. What we're looking for is a BuildKite bot, as documented here: https://libcxx.llvm.org/AddingNewCIJobs.html#addingnewcijobs.

Feel free to ping me on Discord and I'll help you set them up, it's pretty easy.

[ldionne]

Address review comments

[mstorsjo]

libcxx/docs/index.rst

113

Windows/arm64 isn't available on any common cloud infra providers that I know of yet (I don't know about the setup where the current buildkite windows runners are hosted, but I doubt they have it easily accessible either), so probably no plans for that in the immediate future.

[Mordante]

LGTM! Since there's one new review comment I only approve as myself.

[ldionne]

libcxx/docs/index.rst

113

Alright, in that case I'm going to remove arm64 from Windows since we are unable to test it on a regular basis. I really want to avoid being hand-wavy -- when we say we support it, I want us to truly provide support for it, which we're unable to do if we don't test publicly on a regular basis.

[ldionne]

Remove arm64 from Windows

[mstorsjo]

libcxx/docs/index.rst

113

I appreciate that you want to avoid being hand-wavy, but would you be ok with adding a separate paragraph clarifying what support means here, e.g. something along these lines?

"These are platform/architecture combinations that are continuously tested, that we support. In practice, the library also is regularly used on other architectures, but as they're not continuously tested they're not formally supported."

... because I've had my fair share of dealing with people interpreting lists like this as "the website says it *only* works on x86_64 on windows, so it's certainly broken on the other architectures". So that acknowledges that we're aware of it working well on other architectures too (even though that makes it a bit more hand-wavy), and that makes it a bit clearer that not being on the list doesn't make it more broken, just less continuously tested.

libcxx/docs/index.rst

* Design and Implementation:
 
   * Extensive unit tests
   * Internal linker model can be dumped/read to textual format
   * Additional linking features can be plugged in as "passes"
   * OS specific and CPU specific code factored out
 
 
 Getting Started with libc++
----------------------------
+===========================
 
 .. toctree::
    :maxdepth: 1
 
    ReleaseNotes
    UsingLibcxx
    BuildingLibcxx
    TestingLibcxx

 .. toctree::
     :hidden:
 
     AddingNewCIJobs
     FeatureTestMacroTable
 
 
 Current Status
---------------
+==============
 
 After its initial introduction, many people have asked "why start a new
 library instead of contributing to an existing library?" (like Apache's
 libstdcxx, GNU's libstdc++, STLport, etc).  There are many contributing
 reasons, but some of the major ones are:
 
 * From years of experience (including having implemented the standard
   library before), we've learned many things about implementing
* STLport and the Apache libstdcxx library are two other popular
   experience of libstdc++ developers) is that adding support for C++11 (in
   particular rvalue references and move-only types) requires changes to
   almost every class and function, essentially amounting to a rewrite.
   Faced with a rewrite, we decided to start from scratch and evaluate every
   design decision from first principles based on experience.
   Further, both projects are apparently abandoned: STLport 5.2.1 was
   released in Oct'08, and STDCXX 4.2.1 in May'08.
 
-Platform and Compiler Support
------------------------------
-
-For using the libc++ headers
-############################
-The libc++ headers are known to work on the following platforms, using GCC and
-Clang. Note that functionality provided by ``<atomic>`` is only functional with
-Clang and GCC.
-
-============ ==================== ============
-OS           Arch                 Compilers
-============ ==================== ============
-macOS 10.9+  i386, x86_64         Clang, GCC
-FreeBSD 10+  i386, x86_64, ARM    Clang, GCC
-Linux        i386, x86_64         Clang, GCC
-============ ==================== ============
-
-The following minimum compiler versions are required:
-
-* Clang 4.0 and above
-* GCC 5.0 and above.
-
-The C++03 dialect is only supported with Clang.
-
-For building the libc++ library
-###############################
-Building the libc++ library (static or shared) requires some features from
-the operating system. As such, it has its own set of (slightly different)
-system requirements.
-
-============ ==================== ============ ========================
-OS           Arch                 Compilers    ABI Library
-============ ==================== ============ ========================
-macOS 10.12+ i386, x86_64         Clang, GCC   libc++abi
-FreeBSD 10+  i386, x86_64, ARM    Clang, GCC   libcxxrt, libc++abi
-Linux        i386, x86_64         Clang, GCC   libc++abi
-============ ==================== ============ ========================
 
-The following minimum compiler versions are required:
+Platform and Compiler Support
+=============================
 
-* Clang 4.0 and above
-* GCC 5.0 and above.
+Libc++ aims to support common compilers that implement the C++11 Standard. In order to strike a
+good balance between stability for users and maintenance cost, testing coverage and development
+velocity, libc++ drops support for older compilers as newer ones are released.
+
+============ =============== ========================== =====================
+Compiler     Versions        Restrictions               Support policy
+============ =============== ========================== =====================
+Clang        11, 12                                     latest two stable releases per `LLVM's release page <https://releases.llvm.org>`_
+AppleClang   12                                         latest stable release per `Xcode's release page <https://developer.apple.com/documentation/xcode-release-notes>`_
+GCC          11              In C++11 or later only     latest stable release per `GCC's release page <https://gcc.gnu.org/releases.html>`_
+============ =============== ========================== =====================
+
+Libc++ also supports common platforms and architectures:
+
+=============== ==================== ============================
+Target platform Target architecture  Notes
+=============== ==================== ============================
+macOS 10.9+     i386, x86_64, ARM    Building the shared library itself requires targetting macOS 10.12+
+FreeBSD 10+     i386, x86_64, ARM
+Linux           i386, x86_64
+=============== ==================== ============================
+
+Generally speaking, libc++ should work on any platform that provides a fairly complete
+C Standard Library. It is also possible to turn off parts of the library for use on
+systems that provide incomplete support.
+
+However, libc++ aims to provide a high-quality implementation of the C++ Standard
+Library, especially when it comes to correctness. As such, we aim to have test coverage
+for all the platforms and compilers that we claim to support. If a platform or compiler
+is not listed here, it is not officially supported. It may happen to work, but we don't
+make any guarantees. If you would like your compiler and/or platform to be listed here,
+please work with the libc++ team to set up testing for your configuration.
 
 
 C++ Dialect Support
----------------------
+===================
 
 * C++11 - Complete
 * :ref:`C++14 - Complete <cxx14-status>`
 * :ref:`C++17 - In Progress <cxx17-status>`
 * :ref:`C++20 - In Progress <cxx20-status>`
 * :ref:`C++2b - In Progress <cxx2b-status>`
 * :ref:`C++ Feature Test Macro Status <feature-status>`
 
+
 Notes and Known Issues
-----------------------
+======================
 
 This list contains known issues with libc++
 
 * Building libc++ with ``-fno-rtti`` is not supported. However
   linking against it with ``-fno-rtti`` is supported.
 
 
 A full list of currently open libc++ bugs can be `found here`__.
 
 .. __:  https://bugs.llvm.org/buglist.cgi?component=All%20Bugs&product=libc%2B%2B&query_format=advanced&resolution=---&order=changeddate%20DESC%2Cassigned_to%20DESC%2Cbug_status%2Cpriority%2Cbug_id&list_id=74184
 
+
 Design Documents
-----------------
+================
 
 .. toctree::
    :maxdepth: 1
 
    DesignDocs/ABIVersioning
    DesignDocs/AtomicDesign
    DesignDocs/CapturingConfigInfo
    DesignDocs/DebugMode
    DesignDocs/ExperimentalFeatures
    DesignDocs/ExtendedCXX03Support
    DesignDocs/FeatureTestMacros
    DesignDocs/FileTimeType
    DesignDocs/NoexceptPolicy
    DesignDocs/ThreadingSupportAPI
    DesignDocs/UniquePtrTrivialAbi
    DesignDocs/VisibilityMacros
 
+
 Build Bots and Test Coverage
-----------------------------
+============================
 
 * `Buildkite CI pipeline <https://buildkite.com/llvm-project/libcxx-ci>`_
 * `LLVM Buildbot Builders <http://lab.llvm.org:8011>`_
 * :ref:`Adding New CI Jobs <AddingNewCIJobs>`
 
+
 Getting Involved
 ================
 
 First please review our `Developer's Policy <https://llvm.org/docs/DeveloperPolicy.html>`__
 and `Getting started with LLVM <https://llvm.org/docs/GettingStarted.html>`__.
 
 **Bug Reports**
 
 If you think you've found a bug in libc++, please report it using
 the `LLVM Bugzilla`_. If you're not sure, you
 can post a message to the `libcxx-dev mailing list`_ or on IRC.
 
 **Patches**
 
 If you want to contribute a patch to libc++, the best place for that is
 `Phabricator <https://llvm.org/docs/Phabricator.html>`_. Please add `libcxx-commits` as a subscriber.
 Also make sure you are subscribed to the `libcxx-commits mailing list <http://lists.llvm.org/mailman/listinfo/libcxx-commits>`_.
 
 **Discussion and Questions**
 
 Send discussions and questions to the
 `libcxx-dev mailing list <http://lists.llvm.org/mailman/listinfo/libcxx-dev>`_.
 
 
-
 Quick Links
 ===========
 * `LLVM Homepage <https://llvm.org/>`_
 * `libc++abi Homepage <http://libcxxabi.llvm.org/>`_
 * `LLVM Bugzilla <https://bugs.llvm.org/>`_
 * `libcxx-commits Mailing List`_
 * `libcxx-dev Mailing List`_
 * `Browse libc++ Sources <https://github.com/llvm/llvm-project/tree/main/libcxx/>`_