import of libc++ 6.0.0

1 files changed, 94 insertions, 0 deletions

diff --git a/lib/libcxx/docs/UsingLibcxx.rst b/lib/libcxx/docs/UsingLibcxx.rst
index 514ed14b746..f54234d6aa3 100644
--- a/lib/libcxx/docs/UsingLibcxx.rst
+++ b/lib/libcxx/docs/UsingLibcxx.rst
@@ -123,3 +123,97 @@ 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.