[libc++] Support Microsoft ABI without vcruntime headers
The vcruntime headers are hairy and clash with both libc++ headers
themselves and other libraries. libc++ normally deals with the clashes
by deferring to the vcruntime headers and silencing its own definitions,
but for clients which don't want to depend on vcruntime headers, it's
desirable to support the opposite, i.e. have libc++ provide its own
definitions.
Certain operator new/delete replacement scenarios are not currently
supported in this mode, which requires some tests to be marked XFAIL.
The added documentation has more details.
Differential Revision: https://reviews.llvm.org/D38522
git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@315234 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/docs/UsingLibcxx.rst b/docs/UsingLibcxx.rst
index 1836646..f54234d 100644
--- a/docs/UsingLibcxx.rst
+++ b/docs/UsingLibcxx.rst
@@ -185,6 +185,26 @@
* 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**: