[libc++][docs] Major update to the documentation

ldionne · ldionne · commit 41dcdfbff12a · 2024-08-22T10:30:10.000-04:00
- Landing page: add link to the libc++ Discord channel
- Landing page: reorder "Getting Involved" above "Design documents"
- Landing page: remove "Notes and Known Issues" which was completely outdated
- Rename "Using Libc++" to "User Documentation" and update contents
- Rename "Building Libc++" to "Vendor Documentation" and update contents

The "BuildingLibcxx" and "UsingLibcxx" pages have basically been used for
vendor and user documentation respectively. However, they were named in
a way that doesn't really make that clear. Renaming the pages now gives
us a location to clearly document what we target at vendors and what we
target at users, and to do that separately.
diff --git a/libcxx/CMakeLists.txt b/libcxx/CMakeLists.txt
@@ -1,6 +1,3 @@
-# See https://libcxx.llvm.org/docs/BuildingLibcxx.html for instructions on how
-# to build libcxx with CMake.
-
 #===============================================================================
 # Setup Project
 #===============================================================================
diff --git a/libcxx/docs/Contributing.rst b/libcxx/docs/Contributing.rst
@@ -4,9 +4,9 @@
 Contributing to libc++
 ======================
 
-This file contains notes about various tasks and processes specific to contributing
-to libc++. If this is your first time contributing, please also read `this document
-<https://www.llvm.org/docs/Contributing.html>`__ on general rules for contributing to LLVM.
+This file contains information useful when contributing to libc++. If this is your first time contributing,
+please also read `this document <https://www.llvm.org/docs/Contributing.html>`__ on general rules for
+contributing to LLVM.
 
 If you plan on contributing to libc++, it can be useful to join the ``#libcxx`` channel
 on `LLVM's Discord server <https://discord.gg/jzUbyP26tQ>`__.
@@ -24,16 +24,22 @@ RFCs for significant user-affecting changes
 ===========================================
 
 Before you start working on a change that can have significant impact on users of the library,
-please consider creating a RFC on `libc++'s Discourse forum <https://discourse.llvm.org/c/runtimes/libcxx>`__.
+please consider creating a RFC on the `libc++ forum <https://discourse.llvm.org/c/runtimes/libcxx>`_.
 This will ensure that you work in a direction that the project endorses and will ease reviewing your
-contribution as directional questions can be raised early. Including a WIP patch is not mandatory, but
-it can be useful to ground the discussion in something concrete.
+contribution as directional questions can be raised early. Including a WIP patch is not mandatory,
+but it can be useful to ground the discussion in something concrete.
+
+Writing tests and running the test suite
+========================================
+
+Every change in libc++ must come with appropriate tests. Libc++ has an extensive test suite that
+should be run locally by developers before submitting patches and is also run as part of our CI
+infrastructure. The documentation about writing tests and running them is :ref:`here <testing>`.
 
 Coding standards
 ================
 
-In general, libc++ follows the
-`LLVM Coding Standards <https://llvm.org/docs/CodingStandards.html>`_.
+In general, libc++ follows the `LLVM Coding Standards <https://llvm.org/docs/CodingStandards.html>`_.
 There are some deviations from these standards.
 
 Libc++ uses ``__ugly_names``. These names are reserved for implementations, so
diff --git a/libcxx/docs/TestingLibcxx.rst b/libcxx/docs/TestingLibcxx.rst
@@ -1,12 +1,12 @@
+.. _testing:
+
 ==============
 Testing libc++
 ==============
 
 .. contents::
   :local:
 
-.. _testing:
-
 Getting Started
 ===============
 
@@ -459,11 +459,6 @@ This will build all of the benchmarks under ``<libcxx>/test/benchmarks`` to be
 built against the just-built libc++. The compiled tests are output into
 ``build/libcxx/test/benchmarks``.
 
-Also See:
-
-  * :ref:`Building Libc++ <build instructions>`
-  * :ref:`CMake Options`
-
 Running Benchmarks
 ------------------
 
diff --git a/libcxx/docs/UserDocumentation.rst b/libcxx/docs/UserDocumentation.rst
@@ -1,19 +1,17 @@
-.. _using-libcxx:
+.. _user-documentation:
 
-============
-Using libc++
-============
+==================
+User documentation
+==================
 
 .. contents::
   :local:
 
-Usually, libc++ is packaged and shipped by a vendor through some delivery vehicle
-(operating system distribution, SDK, toolchain, etc) and users don't need to do
-anything special in order to use the library.
-
 This page contains information about configuration knobs that can be used by
 users when they know libc++ is used by their toolchain, and how to use libc++
