Imported Upstream version 6.10.0.49

Former-commit-id: 1d6753294b2993e1fbf92de9366bb9544db4189b

external/llvm-project/libcxx/docs/CMakeLists.txt

@@ -0,0 +1,9 @@
+
+if (LLVM_ENABLE_SPHINX)
+  include(AddSphinxTarget)
+  if (SPHINX_FOUND)
+    if (${SPHINX_OUTPUT_HTML})
+      add_sphinx_target(html libcxx)
+    endif()
+  endif()
+endif()

external/llvm-project/libcxx/docs/DesignDocs/ABIVersioning.rst

@@ -0,0 +1,17 @@
+
+====================
+Libc++ ABI stability
+====================
+
+Libc++ aims to preserve stable ABI to avoid subtle bugs when code built to the old ABI
+is linked with the code build to the new ABI. At the same time, libc++ allows ABI-breaking
+improvements and bugfixes for the scenarios when ABI change is not a issue.
+
+To support both cases, libc++ allows specifying the ABI version at the
+build time.  The version is defined with a cmake option
+LIBCXX_ABI_VERSION. Another option LIBCXX_ABI_UNSTABLE can be used to
+include all present ABI breaking features. These options translate
+into C++ macro definitions _LIBCPP_ABI_VERSION, _LIBCPP_ABI_UNSTABLE.
+
+Any ABI-changing feature is placed under it's own macro, _LIBCPP_ABI_XXX, which is enabled
+based on the value of _LIBCPP_ABI_VERSION. _LIBCPP_ABI_UNSTABLE, if set, enables all features at once.

external/llvm-project/libcxx/docs/DesignDocs/AvailabilityMarkup.rst

