Update the docs for building libc++.

Summary:
Rewrite the in-tree build to be a clearer tl;dr like we have for the
out-of-tree build.

Reviewers: EricWF, mclow.lists, ldionne

Reviewed By: ldionne

Subscribers: dexonsmith, christof, ldionne, enh, libcxx-commits

Tags: #libc

Differential Revision: https://reviews.llvm.org/D69917

diff --git a/libcxx/docs/BuildingLibcxx.rst b/libcxx/docs/BuildingLibcxx.rst
index e6a21a9..f2fff0e 100644 (file)
--- a/libcxx/docs/BuildingLibcxx.rst
+++ b/libcxx/docs/BuildingLibcxx.rst
@@ -16,40 +16,44 @@ On Mac OS 10.7 (Lion) and later, the easiest way to get this library is to insta
 Xcode 4.2 or later.  However if you want to install tip-of-trunk from here
 (getting the bleeding edge), read on.
 
-The basic steps needed to build libc++ are:
+The following instructions describe how to checkout, build, test and
+(optionally) install libc++ and libc++abi.
 
-#. Checkout and configure LLVM (including libc++ and libc++abi), according to the `LLVM
-   getting started <https://llvm.org/docs/GettingStarted.html>`_ documentation. Make sure
-   to include ``libcxx`` and ``libcxxabi`` in the ``LLVM_ENABLE_PROJECTS`` option passed
-   to CMake.
+If your system already provides a libc++ installation it is important to be
+careful not to replace it. Remember Use the CMake option
+``CMAKE_INSTALL_PREFIX`` to select a safe place to install libc++.
 
-   For more information about configuring libc++ see :ref:`CMake Options`.
-
-   * ``make cxx`` --- will build libc++ and libc++abi.
-   * ``make check-cxx check-cxxabi`` --- will run the test suites.
-
-   Shared libraries for libc++ and libc++ abi should now be present in llvm/build/lib.
-   See :ref:`using an alternate libc++ installation <alternate libcxx>`
-
-#. **Optional**: Install libc++ and libc++abi
-
-   If your system already provides a libc++ installation it is important to be
-   careful not to replace it. Remember Use the CMake option ``CMAKE_INSTALL_PREFIX`` to
-   select a safe place to install libc++.
-
-   * ``make install-cxx install-cxxabi`` --- Will install the libraries and the headers
+.. warning::
+  * Replacing your systems libc++ installation could render the system non-functional.
+  * macOS will not boot without a valid copy of ``libc++.1.dylib`` in ``/usr/lib``.
 
-   .. warning::
-     * Replacing your systems libc++ installation could render the system non-functional.
-     * macOS will not boot without a valid copy of ``libc++.1.dylib`` in ``/usr/lib``.
+.. code-block:: bash
 
+  $ git clone https://github.com/llvm/llvm-project.git
+  $ cd llvm-project
+  $ mkdir build && cd build
+  $ cmake -DCMAKE_C_COMPILER=clang \
+          -DCMAKE_CXX_COMPILER=clang++ \
+          -DLLVM_ENABLE_PROJECTS="libcxx;libcxxabi" \
+          ../llvm
+  $ make # Build
+  $ make check-cxx # Test
+  $ make install-cxx install-cxxabi # Install
+
+For more information about configuring libc++ see :ref:`CMake Options`. You may
+also want to read the `LLVM getting started
+<https://llvm.org/docs/GettingStarted.html>`_ documentation.
+
+Shared libraries for libc++ and libc++ abi should now be present in
+``build/lib``.  See :ref:`using an alternate libc++ installation <alternate
+libcxx>` for information on how to use this libc++.
 
 The instructions are for building libc++ on
 FreeBSD, Linux, or Mac using `libc++abi`_ as the C++ ABI library.
 On Linux, it is also possible to use :ref:`libsupc++ <libsupcxx>` or libcxxrt.
 
-It is sometimes beneficial to build separately from the full LLVM build. An
-out-of-tree build would look like this:
+It is possible to keep your LLVM and libc++ trees separate so you can avoid
+rebuilding LLVM as often. An out-of-tree build would look like this:
 
 .. code-block:: bash