| | ============ |
| | 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<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``: |
| |
|
| | .. code-block:: bash |
| |
|
| | $ 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``. |
| |
|
| | .. 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++ <build instructions>` and |
| | :ref:`libc++experimental CMake Options <libc++experimental options>`. |
| |
|
| | Also see the `Experimental Library Implementation Status <http://libcxx.llvm.org/ts1z_status.html>`__ |
| | 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 :ref:`here <experimental features>`. |
| |
|
| | 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<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 <https://github.com/koutheir/libcxx-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. |
| |
|
| | **_LIBCUDACXX_DEBUG**: |
| | See :ref:`using-debug-mode` for more information. |
| |
|
| | **_LIBCUDACXX_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. |
| |
|
| | **_LIBCUDACXX_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. |
| |
|
| | **_LIBCUDACXX_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. |
| |
|
| | **_LIBCUDACXX_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<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 <http://llvm.org/PR27374>`_ 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<std::string, int, std::error_code>; |
| | return Tup{"hello world", 42}; // explicit constructor called. OK. |
| | } |
| |
|
| | **_LIBCUDACXX_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. |
| |
|
| | **_LIBCUDACXX_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 `_LIBCUDACXX_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`. |
| |
|
| | **_LIBCUDACXX_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. |
| |
|
| | **_LIBCUDACXX_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. |
| |
|
| | **_LIBCUDACXX_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 |
| | ----------------------------------- |
| | **_LIBCUDACXX_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. |
| |
|
| | **_LIBCUDACXX_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. |
| |
|
| | **_LIBCUDACXX_ENABLE_CXX17_REMOVED_AUTO_PTR**: |
| | This macro is used to re-enable `std::auto_ptr` in C++17. |
| |
|
| | C++2a Specific Configuration Macros: |
| | ------------------------------------ |
| | **_LIBCUDACXX_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. |
| |
|
| | .. _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 ``_LIBCUDACXX_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 ``_LIBCUDACXX_DISABLE_NODISCARD_AFTER_CXX17``. |
| | |
| | Applications of the second form, which are pure extensions, may be disabled |
| | by defining ``_LIBCUDACXX_DISABLE_NODISCARD_EXT``. |
| | |
| | |
| | Entities declared with ``_LIBCUDACXX_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 |
| | |