@@ -0,0 +1,114 @@
+===================
+Availability Markup
+===================
+
+.. contents::
+   :local:
+
+Overview
+========
+
+Libc++ is used as a system library on macOS and iOS (amongst others). In order
+for users to be able to compile a binary that is intended to be deployed to an
+older version of the platform, clang provides the
+`availability attribute <https://clang.llvm.org/docs/AttributeReference.html#availability>`_
+that can be placed on declarations to describe the lifecycle of a symbol in the
+library.
+
+Design
+======
+
+When a new feature is introduced that requires dylib support, a macro should be
+created in include/__config to mark this feature as unavailable for all the
+systems. For example::
+
+    // Define availability macros.
+    #if defined(_LIBCPP_USE_AVAILABILITY_APPLE)
+    #define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((unavailable))
+    #else  if defined(_LIBCPP_USE_AVAILABILITY_SOME_OTHER_VENDOR)
+    #define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((unavailable))
+	#else
+    #define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS
+    #endif
+
+When the library is updated by the platform vendor, the markup can be updated.
+For example::
+
+    #define _LIBCPP_AVAILABILITY_SHARED_MUTEX                                  \
+      __attribute__((availability(macosx,strict,introduced=10.12)))            \
+      __attribute__((availability(ios,strict,introduced=10.0)))                \
+      __attribute__((availability(tvos,strict,introduced=10.0)))               \
+      __attribute__((availability(watchos,strict,introduced=3.0)))
+
+In the source code, the macro can be added on a class if the full class requires
+type info from the library for example::
+
+	_LIBCPP_BEGIN_NAMESPACE_EXPERIMENTAL
+	class _LIBCPP_EXCEPTION_ABI _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS bad_optional_access
+	    : public std::logic_error {
+
+or on a particular symbol:
+
+    _LIBCPP_OVERRIDABLE_FUNC_VIS _LIBCPP_AVAILABILITY_SIZED_NEW_DELETE void  operator delete(void* __p, std::size_t __sz) _NOEXCEPT;
+
+
+Testing
+=======
+
+Some parameters can be passed to lit to run the test-suite and exercising the
+availability.
+
+* The `platform` parameter controls the deployement target. For example lit can
+  be invoked with `--param=platform=macosx10.8`. Default is the current host.
+* The `use_system_cxx_lib` parameter indicates to use another library than the
+  just built one. Invoking lit with `--param=use_system_cxx_lib=true` will run
+  the test-suite against the host system library. Alternatively a path to the
+  directory containing a specific prebuilt libc++ can be used, for example:
+  `--param=use_system_cxx_lib=/path/to/macOS/10.8/`.
+* The `with_availability` boolean parameter enables the availability markup.
+
+Tests can be marked as XFAIL based on multiple features made available by lit:
+
+
+* if either `use_system_cxx_lib` or  `with_availability` is passed to lit,
+  assuming `--param=platform=macosx10.8` is passed as well the following
+  features will be available:
+
+  - availability
+  - availability=x86_64
+  - availability=macosx
+  - availability=x86_64-macosx
+  - availability=x86_64-apple-macosx10.8
+  - availability=macosx10.8
+
+  This feature is used to XFAIL a test that *is* using a class of a method marked
+  as unavailable *and* that is expected to *fail* if deployed on an older system.
+
+* if `use_system_cxx_lib` is passed to lit, the following features will also
+  be available:
+
+  - with_system_cxx_lib
+  - with_system_cxx_lib=x86_64
+  - with_system_cxx_lib=macosx
+  - with_system_cxx_lib=x86_64-macosx
+  - with_system_cxx_lib=x86_64-apple-macosx10.8
+  - with_system_cxx_lib=macosx10.8
+
+  This feature is used to XFAIL a test that is *not* using a class of a method
+  marked as unavailable *but* that is expected to fail if deployed on an older
+  system. For example if we know that it exhibits a but in the libc on a
+  particular system version.
+
+* if `with_availability` is passed to lit, the following features will also
+  be available:
+
+  - availability_markup
+  - availability_markup=x86_64
+  - availability_markup=macosx
+  - availability_markup=x86_64-macosx
+  - availability_markup=x86_64-apple-macosx10.8
+  - availability_markup=macosx10.8
+
+  This feature is used to XFAIL a test that *is* using a class of a method
+  marked as unavailable *but* that is expected to *pass* if deployed on an older
+  system. For example if it is using a symbol in a statically evaluated context.

external/llvm-project/libcxx/docs/DesignDocs/CapturingConfigInfo.rst

@@ -0,0 +1,88 @@
+=======================================================
+Capturing configuration information during installation
+=======================================================
+
+.. contents::
+   :local:
+
+The Problem
+===========
+
+Currently the libc++ supports building the library with a number of different
+configuration options.  Unfortunately all of that configuration information is
+lost when libc++ is installed. In order to support "persistent"
+configurations libc++ needs a mechanism to capture the configuration options
+in the INSTALLED headers.
+
+
+Design Goals
+============
+
+* The solution should not INSTALL any additional headers. We don't want an extra
+  #include slowing everybody down.
+
+* The solution should not unduly affect libc++ developers. The problem is limited
+  to installed versions of libc++ and the solution should be as well.
+
+* The solution should not modify any existing headers EXCEPT during installation.
+  It makes developers lives harder if they have to regenerate the libc++ headers
+  every time they are modified.
+
+* The solution should not make any of the libc++ headers dependant on
+  files generated by the build system. The headers should be able to compile
+  out of the box without any modification.
+
+* The solution should not have ANY effect on users who don't need special
+  configuration options. The vast majority of users will never need this so it
+  shouldn't cost them.
+
+
+The Solution
+============
+
+When you first configure libc++ using CMake we check to see if we need to
+capture any options. If we haven't been given any "persistent" options then
+we do NOTHING.
+
+Otherwise we create a custom installation rule that modifies the installed __config
+header. The rule first generates a dummy "__config_site" header containing the required
+#defines. The contents of the dummy header are then prependend to the installed
+__config header. By manually prepending the files we avoid the cost of an
+extra #include and we allow the __config header to be ignorant of the extra
+configuration all together. An example "__config" header generated when
+-DLIBCXX_ENABLE_THREADS=OFF is given to CMake would look something like:
+
+.. code-block:: cpp
+
+  //===----------------------------------------------------------------------===//
+  //
+  //                     The LLVM Compiler Infrastructure
+  //
+  // This file is dual licensed under the MIT and the University of Illinois Open
+  // Source Licenses. See LICENSE.TXT for details.
+  //
+  //===----------------------------------------------------------------------===//
+
+  #ifndef _LIBCPP_CONFIG_SITE
+  #define _LIBCPP_CONFIG_SITE
+
+  /* #undef _LIBCPP_HAS_NO_GLOBAL_FILESYSTEM_NAMESPACE */
+  /* #undef _LIBCPP_HAS_NO_STDIN */
+  /* #undef _LIBCPP_HAS_NO_STDOUT */
+  #define _LIBCPP_HAS_NO_THREADS
+  /* #undef _LIBCPP_HAS_NO_MONOTONIC_CLOCK */
+  /* #undef _LIBCPP_HAS_NO_THREAD_UNSAFE_C_FUNCTIONS */
+
+  #endif
+  // -*- C++ -*-
+  //===--------------------------- __config ---------------------------------===//
+  //
+  //                     The LLVM Compiler Infrastructure
+  //
+  // This file is dual licensed under the MIT and the University of Illinois Open
+  // Source Licenses. See LICENSE.TXT for details.
+  //
+  //===----------------------------------------------------------------------===//
+
+  #ifndef _LIBCPP_CONFIG
+  #define _LIBCPP_CONFIG

external/llvm-project/libcxx/docs/DesignDocs/DebugMode.rst

@@ -0,0 +1,100 @@
+==========
+Debug Mode
+==========
+
+.. contents::
+   :local:
+
+.. _using-debug-mode:
+
+Using Debug Mode
+================
+
+Libc++ provides a debug mode that enables assertions meant to detect incorrect
+usage of the standard library. By default these assertions are disabled but
+they can be enabled using the ``_LIBCPP_DEBUG`` macro.
+
+**_LIBCPP_DEBUG** Macro
+-----------------------
+
+**_LIBCPP_DEBUG**:
+  This macro is used to enable assertions and iterator debugging checks within
+  libc++. By default it is undefined.
+
+  **Values**: ``0``, ``1``
+
+  Defining ``_LIBCPP_DEBUG`` to ``0`` or greater enables most of libc++'s
+  assertions. Defining ``_LIBCPP_DEBUG`` to ``1`` enables "iterator debugging"
+  which provides additional assertions about the validity of iterators used by
+  the program.
+
+  Note that this option has no effect on libc++'s ABI
+
+**_LIBCPP_DEBUG_USE_EXCEPTIONS**:
+  When this macro is defined ``_LIBCPP_ASSERT`` failures throw
+  ``__libcpp_debug_exception`` instead of aborting. Additionally this macro
+  disables exception specifications on functions containing ``_LIBCPP_ASSERT``
+  checks. This allows assertion failures to correctly throw through these
+  functions.
+
+Handling Assertion Failures
+---------------------------
+
+When a debug assertion fails the assertion handler is called via the
+``std::__libcpp_debug_function`` function pointer. It is possible to override
+this function pointer using a different handler function. Libc++ provides two
+different assertion handlers, the default handler
+``std::__libcpp_abort_debug_handler`` which aborts the program, and
+``std::__libcpp_throw_debug_handler`` which throws an instance of
+``std::__libcpp_debug_exception``. Libc++ can be changed to use the throwing
+assertion handler as follows:
+
+.. code-block:: cpp
+
+  #define _LIBCPP_DEBUG 1
+  #include <string>
+  int main() {
+    std::__libcpp_debug_function = std::__libcpp_throw_debug_function;
+    try {
+      std::string::iterator bad_it;
+      std::string str("hello world");
+      str.insert(bad_it, '!'); // causes debug assertion
+    } catch (std::__libcpp_debug_exception const&) {
+      return EXIT_SUCCESS;
+    }
+    return EXIT_FAILURE;
+  }
+
+Debug Mode Checks
+=================
+
+Libc++'s debug mode offers two levels of checking. The first enables various
+precondition checks throughout libc++. The second additionally enables
+"iterator debugging" which checks the validity of iterators used by the program.
+
+Basic Checks
+============
+
+These checks are enabled when ``_LIBCPP_DEBUG`` is defined to either 0 or 1.
+
+The following checks are enabled by ``_LIBCPP_DEBUG``:
+
+  * FIXME: Update this list
+
+Iterator Debugging Checks
+=========================
+
+These checks are enabled when ``_LIBCPP_DEBUG`` is defined to 1.
+
+The following containers and STL classes support iterator debugging:
+
+  * ``std::string``
+  * ``std::vector<T>`` (``T != bool``)
+  * ``std::list``
+  * ``std::unordered_map``
+  * ``std::unordered_multimap``
+  * ``std::unordered_set``
+  * ``std::unordered_multiset``
+
+The remaining containers do not currently support iterator debugging.
+Patches welcome.

external/llvm-project/libcxx/docs/DesignDocs/ThreadingSupportAPI.rst

@@ -0,0 +1,79 @@
+=====================
+Threading Support API
+=====================
+
+.. contents::
+   :local:
+
+Overview
+========
+
+Libc++ supports using multiple different threading models and configurations
+to implement the threading parts of libc++, including ``<thread>`` and ``<mutex>``.
+These different models provide entirely different interfaces from each
+other. To address this libc++ wraps the underlying threading API in a new and
+consistent API, which it uses internally to implement threading primitives.
+
+The ``<__threading_support>`` header is where libc++ defines its internal
+threading interface. It contains forward declarations of the internal threading
+interface as well as definitions for the interface.
+
+External Threading API and the ``<__external_threading>`` header
+================================================================
+
+In order to support vendors with custom threading API's libc++ allows the
+entire internal threading interface to be provided by an external,
+vendor provided, header.
+
+When ``_LIBCPP_HAS_THREAD_API_EXTERNAL`` is defined the ``<__threading_support>``
+header simply forwards to the ``<__external_threading>`` header (which must exist).
+It is expected that the ``<__external_threading>`` header provide the exact
+interface normally provided by ``<__threading_support>``.
+
+External Threading Library
+==========================
+
+libc++ can be compiled with its internal threading API delegating to an external
+library. Such a configuration is useful for library vendors who wish to
+distribute a thread-agnostic libc++ library, where the users of the library are
+expected to provide the implementation of the libc++ internal threading API.
+
+On a production setting, this would be achieved through a custom
+``<__external_threading>`` header, which declares the libc++ internal threading
+API but leaves out the implementation.
+
+The ``-DLIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY`` option allows building libc++ in
+such a configuration while allowing it to be tested on a platform that supports
+any of the threading systems (e.g. pthread) supported in ``__threading_support``
+header. Therefore, the main purpose of this option is to allow testing of this
+particular configuration of the library without being tied to a vendor-specific
+threading system. This option is only meant to be used by libc++ library
+developers.
+
+Threading Configuration Macros
+==============================
+
+**_LIBCPP_HAS_NO_THREADS**
+  This macro is defined when libc++ is built without threading support. It
+  should not be manually defined by the user.
+
+**_LIBCPP_HAS_THREAD_API_EXTERNAL**
+  This macro is defined when libc++ should use the ``<__external_threading>``
+  header to provide the internal threading API. This macro overrides
+  ``_LIBCPP_HAS_THREAD_API_PTHREAD``.
+
+**_LIBCPP_HAS_THREAD_API_PTHREAD**
+  This macro is defined when libc++ should use POSIX threads to implement the
+  internal threading API.
+
+**_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL**
+  This macro is defined when libc++ expects the definitions of the internal
+  threading API to be provided by an external library. When defined
+  ``<__threading_support>`` will only provide the forward declarations and
+  typedefs for the internal threading API.
+
+**_LIBCPP_BUILDING_THREAD_LIBRARY_EXTERNAL**
+  This macro is used to build an external threading library using the
+  ``<__threading_support>``. Specifically it exposes the threading API
+  definitions in ``<__threading_support>`` as non-inline definitions meant to
+  be compiled into a library.

external/llvm-project/libcxx/docs/DesignDocs/VisibilityMacros.rst

@@ -0,0 +1,163 @@
+========================
+Symbol Visibility Macros
+========================
+
+.. contents::
+   :local:
+
+Overview
+========
+
+Libc++ uses various "visibility" macros in order to provide a stable ABI in
+both the library and the headers. These macros work by changing the
+visibility and inlining characteristics of the symbols they are applied to.
+
+Visibility Macros
+=================
+
+**_LIBCPP_HIDDEN**
+  Mark a symbol as hidden so it will not be exported from shared libraries.
+
+**_LIBCPP_FUNC_VIS**
+  Mark a symbol as being exported by the libc++ library. This attribute must
+  be applied to the declaration of all functions exported by the libc++ dylib.
+
+**_LIBCPP_EXTERN_VIS**
+  Mark a symbol as being exported by the libc++ library. This attribute may
+  only be applied to objects defined in the libc++ library. On Windows this
+  macro applies `dllimport`/`dllexport` to the symbol. On all other platforms
+  this macro has no effect.
+
+**_LIBCPP_OVERRIDABLE_FUNC_VIS**
+  Mark a symbol as being exported by the libc++ library, but allow it to be
+  overridden locally. On non-Windows, this is equivalent to `_LIBCPP_FUNC_VIS`.
+  This macro is applied to all `operator new` and `operator delete` overloads.
+
+  **Windows Behavior**: Any symbol marked `dllimport` cannot be overridden
+  locally, since `dllimport` indicates the symbol should be bound to a separate
+  DLL. All `operator new` and `operator delete` overloads are required to be
+  locally overridable, and therefore must not be marked `dllimport`. On Windows,
+  this macro therefore expands to `__declspec(dllexport)` when building the
+  library and has an empty definition otherwise.
+
+**_LIBCPP_INLINE_VISIBILITY**
+  Mark a function as hidden and force inlining whenever possible.
+
+**_LIBCPP_ALWAYS_INLINE**
+  A synonym for `_LIBCPP_INLINE_VISIBILITY`
+
+**_LIBCPP_TYPE_VIS**
+  Mark a type's typeinfo, vtable and members as having default visibility.
+  This attribute cannot be used on class templates.
+
+**_LIBCPP_TEMPLATE_VIS**
+  Mark a type's typeinfo and vtable as having default visibility.
+  This macro has no effect on the visibility of the type's member functions.
+
+  **GCC Behavior**: GCC does not support Clang's `type_visibility(...)`
+  attribute. With GCC the `visibility(...)` attribute is used and member
+  functions are affected.
+
+  **Windows Behavior**: DLLs do not support dllimport/export on class templates.
+  The macro has an empty definition on this platform.
+
+
+**_LIBCPP_ENUM_VIS**
+  Mark the typeinfo of an enum as having default visibility. This attribute
+  should be applied to all enum declarations.
+
+  **Windows Behavior**: DLLs do not support importing or exporting enumeration
+  typeinfo. The macro has an empty definition on this platform.
+
+  **GCC Behavior**: GCC un-hides the typeinfo for enumerations by default, even
+  if `-fvisibility=hidden` is specified. Additionally applying a visibility
+  attribute to an enum class results in a warning. The macro has an empty
+  definition with GCC.
+
+**_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS**
+  Mark the member functions, typeinfo, and vtable of the type named in
+  a `_LIBCPP_EXTERN_TEMPLATE` declaration as being exported by the libc++ library.
+  This attribute must be specified on all extern class template declarations.
+
+  This macro is used to override the `_LIBCPP_TEMPLATE_VIS` attribute
+  specified on the primary template and to export the member functions produced
+  by the explicit instantiation in the dylib.
+
+  **GCC Behavior**: GCC ignores visibility attributes applied the type in
+  extern template declarations and applying an attribute results in a warning.
+  However since `_LIBCPP_TEMPLATE_VIS` is the same as
+  `__attribute__((visibility("default"))` the visibility is already correct.
+  The macro has an empty definition with GCC.
+
+  **Windows Behavior**: `extern template` and `dllexport` are fundamentally
+  incompatible *on a class template* on Windows; the former suppresses
+  instantiation, while the latter forces it. Specifying both on the same
+  declaration makes the class template be instantiated, which is not desirable
+  inside headers. This macro therefore expands to `dllimport` outside of libc++
+  but nothing inside of it (rather than expanding to `dllexport`); instead, the
+  explicit instantiations themselves are marked as exported. Note that this
+  applies *only* to extern *class* templates. Extern *function* templates obey
+  regular import/export semantics, and applying `dllexport` directly to the
+  extern template declaration (i.e. using `_LIBCPP_FUNC_VIS`) is the correct
+  thing to do for them.
+
+**_LIBCPP_CLASS_TEMPLATE_INSTANTIATION_VIS**
+  Mark the member functions, typeinfo, and vtable of an explicit instantiation
+  of a class template as being exported by the libc++ library. This attribute
+  must be specified on all class template explicit instantiations.
+
+  It is only necessary to mark the explicit instantiation itself (as opposed to
+  the extern template declaration) as exported on Windows, as discussed above.
+  On all other platforms, this macro has an empty definition.
+
+**_LIBCPP_METHOD_TEMPLATE_IMPLICIT_INSTANTIATION_VIS**
+  Mark a symbol as hidden so it will not be exported from shared libraries. This
+  is intended specifically for method templates of either classes marked with
+  `_LIBCPP_TYPE_VIS` or classes with an extern template instantiation
+  declaration marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS`.
+
+  When building libc++ with hidden visibility, we want explicit template
+  instantiations to export members, which is consistent with existing Windows
+  behavior. We also want classes annotated with `_LIBCPP_TYPE_VIS` to export
+  their members, which is again consistent with existing Windows behavior.
+  Both these changes are necessary for clients to be able to link against a
+  libc++ DSO built with hidden visibility without encountering missing symbols.
+
+  An unfortunate side effect, however, is that method templates of classes
+  either marked `_LIBCPP_TYPE_VIS` or with extern template instantiation
+  declarations marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` also get default
+  visibility when instantiated. These methods are often implicitly instantiated
+  inside other libraries which use the libc++ headers, and will therefore end up
+  being exported from those libraries, since those implicit instantiations will
+  receive default visibility. This is not acceptable for libraries that wish to
+  control their visibility, and led to PR30642.
+
+  Consequently, all such problematic method templates are explicitly marked
+  either hidden (via this macro) or inline, so that they don't leak into client
+  libraries. The problematic methods were found by running
+  `bad-visibility-finder <https://github.com/smeenai/bad-visibility-finder>`_
+  against the libc++ headers after making `_LIBCPP_TYPE_VIS` and
+  `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` expand to default visibility.
+
+**_LIBCPP_EXTERN_TEMPLATE_INLINE_VISIBILITY**
+  Mark a member function of a class template as visible and always inline. This
+  macro should only be applied to member functions of class templates that are
+  externally instantiated. It is important that these symbols are not marked
+  as hidden as that will prevent the dylib definition from being found.
+
+  This macro is used to maintain ABI compatibility for symbols that have been
+  historically exported by the libc++ library but are now marked inline.
+
+**_LIBCPP_EXCEPTION_ABI**
+  Mark the member functions, typeinfo, and vtable of the type as being exported
+  by the libc++ library. This macro must be applied to all *exception types*.
+  Exception types should be defined directly in namespace `std` and not the
+  versioning namespace. This allows throwing and catching some exception types
+  between libc++ and libstdc++.
+
+Links
+=====
+
+* `[cfe-dev] Visibility in libc++ - 1 <http://lists.llvm.org/pipermail/cfe-dev/2013-July/030610.html>`_
+* `[cfe-dev] Visibility in libc++ - 2 <http://lists.llvm.org/pipermail/cfe-dev/2013-August/031195.html>`_
+* `[libcxx] Visibility fixes for Windows <http://lists.llvm.org/pipermail/cfe-commits/Week-of-Mon-20130805/085461.html>`_

external/llvm-project/libcxx/docs/Makefile.sphinx

@@ -0,0 +1,37 @@
+# Makefile for Sphinx documentation
+#
+# FIXME: This hack is only in place to allow the libcxx.llvm.org/docs builder
+# to work with libcxx. This should be removed when that builder supports
+# out-of-tree builds.
+
+# You can set these variables from the command line.
+SPHINXOPTS    = -n -W
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext default
+
+default: html
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@# FIXME: Remove this `cp` once HTML->Sphinx transition is completed.
+	@# Kind of a hack, but HTML-formatted docs are on the way out anyway.
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+

external/llvm-project/libcxx/docs/README.txt

@@ -0,0 +1,13 @@
+libc++ Documentation
+====================
+
+The libc++ documentation is written using the Sphinx documentation generator. It is
+currently tested with Sphinx 1.1.3.
+
+To build the documents into html configure libc++ with the following cmake options:
+
+  * -DLLVM_ENABLE_SPHINX=ON
+  * -DLIBCXX_INCLUDE_DOCS=ON
+
+After configuring libc++ with these options the make rule `docs-libcxx-html`
+should be available.

external/llvm-project/libcxx/docs/TestingLibcxx.rst

@@ -0,0 +1,266 @@
+==============
+Testing libc++
+==============
+
+.. contents::
+  :local:
+
+Getting Started
+===============
+
+libc++ uses LIT to configure and run its tests. The primary way to run the
+libc++ tests is by using make check-libcxx. However since libc++ can be used
+in any number of possible configurations it is important to customize the way
+LIT builds and runs the tests. This guide provides information on how to use
+LIT directly to test libc++.
+
+Please see the `Lit Command Guide`_ for more information about LIT.
+
+.. _LIT Command Guide: http://llvm.org/docs/CommandGuide/lit.html
+
+Setting up the Environment
+--------------------------
+
+After building libc++ you must setup your environment to test libc++ using
+LIT.
+
+#. Create a shortcut to the actual lit executable so that you can invoke it
+   easily from the command line.
+
+   .. code-block:: bash
+
+     $ alias lit='python path/to/llvm/utils/lit/lit.py'
+
+#. Tell LIT where to find your build configuration.
+
+   .. code-block:: bash
+
+     $ export LIBCXX_SITE_CONFIG=path/to/build-libcxx/test/lit.site.cfg
+
+Example Usage
+-------------
+
+Once you have your environment set up and you have built libc++ you can run
+parts of the libc++ test suite by simply running `lit` on a specified test or
+directory. For example:
+
+.. code-block:: bash
+
+  $ cd path/to/src/libcxx
+  $ lit -sv test/std/re # Run all of the std::regex tests
+  $ lit -sv test/std/depr/depr.c.headers/stdlib_h.pass.cpp # Run a single test
+  $ lit -sv test/std/atomics test/std/threads # Test std::thread and std::atomic
+
+Sometimes you'll want to change the way LIT is running the tests. Custom options
+can be specified using the `--param=<name>=<val>` flag. The most common option
+you'll want to change is the standard dialect (ie -std=c++XX). By default the
+test suite will select the newest C++ dialect supported by the compiler and use
+that. However if you want to manually specify the option like so:
+
+.. code-block:: bash
+
+  $ lit -sv test/std/containers # Run the tests with the newest -std
+  $ lit -sv --param=std=c++03 test/std/containers # Run the tests in C++03
+
+Occasionally you'll want to add extra compile or link flags when testing.
+You can do this as follows:
+
+.. code-block:: bash
+
+  $ lit -sv --param=compile_flags='-Wcustom-warning'
+  $ lit -sv --param=link_flags='-L/custom/library/path'
+
+Some other common examples include:
+
+.. code-block:: bash
+
+  # Specify a custom compiler.
+  $ lit -sv --param=cxx_under_test=/opt/bin/g++ test/std
+
+  # Enable warnings in the test suite
+  $ lit -sv --param=enable_warnings=true test/std
+
+  # Use UBSAN when running the tests.
+  $ lit -sv --param=use_sanitizer=Undefined
+
+
+LIT Options
+===========
+
+:program:`lit` [*options*...] [*filenames*...]
+
+Command Line Options
+--------------------
+
+To use these options you pass them on the LIT command line as --param NAME or
+--param NAME=VALUE. Some options have default values specified during CMake's
+configuration. Passing the option on the command line will override the default.
+
+.. program:: lit
+
+.. option:: cxx_under_test=<path/to/compiler>
+
+  Specify the compiler used to build the tests.
+
+.. option:: cxx_stdlib_under_test=<stdlib name>
+
+  **Values**: libc++, libstdc++
+
+  Specify the C++ standard library being tested. Unless otherwise specified
+  libc++ is used. This option is intended to allow running the libc++ test
+  suite against other standard library implementations.
+
+.. option:: std=<standard version>
+
+  **Values**: c++98, c++03, c++11, c++14, c++17, c++2a
+
+  Change the standard version used when building the tests.
+
+.. option:: libcxx_site_config=<path/to/lit.site.cfg>
+
+  Specify the site configuration to use when running the tests.  This option
+  overrides the environment variable LIBCXX_SITE_CONFIG.
+
+.. option:: cxx_headers=<path/to/headers>
+
+  Specify the c++ standard library headers that are tested. By default the
+  headers in the source tree are used.
+
+.. option:: cxx_library_root=<path/to/lib/>
+
+  Specify the directory of the libc++ library to be tested. By default the
+  library folder of the build directory is used. This option cannot be used
+  when use_system_cxx_lib is provided.
+
+
+.. option:: cxx_runtime_root=<path/to/lib/>
+
+  Specify the directory of the libc++ library to use at runtime. This directory
+  is not added to the linkers search path. This can be used to compile tests
+  against one version of libc++ and run them using another. The default value
+  for this option is `cxx_library_root`. This option cannot be used
+  when use_system_cxx_lib is provided.
+
+.. option:: use_system_cxx_lib=<bool>
+
+  **Default**: False
+
+  Enable or disable testing against the installed version of libc++ library.
+  Note: This does not use the installed headers.
+
+.. option:: use_lit_shell=<bool>
+
+  Enable or disable the use of LIT's internal shell in ShTests. If the
+  environment variable LIT_USE_INTERNAL_SHELL is present then that is used as
+  the default value. Otherwise the default value is True on Windows and False
+  on every other platform.
+
+.. option:: no_default_flags=<bool>
+
+  **Default**: False
+
+  Disable all default compile and link flags from being added. When this
+  option is used only flags specified using the compile_flags and link_flags
+  will be used.
+
+.. option:: compile_flags="<list-of-args>"
+
+  Specify additional compile flags as a space delimited string.
+  Note: This options should not be used to change the standard version used.
+
+.. option:: link_flags="<list-of-args>"
+
+  Specify additional link flags as a space delimited string.
+
+.. option:: debug_level=<level>
+
+  **Values**: 0, 1
+
+  Enable the use of debug mode. Level 0 enables assertions and level 1 enables
+  assertions and debugging of iterator misuse.
+
+.. option:: use_sanitizer=<sanitizer name>
+
+  **Values**: Memory, MemoryWithOrigins, Address, Undefined
+
+  Run the tests using the given sanitizer. If LLVM_USE_SANITIZER was given when
+  building libc++ then that sanitizer will be used by default.
+
+.. option:: color_diagnostics
+
+  Enable the use of colorized compile diagnostics. If the color_diagnostics
+  option is specified or the environment variable LIBCXX_COLOR_DIAGNOSTICS is
+  present then color diagnostics will be enabled.
+
+
+Environment Variables
+---------------------
+
+.. envvar:: LIBCXX_SITE_CONFIG=<path/to/lit.site.cfg>
+
+  Specify the site configuration to use when running the tests.
+  Also see `libcxx_site_config`.
+
+.. envvar:: LIBCXX_COLOR_DIAGNOSTICS
+
+  If ``LIBCXX_COLOR_DIAGNOSTICS`` is defined then the test suite will attempt
+  to use color diagnostic outputs from the compiler.
+  Also see `color_diagnostics`.
+
+Benchmarks
+==========
+
+Libc++ contains benchmark tests separately from the test of the test suite.
+The benchmarks are written using the `Google Benchmark`_ library, a copy of which
+is stored in the libc++ repository.
+
+For more information about using the Google Benchmark library see the
+`official documentation <https://github.com/google/benchmark>`_.
+
+.. _`Google Benchmark`: https://github.com/google/benchmark
+
+Building Benchmarks
+-------------------
+
+The benchmark tests are not built by default. The benchmarks can be built using
+the ``cxx-benchmarks`` target.
+
+An example build would look like:
+
+.. code-block:: bash
+
+  $ cd build
+  $ cmake [options] <path to libcxx sources>
+  $ make cxx-benchmarks
+
+This will build all of the benchmarks under ``<libcxx-src>/benchmarks`` to be
+built against the just-built libc++. The compiled tests are output into
+``build/benchmarks``.
+
+The benchmarks can also be built against the platforms native standard library
+using the ``-DLIBCXX_BUILD_BENCHMARKS_NATIVE_STDLIB=ON`` CMake option. This
+is useful for comparing the performance of libc++ to other standard libraries.
+The compiled benchmarks are named ``<test>.libcxx.out`` if they test libc++ and
+``<test>.native.out`` otherwise.
+
+Also See:
+
+  * :ref:`Building Libc++ <build instructions>`
+  * :ref:`CMake Options`
+
+Running Benchmarks
+------------------
+
+The benchmarks must be run manually by the user. Currently there is no way
+to run them as part of the build.
+
+For example:
+
+.. code-block:: bash
+
+  $ cd build/benchmarks
+  $ make cxx-benchmarks
+  $ ./algorithms.libcxx.out # Runs all the benchmarks
+  $ ./algorithms.libcxx.out --benchmark_filter=BM_Sort.* # Only runs the sort benchmarks
+
+For more information about running benchmarks see `Google Benchmark`_.

external/llvm-project/libcxx/docs/UsingLibcxx.rst

@@ -0,0 +1,219 @@
+============
+Using libc++
+============
+
+.. contents::
+  :local:
+
+Getting Started
+===============
+
+If you already have libc++ installed you can use it with clang.
+
+.. code-block:: bash
+
+    $ clang++ -stdlib=libc++ test.cpp
+    $ clang++ -std=c++11 -stdlib=libc++ test.cpp
+
+On OS X and FreeBSD libc++ is the default standard library
+and the ``-stdlib=libc++`` is not required.
+
+.. _alternate libcxx:
+
+If you want to select an alternate installation of libc++ you
+can use the following options.
+
+.. code-block:: bash
+
+  $ clang++ -std=c++11 -stdlib=libc++ -nostdinc++ \
+            -I<libcxx-install-prefix>/include/c++/v1 \
+            -L<libcxx-install-prefix>/lib \
+            -Wl,-rpath,<libcxx-install-prefix>/lib \
+            test.cpp
+
+The option ``-Wl,-rpath,<libcxx-install-prefix>/lib`` adds a runtime library
+search path. Meaning that the systems dynamic linker will look for libc++ in
+``<libcxx-install-prefix>/lib`` whenever the program is run. Alternatively the
+environment variable ``LD_LIBRARY_PATH`` (``DYLD_LIBRARY_PATH`` on OS X) can
+be used to change the dynamic linkers search paths after a program is compiled.
+
+An example of using ``LD_LIBRARY_PATH``:
+
+.. code-block:: bash
+
+  $ clang++ -stdlib=libc++ -nostdinc++ \
+            -I<libcxx-install-prefix>/include/c++/v1
+            -L<libcxx-install-prefix>/lib \
+            test.cpp -o
+  $ ./a.out # Searches for libc++ in the systems library paths.
+  $ 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 be required to link ``-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
+=====================
+
+On Linux libc++ can typically be used with only '-stdlib=libc++'. However
+some libc++ installations require the user manually link libc++abi themselves.
+If you are running into linker errors when using libc++ try adding '-lc++abi'
+to the link line.  For example:
+
+.. code-block:: bash
+
+  $ clang++ -stdlib=libc++ test.cpp -lc++ -lc++abi -lm -lc -lgcc_s -lgcc
+
+Alternately, you could just add libc++abi to your libraries list, which in
+most situations will give the same result:
+
+.. code-block:: bash
+
+  $ clang++ -stdlib=libc++ test.cpp -lc++abi
+
+
+Using libc++ with GCC
+---------------------
+
+GCC does not provide a way to switch from libstdc++ to libc++. You must manually
+configure the compile and link commands.
+
+In particular you must tell GCC to remove the libstdc++ include directories
+using ``-nostdinc++`` and to not link libstdc++.so using ``-nodefaultlibs``.
+
+Note that ``-nodefaultlibs`` removes all of the standard system libraries and
+not just libstdc++ so they must be manually linked. For example:
+
+.. code-block:: bash
+
+  $ g++ -nostdinc++ -I<libcxx-install-prefix>/include/c++/v1 \
+         test.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc
+
+
+GDB Pretty printers for libc++
+------------------------------
+
+GDB does not support pretty-printing of libc++ symbols by default. Unfortunately
+libc++ does not provide pretty-printers itself. However there are 3rd
+party implementations available and although they are not officially
+supported by libc++ they may be useful to users.
+
+Known 3rd Party Implementations Include:
+
+* `Koutheir's libc++ pretty-printers <https://github.com/koutheir/libcxx-pretty-printers>`_.
+
+
+Libc++ Configuration Macros
+===========================
+
+Libc++ provides a number of configuration macros which can be used to enable
+or disable extended libc++ behavior, including enabling "debug mode" or
+thread safety annotations.
+
+**_LIBCPP_DEBUG**:
+  See :ref:`using-debug-mode` for more information.
+
+**_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS**:
+  This macro is used to enable -Wthread-safety annotations on libc++'s
+  ``std::mutex`` and ``std::lock_guard``. By default these annotations are
+  disabled and must be manually enabled by the user.
+
+**_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**:
+  This macro is used to disable all visibility annotations inside libc++.
+  Defining this macro and then building libc++ with hidden visibility gives a
+  build of libc++ which does not export any symbols, which can be useful when
+  building statically for inclusion into another library.
+
+**_LIBCPP_DISABLE_EXTERN_TEMPLATE**:
+  This macro is used to disable extern template declarations in the libc++
+  headers. The intended use case is for clients who wish to use the libc++
+  headers without taking a dependency on the libc++ library itself.
+
+**_LIBCPP_ENABLE_TUPLE_IMPLICIT_REDUCED_ARITY_EXTENSION**:
+  This macro is used to re-enable an extension in `std::tuple` which allowed
+  it to be implicitly constructed from fewer initializers than contained
+  elements. Elements without an initializer are default constructed. For example:
+
+  .. code-block:: cpp
+
+    std::tuple<std::string, int, std::error_code> foo() {
+      return {"hello world", 42}; // default constructs error_code
+    }
+
+
+  Since libc++ 4.0 this extension has been disabled by default. This macro
+  may be defined to re-enable it in order to support existing code that depends
+  on the extension. New use of this extension should be discouraged.
+  See `PR 27374 <http://llvm.org/PR27374>`_ for more information.
+
+  Note: The "reduced-arity-initialization" extension is still offered but only
+  for explicit conversions. Example:
+
+  .. code-block:: cpp
+
+    auto foo() {
+      using Tup = std::tuple<std::string, int, std::error_code>;
+      return Tup{"hello world", 42}; // explicit constructor called. OK.
+    }
+
+**_LIBCPP_DISABLE_ADDITIONAL_DIAGNOSTICS**:
+  This macro disables the additional diagnostics generated by libc++ using the
+  `diagnose_if` attribute. These additional diagnostics include checks for:
+
+    * Giving `set`, `map`, `multiset`, `multimap` a comparator which is not
+      const callable.
+
+**_LIBCPP_NO_VCRUNTIME**:
+  Microsoft's C and C++ headers are fairly entangled, and some of their C++
+  headers are fairly hard to avoid. In particular, `vcruntime_new.h` gets pulled
+  in from a lot of other headers and provides definitions which clash with
+  libc++ headers, such as `nothrow_t` (note that `nothrow_t` is a struct, so
+  there's no way for libc++ to provide a compatible definition, since you can't
+  have multiple definitions).
+
+  By default, libc++ solves this problem by deferring to Microsoft's vcruntime
+  headers where needed. However, it may be undesirable to depend on vcruntime
+  headers, since they may not always be available in cross-compilation setups,
+  or they may clash with other headers. The `_LIBCPP_NO_VCRUNTIME` macro
+  prevents libc++ from depending on vcruntime headers. Consequently, it also
+  prevents libc++ headers from being interoperable with vcruntime headers (from
+  the aforementioned clashes), so users of this macro are promising to not
+  attempt to combine libc++ headers with the problematic vcruntime headers. This
+  macro also currently prevents certain `operator new`/`operator delete`
+  replacement scenarios from working, e.g. replacing `operator new` and
+  expecting a non-replaced `operator new[]` to call the replaced `operator new`.
+
+C++17 Specific Configuration Macros
+-----------------------------------
+**_LIBCPP_ENABLE_CXX17_REMOVED_FEATURES**:
+  This macro is used to re-enable all the features removed in C++17. The effect
+  is equivalent to manually defining each macro listed below.
+
+**_LIBCPP_ENABLE_CXX17_REMOVED_UNEXPECTED_FUNCTIONS**:
+  This macro is used to re-enable the `set_unexpected`, `get_unexpected`, and
+  `unexpected` functions, which were removed in C++17.
+
+**_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**:
+  This macro is used to re-enable `std::auto_ptr` in C++17.

external/llvm-project/libcxx/docs/conf.py

@@ -0,0 +1,251 @@
+# -*- coding: utf-8 -*-
+#
+# libc++ documentation build configuration file.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.todo']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'libc++'
+copyright = u'2011-2017, LLVM Project'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '6.0'
+# The full version, including alpha/beta/rc tags.
+release = '6.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%Y-%m-%d'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+show_authors = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'friendly'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'haiku'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'libcxxdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('contents', 'libcxx.tex', u'libcxx Documentation',
+   u'LLVM project', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('contents', 'libc++', u'libc++ Documentation',
+     [u'LLVM project'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('contents', 'libc++', u'libc++ Documentation',
+   u'LLVM project', 'libc++', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+
+# FIXME: Define intersphinx configration.
+intersphinx_mapping = {}
+
+
+# -- Options for extensions ----------------------------------------------------
+
+# Enable this if you want TODOs to show up in the generated documentation.
+todo_include_todos = True

external/llvm-project/libcxx/docs/index.rst

@@ -0,0 +1,188 @@
+.. _index:
+
+=============================
+"libc++" C++ Standard Library
+=============================
+
+Overview
+========
+
+libc++ is a new implementation of the C++ standard library, targeting C++11 and
+above.
+
+* 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://bugs.llvm.org/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/AvailabilityMarkup
+   DesignDocs/DebugMode
+   DesignDocs/CapturingConfigInfo
+   DesignDocs/ABIVersioning
+   DesignDocs/VisibilityMacros
+   DesignDocs/ThreadingSupportAPI
+
+* `<atomic> design <http://libcxx.llvm.org/atomic_design.html>`_
+* `<type_traits> design <http://libcxx.llvm.org/type_traits_design.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/>`_
+* `Windows Appveyor Builders <https://ci.appveyor.com/project/llvm-mirror/libcxx>`_
+* `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 <https://bugs.llvm.org/>`_
+* `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/>`_