1.. _using-libcxx: 2 3============ 4Using libc++ 5============ 6 7.. contents:: 8 :local: 9 10Usually, libc++ is packaged and shipped by a vendor through some delivery vehicle 11(operating system distribution, SDK, toolchain, etc) and users don't need to do 12anything special in order to use the library. 13 14This page contains information about configuration knobs that can be used by 15users when they know libc++ is used by their toolchain, and how to use libc++ 16when it is not the default library used by their toolchain. 17 18 19Using a different version of the C++ Standard 20============================================= 21 22Libc++ implements the various versions of the C++ Standard. Changing the version of 23the standard can be done by passing ``-std=c++XY`` to the compiler. Libc++ will 24automatically detect what Standard is being used and will provide functionality that 25matches that Standard in the library. 26 27.. code-block:: bash 28 29 $ clang++ -std=c++17 test.cpp 30 31.. warning:: 32 Using ``-std=c++XY`` with a version of the Standard that has not been ratified yet 33 is considered unstable. Libc++ reserves the right to make breaking changes to the 34 library until the standard has been ratified. 35 36 37Using libc++experimental and ``<experimental/...>`` 38=================================================== 39 40Libc++ provides implementations of experimental technical specifications 41in a separate library, ``libc++experimental.a``. Users of ``<experimental/...>`` 42headers may be required to link ``-lc++experimental``. Note that not all 43vendors ship ``libc++experimental.a``, and as a result, you may not be 44able to use those experimental features. 45 46.. code-block:: bash 47 48 $ clang++ test.cpp -lc++experimental 49 50.. warning:: 51 Experimental libraries are Experimental. 52 * The contents of the ``<experimental/...>`` headers and ``libc++experimental.a`` 53 library will not remain compatible between versions. 54 * No guarantees of API or ABI stability are provided. 55 * When the standardized version of an experimental feature is implemented, 56 the experimental feature is removed two releases after the non-experimental 57 version has shipped. The full policy is explained :ref:`here <experimental features>`. 58 59 60Using libc++ when it is not the system default 61============================================== 62 63On systems where libc++ is provided but is not the default, Clang provides a flag 64called ``-stdlib=`` that can be used to decide which standard library is used. 65Using ``-stdlib=libc++`` will select libc++: 66 67.. code-block:: bash 68 69 $ clang++ -stdlib=libc++ test.cpp 70 71On systems where libc++ is the library in use by default such as macOS and FreeBSD, 72this flag is not required. 73 74 75.. _alternate libcxx: 76 77Using a custom built libc++ 78=========================== 79 80Most compilers provide a way to disable the default behavior for finding the 81standard library and to override it with custom paths. With Clang, this can 82be done with: 83 84.. code-block:: bash 85 86 $ clang++ -nostdinc++ -nostdlib++ \ 87 -isystem <install>/include/c++/v1 \ 88 -L <install>/lib \ 89 -Wl,-rpath,<install>/lib \ 90 -lc++ \ 91 test.cpp 92 93The option ``-Wl,-rpath,<install>/lib`` adds a runtime library search path, 94which causes the system's dynamic linker to look for libc++ in ``<install>/lib`` 95whenever the program is loaded. 96 97GCC does not support the ``-nostdlib++`` flag, so one must use ``-nodefaultlibs`` 98instead. Since that removes all the standard system libraries and not just libc++, 99the system libraries must be re-added manually. For example: 100 101.. code-block:: bash 102 103 $ g++ -nostdinc++ -nodefaultlibs \ 104 -isystem <install>/include/c++/v1 \ 105 -L <install>/lib \ 106 -Wl,-rpath,<install>/lib \ 107 -lc++ -lc++abi -lm -lc -lgcc_s -lgcc \ 108 test.cpp 109 110 111GDB Pretty printers for libc++ 112============================== 113 114GDB does not support pretty-printing of libc++ symbols by default. However, libc++ does 115provide pretty-printers itself. Those can be used as: 116 117.. code-block:: bash 118 119 $ gdb -ex "source <libcxx>/utils/gdb/libcxx/printers.py" \ 120 -ex "python register_libcxx_printer_loader()" \ 121 <args> 122 123 124Libc++ Configuration Macros 125=========================== 126 127Libc++ provides a number of configuration macros which can be used to enable 128or disable extended libc++ behavior, including enabling "debug mode" or 129thread safety annotations. 130 131**_LIBCPP_DEBUG**: 132 See :ref:`using-debug-mode` for more information. 133 134**_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS**: 135 This macro is used to enable -Wthread-safety annotations on libc++'s 136 ``std::mutex`` and ``std::lock_guard``. By default, these annotations are 137 disabled and must be manually enabled by the user. 138 139**_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**: 140 This macro is used to disable all visibility annotations inside libc++. 141 Defining this macro and then building libc++ with hidden visibility gives a 142 build of libc++ which does not export any symbols, which can be useful when 143 building statically for inclusion into another library. 144 145**_LIBCPP_DISABLE_EXTERN_TEMPLATE**: 146 This macro is used to disable extern template declarations in the libc++ 147 headers. The intended use case is for clients who wish to use the libc++ 148 headers without taking a dependency on the libc++ library itself. 149 150**_LIBCPP_DISABLE_ADDITIONAL_DIAGNOSTICS**: 151 This macro disables the additional diagnostics generated by libc++ using the 152 `diagnose_if` attribute. These additional diagnostics include checks for: 153 154 * Giving `set`, `map`, `multiset`, `multimap` and their `unordered_` 155 counterparts a comparator which is not const callable. 156 * Giving an unordered associative container a hasher that is not const 157 callable. 158 159**_LIBCPP_NO_VCRUNTIME**: 160 Microsoft's C and C++ headers are fairly entangled, and some of their C++ 161 headers are fairly hard to avoid. In particular, `vcruntime_new.h` gets pulled 162 in from a lot of other headers and provides definitions which clash with 163 libc++ headers, such as `nothrow_t` (note that `nothrow_t` is a struct, so 164 there's no way for libc++ to provide a compatible definition, since you can't 165 have multiple definitions). 166 167 By default, libc++ solves this problem by deferring to Microsoft's vcruntime 168 headers where needed. However, it may be undesirable to depend on vcruntime 169 headers, since they may not always be available in cross-compilation setups, 170 or they may clash with other headers. The `_LIBCPP_NO_VCRUNTIME` macro 171 prevents libc++ from depending on vcruntime headers. Consequently, it also 172 prevents libc++ headers from being interoperable with vcruntime headers (from 173 the aforementioned clashes), so users of this macro are promising to not 174 attempt to combine libc++ headers with the problematic vcruntime headers. This 175 macro also currently prevents certain `operator new`/`operator delete` 176 replacement scenarios from working, e.g. replacing `operator new` and 177 expecting a non-replaced `operator new[]` to call the replaced `operator new`. 178 179**_LIBCPP_ENABLE_NODISCARD**: 180 Allow the library to add ``[[nodiscard]]`` attributes to entities not specified 181 as ``[[nodiscard]]`` by the current language dialect. This includes 182 backporting applications of ``[[nodiscard]]`` from newer dialects and 183 additional extended applications at the discretion of the library. All 184 additional applications of ``[[nodiscard]]`` are disabled by default. 185 See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` for 186 more information. 187 188**_LIBCPP_DISABLE_NODISCARD_EXT**: 189 This macro prevents the library from applying ``[[nodiscard]]`` to entities 190 purely as an extension. See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` 191 for more information. 192 193**_LIBCPP_DISABLE_DEPRECATION_WARNINGS**: 194 This macro disables warnings when using deprecated components. For example, 195 using `std::auto_ptr` when compiling in C++11 mode will normally trigger a 196 warning saying that `std::auto_ptr` is deprecated. If the macro is defined, 197 no warning will be emitted. By default, this macro is not defined. 198 199C++17 Specific Configuration Macros 200----------------------------------- 201**_LIBCPP_ENABLE_CXX17_REMOVED_FEATURES**: 202 This macro is used to re-enable all the features removed in C++17. The effect 203 is equivalent to manually defining each macro listed below. 204 205**_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**: 206 This macro is used to re-enable `auto_ptr`. 207 208**_LIBCPP_ENABLE_CXX17_REMOVED_BINDERS**: 209 This macro is used to re-enable the `binder1st`, `binder2nd`, 210 `pointer_to_unary_function`, `pointer_to_binary_function`, `mem_fun_t`, 211 `mem_fun1_t`, `mem_fun_ref_t`, `mem_fun1_ref_t`, `const_mem_fun_t`, 212 `const_mem_fun1_t`, `const_mem_fun_ref_t`, and `const_mem_fun1_ref_t` 213 class templates, and the `bind1st`, `bind2nd`, `mem_fun`, `mem_fun_ref`, 214 and `ptr_fun` functions. 215 216**_LIBCPP_ENABLE_CXX17_REMOVED_RANDOM_SHUFFLE**: 217 This macro is used to re-enable the `random_shuffle` algorithm. 218 219**_LIBCPP_ENABLE_CXX17_REMOVED_UNEXPECTED_FUNCTIONS**: 220 This macro is used to re-enable `set_unexpected`, `get_unexpected`, and 221 `unexpected`. 222 223C++20 Specific Configuration Macros: 224------------------------------------ 225**_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17**: 226 This macro can be used to disable diagnostics emitted from functions marked 227 ``[[nodiscard]]`` in dialects after C++17. See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` 228 for more information. 229 230**_LIBCPP_ENABLE_CXX20_REMOVED_FEATURES**: 231 This macro is used to re-enable all the features removed in C++20. The effect 232 is equivalent to manually defining each macro listed below. 233 234**_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS**: 235 This macro is used to re-enable redundant members of `allocator<T>`, 236 including `pointer`, `reference`, `rebind`, `address`, `max_size`, 237 `construct`, `destroy`, and the two-argument overload of `allocate`. 238 239**_LIBCPP_ENABLE_CXX20_REMOVED_BINDER_TYPEDEFS**: 240 This macro is used to re-enable the `argument_type`, `result_type`, 241 `first_argument_type`, and `second_argument_type` members of class 242 templates such as `plus`, `logical_not`, `hash`, and `owner_less`. 243 244**_LIBCPP_ENABLE_CXX20_REMOVED_NEGATORS**: 245 This macro is used to re-enable `not1`, `not2`, `unary_negate`, 246 and `binary_negate`. 247 248**_LIBCPP_ENABLE_CXX20_REMOVED_RAW_STORAGE_ITERATOR**: 249 This macro is used to re-enable `raw_storage_iterator`. 250 251**_LIBCPP_ENABLE_CXX20_REMOVED_TYPE_TRAITS**: 252 This macro is used to re-enable `is_literal_type`, `is_literal_type_v`, 253 `result_of` and `result_of_t`. 254 255 256Libc++ Extensions 257================= 258 259This section documents various extensions provided by libc++, how they're 260provided, and any information regarding how to use them. 261 262.. _nodiscard extension: 263 264Extended applications of ``[[nodiscard]]`` 265------------------------------------------ 266 267The ``[[nodiscard]]`` attribute is intended to help users find bugs where 268function return values are ignored when they shouldn't be. After C++17 the 269C++ standard has started to declared such library functions as ``[[nodiscard]]``. 270However, this application is limited and applies only to dialects after C++17. 271Users who want help diagnosing misuses of STL functions may desire a more 272liberal application of ``[[nodiscard]]``. 273 274For this reason libc++ provides an extension that does just that! The 275extension must be enabled by defining ``_LIBCPP_ENABLE_NODISCARD``. The extended 276applications of ``[[nodiscard]]`` takes two forms: 277 2781. Backporting ``[[nodiscard]]`` to entities declared as such by the 279 standard in newer dialects, but not in the present one. 280 2812. Extended applications of ``[[nodiscard]]``, at the library's discretion, 282 applied to entities never declared as such by the standard. 283 284Users may also opt-out of additional applications ``[[nodiscard]]`` using 285additional macros. 286 287Applications of the first form, which backport ``[[nodiscard]]`` from a newer 288dialect, may be disabled using macros specific to the dialect in which it was 289added. For example, ``_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17``. 290 291Applications of the second form, which are pure extensions, may be disabled 292by defining ``_LIBCPP_DISABLE_NODISCARD_EXT``. 293 294 295Entities declared with ``_LIBCPP_NODISCARD_EXT`` 296~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 297 298This section lists all extended applications of ``[[nodiscard]]`` to entities 299which no dialect declares as such (See the second form described above). 300 301* ``adjacent_find`` 302* ``all_of`` 303* ``any_of`` 304* ``binary_search`` 305* ``clamp`` 306* ``count_if`` 307* ``count`` 308* ``equal_range`` 309* ``equal`` 310* ``find_end`` 311* ``find_first_of`` 312* ``find_if_not`` 313* ``find_if`` 314* ``find`` 315* ``get_temporary_buffer`` 316* ``includes`` 317* ``is_heap_until`` 318* ``is_heap`` 319* ``is_partitioned`` 320* ``is_permutation`` 321* ``is_sorted_until`` 322* ``is_sorted`` 323* ``lexicographical_compare`` 324* ``lower_bound`` 325* ``max_element`` 326* ``max`` 327* ``min_element`` 328* ``min`` 329* ``minmax_element`` 330* ``minmax`` 331* ``mismatch`` 332* ``none_of`` 333* ``remove_if`` 334* ``remove`` 335* ``search_n`` 336* ``search`` 337* ``unique`` 338* ``upper_bound`` 339* ``lock_guard``'s constructors 340* ``as_const`` 341* ``forward`` 342* ``move`` 343* ``move_if_noexcept`` 344* ``identity::operator()`` 345* ``to_integer`` 346* ``to_underlying`` 347