Add documentation for new experimental library
git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@268456 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/docs/UsingLibcxx.rst b/docs/UsingLibcxx.rst
index 344eda5..5747201 100644
--- a/docs/UsingLibcxx.rst
+++ b/docs/UsingLibcxx.rst
@@ -49,7 +49,30 @@
$ 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
=====================