-when it is not the default library used by their toolchain.
+when it is not the default library used by their toolchain. It is aimed at
+users of libc++: a separate page contains documentation aimed at vendors who
+build and ship libc++ as part of their toolchain.
 
 
 Using a different version of the C++ Standard
@@ -28,10 +26,29 @@ matches that Standard in the library.
 
   $ clang++ -std=c++17 test.cpp
 
-.. warning::
-  Using ``-std=c++XY`` with a version of the Standard that has not been ratified yet
-  is considered unstable. Libc++ reserves the right to make breaking changes to the
-  library until the standard has been ratified.
+Note that using ``-std=c++XY`` with a version of the Standard that has not been ratified
+yet is considered unstable. While we strive to maintain stability, libc++ may be forced to
+make breaking changes to features shipped in a Standard that hasn't been ratified yet. Use
+these versions of the Standard at your own risk.
+
+
+Using libc++ when it is not the system default
+==============================================
+
+Usually, libc++ is packaged and shipped by a vendor through some delivery vehicle
+(operating system distribution, SDK, toolchain, etc) and users don't need to do
+anything special in order to use the library.
+
+On systems where libc++ is provided but is not the default, Clang provides a flag
+called ``-stdlib=`` that can be used to decide which standard library is used.
+Using ``-stdlib=libc++`` will select libc++:
+
+.. code-block:: bash
+
+  $ clang++ -stdlib=libc++ test.cpp
+
+On systems where libc++ is the library in use by default such as macOS and FreeBSD,
+this flag is not required.
 
 
 Enabling experimental C++ Library features
@@ -43,6 +60,11 @@ the Standard but whose implementation is not complete or stable yet in libc++. T
 are disabled by default because they are neither API nor ABI stable. However, the
 ``-fexperimental-library`` compiler flag can be defined to turn those features on.
 
+On compilers that do not support the ``-fexperimental-library`` flag (such as GCC),
+users can define the ``_LIBCPP_ENABLE_EXPERIMENTAL`` macro and manually link against
+the appropriate static library (usually shipped as ``libc++experimental.a``) to get
+access to experimental library features.
+
 The following features are currently considered experimental and are only provided
 when ``-fexperimental-library`` is passed:
 
@@ -51,7 +73,7 @@ when ``-fexperimental-library`` is passed:
 * ``std::jthread``
 * ``std::chrono::tzdb`` and related time zone functionality
 
-.. warning::
+.. note::
   Experimental libraries are experimental.
     * The contents of the ``<experimental/...>`` headers and the associated static
       library will not remain compatible between versions.
@@ -60,98 +82,18 @@ when ``-fexperimental-library`` is passed:
       the experimental feature is removed two releases after the non-experimental
       version has shipped. The full policy is explained :ref:`here <experimental features>`.
 
-.. note::
-  On compilers that do not support the ``-fexperimental-library`` flag, users can
-  define the ``_LIBCPP_ENABLE_EXPERIMENTAL`` macro and manually link against the
-  appropriate static library (usually shipped as ``libc++experimental.a``) to get
-  access to experimental library features.
-
-
-Using libc++ when it is not the system default
-==============================================
-
-On systems where libc++ is provided but is not the default, Clang provides a flag
-called ``-stdlib=`` that can be used to decide which standard library is used.
-Using ``-stdlib=libc++`` will select libc++:
-
-.. code-block:: bash
-
-  $ clang++ -stdlib=libc++ test.cpp
-
-On systems where libc++ is the library in use by default such as macOS and FreeBSD,
-this flag is not required.
-
-
-.. _alternate libcxx:
-
-Using a custom built libc++
-===========================
-
-Most compilers provide a way to disable the default behavior for finding the
-standard library and to override it with custom paths. With Clang, this can
-be done with:
-
-.. code-block:: bash
-
-  $ clang++ -nostdinc++ -nostdlib++           \
-            -isystem <install>/include/c++/v1 \
-            -L <install>/lib                  \
-            -Wl,-rpath,<install>/lib          \
-            -lc++                             \
-            test.cpp
-
-The option ``-Wl,-rpath,<install>/lib`` adds a runtime library search path,
-which causes the system's dynamic linker to look for libc++ in ``<install>/lib``
-whenever the program is loaded.
-
-GCC does not support the ``-nostdlib++`` flag, so one must use ``-nodefaultlibs``
-instead. Since that removes all the standard system libraries and not just libc++,
-the system libraries must be re-added manually. For example:
-
-.. code-block:: bash
-
-  $ g++ -nostdinc++ -nodefaultlibs           \
-        -isystem <install>/include/c++/v1    \
-        -L <install>/lib                     \
-        -Wl,-rpath,<install>/lib             \
-        -lc++ -lc++abi -lm -lc -lgcc_s -lgcc \
-        test.cpp
-
-
-GDB Pretty printers for libc++
-==============================
-
-GDB does not support pretty-printing of libc++ symbols by default. However, libc++ does
-provide pretty-printers itself. Those can be used as:
-
-.. code-block:: bash
-
-  $ gdb -ex "source <libcxx>/utils/gdb/libcxx/printers.py" \
-        -ex "python register_libcxx_printer_loader()" \
-        <args>
-
-.. _include-what-you-use:
-
-include-what-you-use (IWYU)
-===========================
-
-libc++ provides an IWYU `mapping file <https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUMappings.md>`_,
-which drastically improves the accuracy of the tool when using libc++. To use the mapping file with
-IWYU, you should run the tool like so:
-
-.. code-block:: bash
-
-  $ include-what-you-use -Xiwyu --mapping_file=/path/to/libcxx/include/libcxx.imp file.cpp
-
-If you would prefer to not use that flag, then you can replace ``/path/to/include-what-you-use/share/libcxx.imp``
-file with the libc++-provided ``libcxx.imp`` file.
 
 Libc++ Configuration Macros
 ===========================
 
