Add documentation for new experimental library

git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@268456 91177308-0d34-0410-b5e6-96231b3b80d8

docs/BuildingLibcxx.rst

@@ -6,6 +6,8 @@ Building libc++
 .. contents::
   :local:
 
+.. _build instructions:
+
 Getting Started
 ===============
 
@@ -119,6 +121,18 @@ CMake docs or execute ``cmake --help-variable VARIABLE_NAME``.
 libc++ specific options
 -----------------------
 
+.. option:: LIBCXX_INSTALL_LIBRARY:BOOL
+
+  **Default**: ``ON``
+
+  Toggle the installation of the library portion of libc++.
+
+.. option:: LIBCXX_INSTALL_HEADERS:BOOL
+
+  **Default**: ``ON``
+
+  Toggle the installation of the libc++ headers.
+
 .. option:: LIBCXX_ENABLE_ASSERTIONS:BOOL
 
   **Default**: ``ON``
@@ -143,6 +157,25 @@ libc++ specific options
   Extra suffix to append to the directory where libraries are to be installed.
   This option overrides :option:`LLVM_LIBDIR_SUFFIX`.
 
+
+.. _libc++experimental options:
+
+libc++experimental Specific Options
+------------------------------------
+
+.. option:: LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY:BOOL
+
+  **Default**: ``ON``
+
+  Build and test libc++experimental.a.
+
+.. option:: LIBCXX_INSTALL_EXPERIMENTAL_LIBRARY:BOOL
+
+  **Default**: ``OFF``
+
+  Install libc++experimental.a alongside libc++.
+
+
 .. _ABI Library Specific Options:
 
 ABI Library Specific Options

docs/UsingLibcxx.rst

@@ -49,7 +49,30 @@ An example of using ``LD_LIBRARY_PATH``:
   $ export LD_LIBRARY_PATH=<libcxx-install-prefix>/lib
   $ ./a.out # Searches for libc++ along LD_LIBRARY_PATH
 
+Using libc++experimental and ``<experimental/...>``
+=====================================================
 
+Libc++ provides implementations of experimental technical specifications
+in a separate library, ``libc++experimental.a``. Users of ``<experimental/...>``
+headers may requiring linking with ``-lc++experimental``.
+
+.. code-block:: bash
+
+  $ clang++ -std=c++14 -stdlib=libc++ test.cpp -lc++experimental
+
+Libc++experimental.a may not always be available, even when libc++ is already
+installed. For information on building libc++experimental from source see
+:ref:`Building Libc++ <build instructions>` and
+:ref:`libc++experimental CMake Options <libc++experimental options>`.
+
+Also see the `Experimental Library Implementation Status <http://libcxx.llvm.org/ts1z_status.html>`__
+page.
+
+.. warning::
+  Experimental libraries are Experimental.
+    * The contents of the ``<experimental/...>`` headers and ``libc++experimental.a``
+      library will not remain compatible between versions.
+    * No guarantees of API or ABI stability are provided.
 
 Using libc++ on Linux
 =====================