Using libc++

Getting Started

If you already have libc++ installed you can use it with clang.

$ clang++ -stdlib=libc++ test.cpp
$ clang++ -std=c++11 -stdlib=libc++ test.cpp

On macOS and FreeBSD libc++ is the default standard library and the -stdlib=libc++ is not required.

If you want to select an alternate installation of libc++ you can use the following options.

$ 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 macOS) can be used to change the dynamic linkers search paths after a program is compiled.

An example of using LD_LIBRARY_PATH:

$ 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 <filesystem>

Prior to LLVM 9.0, libc++ provides the implementation of the filesystem library in a separate static library. Users of <filesystem> and <experimental/filesystem> are required to link -lc++fs. Prior to libc++ 7.0, users of <experimental/filesystem> were required to link libc++experimental.

Starting with LLVM 9.0, support for <filesystem> is provided in the main library and nothing special is required to use <filesystem>.

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++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 page.

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:

$ 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:

$ 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:

$ 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.

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:

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 and their unordered_ counterparts a comparator which is not const callable.
• Giving an unordered associative container a hasher that 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.

_LIBCPP_ENABLE_NODISCARD:

Allow the library to add [[nodiscard]] attributes to entities not specified as [[nodiscard]] by the current language dialect. This includes backporting applications of [[nodiscard]] from newer dialects and additional extended applications at the discretion of the library. All additional applications of [[nodiscard]] are disabled by default. See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` for more information.

_LIBCPP_DISABLE_NODISCARD_EXT:

This macro prevents the library from applying [[nodiscard]] to entities purely as an extension. See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` for more information.

_LIBCPP_DISABLE_DEPRECATION_WARNINGS:

This macro disables warnings when using deprecated components. For example, using std::auto_ptr when compiling in C++11 mode will normally trigger a warning saying that std::auto_ptr is deprecated. If the macro is defined, no warning will be emitted. By default, this macro is not defined.

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.

C++2a Specific Configuration Macros:

_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17:

This macro can be used to disable diagnostics emitted from functions marked [[nodiscard]] in dialects after C++17. See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` for more information.

Libc++ Extensions

This section documents various extensions provided by libc++, how they're provided, and any information regarding how to use them.

Extended applications of [[nodiscard]]

The [[nodiscard]] attribute is intended to help users find bugs where function return values are ignored when they shouldn't be. After C++17 the C++ standard has started to declared such library functions as [[nodiscard]]. However, this application is limited and applies only to dialects after C++17. Users who want help diagnosing misuses of STL functions may desire a more liberal application of [[nodiscard]].

For this reason libc++ provides an extension that does just that! The extension must be enabled by defining _LIBCPP_ENABLE_NODISCARD. The extended applications of [[nodiscard]] takes two forms:

1. Backporting [[nodiscard]] to entities declared as such by the standard in newer dialects, but not in the present one.
2. Extended applications of [[nodiscard]], at the libraries discretion, applied to entities never declared as such by the standard.

Users may also opt-out of additional applications [[nodiscard]] using additional macros.

Applications of the first form, which backport [[nodiscard]] from a newer dialect may be disabled using macros specific to the dialect it was added. For example _LIBCPP_DISABLE_NODISCARD_AFTER_CXX17.

Applications of the second form, which are pure extensions, may be disabled by defining _LIBCPP_DISABLE_NODISCARD_EXT.

Entities declared with _LIBCPP_NODISCARD_EXT

This section lists all extended applications of [[nodiscard]] to entities which no dialect declares as such (See the second form described above).

• adjacent_find
• all_of
• any_of
• binary_search
• clamp
• count_if
• count
• equal_range
• equal
• find_end
• find_first_of
• find_if_not
• find_if
• find
• get_temporary_buffer
• includes
• is_heap_until
• is_heap
• is_partitioned
• is_permutation
• is_sorted_until
• is_sorted
• lexicographical_compare
• lower_bound
• max_element
• max
• min_element
• min
• minmax_element
• minmax
• mismatch
• none_of
• remove_if
• remove
• search_n
• search
• unique
• upper_bound
• lock_guard's constructors