Import libc++ 3.9.0

1 files changed, 185 insertions, 0 deletions

diff --git a/lib/libcxx/docs/index.rst b/lib/libcxx/docs/index.rst
new file mode 100644
index 00000000000..b0c8b813f57
--- /dev/null
+++ b/lib/libcxx/docs/index.rst
@@ -0,0 +1,185 @@
+.. _index:
+
+=============================
+"libc++" C++ Standard Library
+=============================
+
+Overview
+========
+
+libc++ is a new implementation of the C++ standard library, targeting C++11.
+
+* Features and Goals
+
+  * Correctness as defined by the C++11 standard.
+  * Fast execution.
+  * Minimal memory use.
+  * Fast compile times.
+  * ABI compatibility with gcc's libstdc++ for some low-level features
+    such as exception objects, rtti and memory allocation.
+  * Extensive unit tests.
+
+* 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: 2
+
+   UsingLibcxx
+   BuildingLibcxx
+   TestingLibcxx
+
+
+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
+  the standard containers which require ABI breakage and fundamental changes
+  to how they are implemented.  For example, it is generally accepted that
+  building std::string using the "short string optimization" instead of
+  using Copy On Write (COW) is a superior approach for multicore
+  machines (particularly in C++11, which has rvalue references).  Breaking
+  ABI compatibility with old versions of the library was
+  determined to be critical to achieving the performance goals of
+  libc++.
+
+* Mainline libstdc++ has switched to GPL3, a license which the developers
+  of libc++ cannot use.  libstdc++ 4.2 (the last GPL2 version) could be
+  independently extended to support C++11, but this would be a fork of the
+  codebase (which is often seen as worse for a project than starting a new
+  independent one).  Another problem with libstdc++ is that it is tightly
+  integrated with G++ development, tending to be tied fairly closely to the
+  matching version of G++.
+
+* STLport and the Apache libstdcxx library are two other popular
+  candidates, but both lack C++11 support.  Our experience (and the
+  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
+-----------------------------
+
+libc++ is known to work on the following platforms, using gcc-4.2 and
+clang  (lack of C++11 language support disables some functionality).
+Note that functionality provided by ``<atomic>`` is only functional with clang
+and GCC.
+
+============ ==================== ============ ========================
+OS           Arch                 Compilers    ABI Library
+============ ==================== ============ ========================
+Mac OS X     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 strongly recommended.
+
+* Clang 3.5 and above
+* GCC 4.7 and above.
+
+Anything older *may* work.
+
+C++ Dialect Support
+---------------------
+
+* C++11 - Complete
+* `C++14 - Complete <http://libcxx.llvm.org/cxx1y_status.html>`__
+* `C++1z - In Progress <http://libcxx.llvm.org/cxx1z_status.html>`__
+* `Post C++14 Technical Specifications - In Progress <http://libcxx.llvm.org/ts1z_status.html>`__
+
+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.
+* On OS X v10.8 and older the CMake option ``-DLIBCXX_LIBCPPABI_VERSION=""``
+  must be used during configuration.
+
+
+A full list of currently open libc++ bugs can be `found here`__.
+
+.. __:  https://llvm.org/bugs/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/CapturingConfigInfo
+   DesignDocs/ABIVersioning
+
+
+* `<atomic> design <http://libcxx.llvm.org/atomic_design.html>`_
+* `<type_traits> design <http://libcxx.llvm.org/type_traits_design.html>`_
+* `Status of debug mode <http://libcxx.llvm.org/debug_mode.html>`_
+* `Notes by Marshall Clow`__
+
+.. __: https://cplusplusmusings.wordpress.com/2012/07/05/clang-and-standard-libraries-on-mac-os-x/
+
+Build Bots and Test Coverage
+----------------------------
+
+* `LLVM Buildbot Builders <http://lab.llvm.org:8011/console>`_
+* `Apple Jenkins Builders <http://lab.llvm.org:8080/green/view/Libcxx/>`_
+* `EricWF's Nightly Builders <http://ds2.efcs.ca:8080/console>`_
+* `Code Coverage Results <http://efcs.ca/libcxx-coverage>`_
+
+Getting Involved
+================
+
+First please review our `Developer's Policy <http://llvm.org/docs/DeveloperPolicy.html>`__
+and `Getting started with LLVM <http://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 `cfe-dev mailing list`_ or on IRC.
+Please include "libc++" in your subject.
+
+**Patches**
+
+If you want to contribute a patch to libc++, the best place for that is
+`Phabricator <http://llvm.org/docs/Phabricator.html>`_. Please include [libcxx] in the subject and
+add `cfe-commits` as a subscriber. Also make sure you are subscribed to the
+`cfe-commits mailing list <http://lists.llvm.org/mailman/listinfo/cfe-commits>`_.
+
+**Discussion and Questions**
+
+Send discussions and questions to the
+`cfe-dev mailing list <http://lists.llvm.org/mailman/listinfo/cfe-dev>`_.
+Please include [libcxx] in the subject.
+
+
+
+Quick Links
+===========
+* `LLVM Homepage <http://llvm.org/>`_
+* `libc++abi Homepage <http://libcxxabi.llvm.org/>`_
+* `LLVM Bugzilla <http://llvm.org/bugs/>`_
+* `cfe-commits Mailing List`_
+* `cfe-dev Mailing List`_
+* `Browse libc++ -- SVN <http://llvm.org/svn/llvm-project/libcxx/trunk/>`_
+* `Browse libc++ -- ViewVC <http://llvm.org/viewvc/llvm-project/libcxx/trunk/>`_