============ Using libc++ ============ .. contents:: :local: Getting Started =============== If you already have libc++ installed you can use it with clang. .. code-block:: bash $ 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. .. _alternate libcxx: If you want to select an alternate installation of libc++ you can use the following options. .. code-block:: bash $ clang++ -std=c++11 -stdlib=libc++ -nostdinc++ \ -I/include/c++/v1 \ -L/lib \ -Wl,-rpath,/lib \ test.cpp The option ``-Wl,-rpath,/lib`` adds a runtime library search path. Meaning that the systems dynamic linker will look for libc++ in ``/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``: .. code-block:: bash $ clang++ -stdlib=libc++ -nostdinc++ \ -I/include/c++/v1 -L/lib \ test.cpp -o $ ./a.out # Searches for libc++ in the systems library paths. $ export LD_LIBRARY_PATH=/lib $ ./a.out # Searches for libc++ along LD_LIBRARY_PATH Using ```` ====================== Prior to LLVM 9.0, libc++ provides the implementation of the filesystem library in a separate static library. Users of ```` and ```` are required to link ``-lc++fs``. Prior to libc++ 7.0, users of ```` were required to link libc++experimental. Starting with LLVM 9.0, support for ```` is provided in the main library and nothing special is required to use ````. Using libc++experimental and ```` ===================================================== Libc++ provides implementations of experimental technical specifications in a separate library, ``libc++experimental.a``. Users of ```` headers may be required to link ``-lc++experimental``. .. code-block:: bash $ 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++ ` and :ref:`libc++experimental CMake Options `. Also see the `Experimental Library Implementation Status `__ page. .. warning:: Experimental libraries are Experimental. * The contents of the ```` 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 :ref:`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: .. code-block:: bash $ 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: .. code-block:: bash $ 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: .. code-block:: bash $ g++ -nostdinc++ -I/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: .. code-block:: cpp std::tuple 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: .. code-block:: cpp auto foo() { using Tup = std::tuple; 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]] ` 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]] ` 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]] ` 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. .. _nodiscard extension: 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