1============ 2Using libc++ 3============ 4 5.. contents:: 6 :local: 7 8Getting Started 9=============== 10 11If you already have libc++ installed you can use it with clang. 12 13.. code-block:: bash 14 15 $ clang++ -stdlib=libc++ test.cpp 16 $ clang++ -std=c++11 -stdlib=libc++ test.cpp 17 18On macOS and FreeBSD libc++ is the default standard library 19and the ``-stdlib=libc++`` is not required. 20 21.. _alternate libcxx: 22 23If you want to select an alternate installation of libc++ you 24can use the following options. 25 26.. code-block:: bash 27 28 $ clang++ -std=c++11 -stdlib=libc++ -nostdinc++ \ 29 -I<libcxx-install-prefix>/include/c++/v1 \ 30 -L<libcxx-install-prefix>/lib \ 31 -Wl,-rpath,<libcxx-install-prefix>/lib \ 32 test.cpp 33 34The option ``-Wl,-rpath,<libcxx-install-prefix>/lib`` adds a runtime library 35search path. Meaning that the systems dynamic linker will look for libc++ in 36``<libcxx-install-prefix>/lib`` whenever the program is run. Alternatively the 37environment variable ``LD_LIBRARY_PATH`` (``DYLD_LIBRARY_PATH`` on macOS) can 38be used to change the dynamic linkers search paths after a program is compiled. 39 40An example of using ``LD_LIBRARY_PATH``: 41 42.. code-block:: bash 43 44 $ clang++ -stdlib=libc++ -nostdinc++ \ 45 -I<libcxx-install-prefix>/include/c++/v1 46 -L<libcxx-install-prefix>/lib \ 47 test.cpp -o 48 $ ./a.out # Searches for libc++ in the systems library paths. 49 $ export LD_LIBRARY_PATH=<libcxx-install-prefix>/lib 50 $ ./a.out # Searches for libc++ along LD_LIBRARY_PATH 51 52Using ``<filesystem>`` 53====================== 54 55Prior to LLVM 9.0, libc++ provides the implementation of the filesystem library 56in a separate static library. Users of ``<filesystem>`` and ``<experimental/filesystem>`` 57are required to link ``-lc++fs``. Prior to libc++ 7.0, users of 58``<experimental/filesystem>`` were required to link libc++experimental. 59 60Starting with LLVM 9.0, support for ``<filesystem>`` is provided in the main 61library and nothing special is required to use ``<filesystem>``. 62 63Using libc++experimental and ``<experimental/...>`` 64===================================================== 65 66Libc++ provides implementations of experimental technical specifications 67in a separate library, ``libc++experimental.a``. Users of ``<experimental/...>`` 68headers may be required to link ``-lc++experimental``. 69 70.. code-block:: bash 71 72 $ clang++ -std=c++14 -stdlib=libc++ test.cpp -lc++experimental 73 74Libc++experimental.a may not always be available, even when libc++ is already 75installed. For information on building libc++experimental from source see 76:ref:`Building Libc++ <build instructions>` and 77:ref:`libc++experimental CMake Options <libc++experimental options>`. 78 79Also see the `Experimental Library Implementation Status <http://libcxx.llvm.org/ts1z_status.html>`__ 80page. 81 82.. warning:: 83 Experimental libraries are Experimental. 84 * The contents of the ``<experimental/...>`` headers and ``libc++experimental.a`` 85 library will not remain compatible between versions. 86 * No guarantees of API or ABI stability are provided. 87 * When we implement the standardized version of an experimental feature, 88 the experimental feature is removed two releases after the non-experimental 89 version has shipped. The full policy is explained :ref:`here <experimental features>`. 90 91Using libc++ on Linux 92===================== 93 94On Linux libc++ can typically be used with only '-stdlib=libc++'. However 95some libc++ installations require the user manually link libc++abi themselves. 96If you are running into linker errors when using libc++ try adding '-lc++abi' 97to the link line. For example: 98 99.. code-block:: bash 100 101 $ clang++ -stdlib=libc++ test.cpp -lc++ -lc++abi -lm -lc -lgcc_s -lgcc 102 103Alternately, you could just add libc++abi to your libraries list, which in 104most situations will give the same result: 105 106.. code-block:: bash 107 108 $ clang++ -stdlib=libc++ test.cpp -lc++abi 109 110 111Using libc++ with GCC 112--------------------- 113 114GCC does not provide a way to switch from libstdc++ to libc++. You must manually 115configure the compile and link commands. 116 117In particular you must tell GCC to remove the libstdc++ include directories 118using ``-nostdinc++`` and to not link libstdc++.so using ``-nodefaultlibs``. 119 120Note that ``-nodefaultlibs`` removes all of the standard system libraries and 121not just libstdc++ so they must be manually linked. For example: 122 123.. code-block:: bash 124 125 $ g++ -nostdinc++ -I<libcxx-install-prefix>/include/c++/v1 \ 126 test.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc 127 128 129GDB Pretty printers for libc++ 130------------------------------ 131 132GDB does not support pretty-printing of libc++ symbols by default. Unfortunately 133libc++ does not provide pretty-printers itself. However there are 3rd 134party implementations available and although they are not officially 135supported by libc++ they may be useful to users. 136 137Known 3rd Party Implementations Include: 138 139* `Koutheir's libc++ pretty-printers <https://github.com/koutheir/libcxx-pretty-printers>`_. 140 141 142Libc++ Configuration Macros 143=========================== 144 145Libc++ provides a number of configuration macros which can be used to enable 146or disable extended libc++ behavior, including enabling "debug mode" or 147thread safety annotations. 148 149**_LIBCPP_DEBUG**: 150 See :ref:`using-debug-mode` for more information. 151 152**_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS**: 153 This macro is used to enable -Wthread-safety annotations on libc++'s 154 ``std::mutex`` and ``std::lock_guard``. By default these annotations are 155 disabled and must be manually enabled by the user. 156 157**_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**: 158 This macro is used to disable all visibility annotations inside libc++. 159 Defining this macro and then building libc++ with hidden visibility gives a 160 build of libc++ which does not export any symbols, which can be useful when 161 building statically for inclusion into another library. 162 163**_LIBCPP_DISABLE_EXTERN_TEMPLATE**: 164 This macro is used to disable extern template declarations in the libc++ 165 headers. The intended use case is for clients who wish to use the libc++ 166 headers without taking a dependency on the libc++ library itself. 167 168**_LIBCPP_ENABLE_TUPLE_IMPLICIT_REDUCED_ARITY_EXTENSION**: 169 This macro is used to re-enable an extension in `std::tuple` which allowed 170 it to be implicitly constructed from fewer initializers than contained 171 elements. Elements without an initializer are default constructed. For example: 172 173 .. code-block:: cpp 174 175 std::tuple<std::string, int, std::error_code> foo() { 176 return {"hello world", 42}; // default constructs error_code 177 } 178 179 180 Since libc++ 4.0 this extension has been disabled by default. This macro 181 may be defined to re-enable it in order to support existing code that depends 182 on the extension. New use of this extension should be discouraged. 183 See `PR 27374 <https://llvm.org/PR27374>`_ for more information. 184 185 Note: The "reduced-arity-initialization" extension is still offered but only 186 for explicit conversions. Example: 187 188 .. code-block:: cpp 189 190 auto foo() { 191 using Tup = std::tuple<std::string, int, std::error_code>; 192 return Tup{"hello world", 42}; // explicit constructor called. OK. 193 } 194 195**_LIBCPP_DISABLE_ADDITIONAL_DIAGNOSTICS**: 196 This macro disables the additional diagnostics generated by libc++ using the 197 `diagnose_if` attribute. These additional diagnostics include checks for: 198 199 * Giving `set`, `map`, `multiset`, `multimap` and their `unordered_` 200 counterparts a comparator which is not const callable. 201 * Giving an unordered associative container a hasher that is not const 202 callable. 203 204**_LIBCPP_NO_VCRUNTIME**: 205 Microsoft's C and C++ headers are fairly entangled, and some of their C++ 206 headers are fairly hard to avoid. In particular, `vcruntime_new.h` gets pulled 207 in from a lot of other headers and provides definitions which clash with 208 libc++ headers, such as `nothrow_t` (note that `nothrow_t` is a struct, so 209 there's no way for libc++ to provide a compatible definition, since you can't 210 have multiple definitions). 211 212 By default, libc++ solves this problem by deferring to Microsoft's vcruntime 213 headers where needed. However, it may be undesirable to depend on vcruntime 214 headers, since they may not always be available in cross-compilation setups, 215 or they may clash with other headers. The `_LIBCPP_NO_VCRUNTIME` macro 216 prevents libc++ from depending on vcruntime headers. Consequently, it also 217 prevents libc++ headers from being interoperable with vcruntime headers (from 218 the aforementioned clashes), so users of this macro are promising to not 219 attempt to combine libc++ headers with the problematic vcruntime headers. This 220 macro also currently prevents certain `operator new`/`operator delete` 221 replacement scenarios from working, e.g. replacing `operator new` and 222 expecting a non-replaced `operator new[]` to call the replaced `operator new`. 223 224**_LIBCPP_ENABLE_NODISCARD**: 225 Allow the library to add ``[[nodiscard]]`` attributes to entities not specified 226 as ``[[nodiscard]]`` by the current language dialect. This includes 227 backporting applications of ``[[nodiscard]]`` from newer dialects and 228 additional extended applications at the discretion of the library. All 229 additional applications of ``[[nodiscard]]`` are disabled by default. 230 See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` for 231 more information. 232 233**_LIBCPP_DISABLE_NODISCARD_EXT**: 234 This macro prevents the library from applying ``[[nodiscard]]`` to entities 235 purely as an extension. See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` 236 for more information. 237 238**_LIBCPP_DISABLE_DEPRECATION_WARNINGS**: 239 This macro disables warnings when using deprecated components. For example, 240 using `std::auto_ptr` when compiling in C++11 mode will normally trigger a 241 warning saying that `std::auto_ptr` is deprecated. If the macro is defined, 242 no warning will be emitted. By default, this macro is not defined. 243 244C++17 Specific Configuration Macros 245----------------------------------- 246**_LIBCPP_ENABLE_CXX17_REMOVED_FEATURES**: 247 This macro is used to re-enable all the features removed in C++17. The effect 248 is equivalent to manually defining each macro listed below. 249 250**_LIBCPP_ENABLE_CXX17_REMOVED_UNEXPECTED_FUNCTIONS**: 251 This macro is used to re-enable the `set_unexpected`, `get_unexpected`, and 252 `unexpected` functions, which were removed in C++17. 253 254**_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**: 255 This macro is used to re-enable `std::auto_ptr` in C++17. 256 257C++2a Specific Configuration Macros: 258------------------------------------ 259**_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17**: 260 This macro can be used to disable diagnostics emitted from functions marked 261 ``[[nodiscard]]`` in dialects after C++17. See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` 262 for more information. 263 264 265Libc++ Extensions 266================= 267 268This section documents various extensions provided by libc++, how they're 269provided, and any information regarding how to use them. 270 271.. _nodiscard extension: 272 273Extended applications of ``[[nodiscard]]`` 274------------------------------------------ 275 276The ``[[nodiscard]]`` attribute is intended to help users find bugs where 277function return values are ignored when they shouldn't be. After C++17 the 278C++ standard has started to declared such library functions as ``[[nodiscard]]``. 279However, this application is limited and applies only to dialects after C++17. 280Users who want help diagnosing misuses of STL functions may desire a more 281liberal application of ``[[nodiscard]]``. 282 283For this reason libc++ provides an extension that does just that! The 284extension must be enabled by defining ``_LIBCPP_ENABLE_NODISCARD``. The extended 285applications of ``[[nodiscard]]`` takes two forms: 286 2871. Backporting ``[[nodiscard]]`` to entities declared as such by the 288 standard in newer dialects, but not in the present one. 289 2902. Extended applications of ``[[nodiscard]]``, at the libraries discretion, 291 applied to entities never declared as such by the standard. 292 293Users may also opt-out of additional applications ``[[nodiscard]]`` using 294additional macros. 295 296Applications of the first form, which backport ``[[nodiscard]]`` from a newer 297dialect may be disabled using macros specific to the dialect it was added. For 298example ``_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17``. 299 300Applications of the second form, which are pure extensions, may be disabled 301by defining ``_LIBCPP_DISABLE_NODISCARD_EXT``. 302 303 304Entities declared with ``_LIBCPP_NODISCARD_EXT`` 305~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 306 307This section lists all extended applications of ``[[nodiscard]]`` to entities 308which no dialect declares as such (See the second form described above). 309 310* ``adjacent_find`` 311* ``all_of`` 312* ``any_of`` 313* ``binary_search`` 314* ``clamp`` 315* ``count_if`` 316* ``count`` 317* ``equal_range`` 318* ``equal`` 319* ``find_end`` 320* ``find_first_of`` 321* ``find_if_not`` 322* ``find_if`` 323* ``find`` 324* ``get_temporary_buffer`` 325* ``includes`` 326* ``is_heap_until`` 327* ``is_heap`` 328* ``is_partitioned`` 329* ``is_permutation`` 330* ``is_sorted_until`` 331* ``is_sorted`` 332* ``lexicographical_compare`` 333* ``lower_bound`` 334* ``max_element`` 335* ``max`` 336* ``min_element`` 337* ``min`` 338* ``minmax_element`` 339* ``minmax`` 340* ``mismatch`` 341* ``none_of`` 342* ``remove_if`` 343* ``remove`` 344* ``search_n`` 345* ``search`` 346* ``unique`` 347* ``upper_bound`` 348* ``lock_guard``'s constructors 349