Find a Home for These Notes

Start by locating the repository’s existing documentation structure and conventions, then determine where notes on libc++experimental linking and libc++ configuration macros belong. Place the material in the appropriate documentation home, preserving the examples and macro descriptions, and verify that the resulting page is discoverable through the project’s documentation navigation.

This documentation needs a home:

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.
$ clang++ -std=c++14 -stdlib=libc++ test.cpp -lc++experimental

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 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:
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 for more information.
Note: The “reduced-arity-initialization” extension is still offered but only for explicit conversions. Example:
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.