-Libc++ provides a number of configuration macros which can be used to enable
-or disable extended libc++ behavior, including enabling hardening or thread
-safety annotations.
+Libc++ provides a number of configuration macros that can be used by developers to
+enable or disable extended libc++ behavior.
+
+.. warning::
+  Configuration macros that are not documented here are not intended to be customized
+  by developers and should not be used. In particular, some configuration macros are
+  only intended to be used by vendors and changing their value from the one provided
+  in your toolchain can lead to unexpected behavior.
 
 **_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS**:
   This macro is used to enable -Wthread-safety annotations on libc++'s
@@ -193,6 +135,12 @@ safety annotations.
   warning saying that `std::auto_ptr` is deprecated. If the macro is defined,
   no warning will be emitted. By default, this macro is not defined.
 
+**_LIBCPP_ENABLE_EXPERIMENTAL**:
+  This macro enables experimental features. This can be used on compilers that do
+  not support the ``-fexperimental-library`` flag. When used, users also need to
+  ensure that the appropriate experimental library (usually ``libc++experimental.a``)
+  is linked into their program.
+
 C++17 Specific Configuration Macros
 -----------------------------------
 **_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**:
@@ -307,7 +255,7 @@ Extensions to the C++23 modules ``std`` and ``std.compat``
 ----------------------------------------------------------
 
 Like other major implementations, libc++ provides C++23 modules ``std`` and
-``std.compat`` in C++20 as an extension"
+``std.compat`` in C++20 as an extension.
 
 Constant-initialized std::string
 --------------------------------
@@ -386,3 +334,38 @@ specific locale is imbued, the IO with the underlying stream happens with
 regular ``char`` elements, which are converted to/from wide characters
 according to the locale. Note that this doesn't behave as expected if the
 stream has been set in Unicode mode.
+
+
+Third-party Integrations
+========================
+
+Libc++ provides integration with a few third-party tools.
+
+GDB Pretty printers for libc++
+------------------------------
+
+GDB does not support pretty-printing of libc++ symbols by default. However, libc++ does
+provide pretty-printers itself. Those can be used as:
+
+.. code-block:: bash
+
+  $ gdb -ex "source <libcxx>/utils/gdb/libcxx/printers.py" \
+        -ex "python register_libcxx_printer_loader()" \
+        <args>
+
+
+.. _include-what-you-use:
+
+include-what-you-use (IWYU)
+---------------------------
+
+libc++ provides an IWYU `mapping file <https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUMappings.md>`_,
+which drastically improves the accuracy of the tool when using libc++. To use the mapping file with
+IWYU, you should run the tool like so:
+
+.. code-block:: bash
+
+  $ include-what-you-use -Xiwyu --mapping_file=/path/to/libcxx/include/libcxx.imp file.cpp
+
+If you would prefer to not use that flag, then you can replace ``/path/to/include-what-you-use/share/libcxx.imp``
+file with the libc++-provided ``libcxx.imp`` file.
diff --git a/libcxx/docs/VendorDocumentation.rst b/libcxx/docs/VendorDocumentation.rst
diff --git a/libcxx/docs/index.rst b/libcxx/docs/index.rst
