Using libc++¶

Getting Started
Using <filesystem>
Using libc++experimental and <experimental/...>
Using libc++ on Linux
- Using libc++ with GCC
- GDB Pretty printers for libc++
Libc++ Configuration Macros
- C++17 Specific Configuration Macros
- C++20 Specific Configuration Macros:
Libc++ Extensions
- Extended applications of [[nodiscard]]
  - Entities declared with _LIBCPP_NODISCARD_EXT

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 Building Libc++ and libc++experimental CMake Options.

Also see the Experimental Library Implementation Status 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.
When we implement the standardized version of an experimental feature, the experimental feature is removed two releases after the non-experimental version has shipped. The full policy is explained here.

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 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 Extended Applications of [[nodiscard]] for more information.

_LIBCPP_DISABLE_NODISCARD_EXT:

This macro prevents the library from applying [[nodiscard]] to entities purely as an extension. See Extended Applications of [[nodiscard]] 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++20 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 Extended Applications of [[nodiscard]] 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:

Backporting [[nodiscard]] to entities declared as such by the standard in newer dialects, but not in the present one.
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