1 ============ 2 Using libc++ 3 ============ 4 5 .. contents:: 6 :local: 7 8 Getting Started 9 =============== 10 11 If 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 18 On macOS and FreeBSD libc++ is the default standard library 19 and the ``-stdlib=libc++`` is not required. 20 21 .. _alternate libcxx: 22 23 If you want to select an alternate installation of libc++ you 24 can 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 34 The option ``-Wl,-rpath,<libcxx-install-prefix>/lib`` adds a runtime library 35 search path. Meaning that the systems dynamic linker will look for libc++ in 36 ``<libcxx-install-prefix>/lib`` whenever the program is run. Alternatively the 37 environment variable ``LD_LIBRARY_PATH`` (``DYLD_LIBRARY_PATH`` on macOS) can 38 be used to change the dynamic linkers search paths after a program is compiled. 39 40 An 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 52 Using ``<filesystem>`` 53 ====================== 54 55 Prior to LLVM 9.0, libc++ provides the implementation of the filesystem library 56 in a separate static library. Users of ``<filesystem>`` and ``<experimental/filesystem>`` 57 are required to link ``-lc++fs``. Prior to libc++ 7.0, users of 58 ``<experimental/filesystem>`` were required to link libc++experimental. 59 60 Starting with LLVM 9.0, support for ``<filesystem>`` is provided in the main 61 library and nothing special is required to use ``<filesystem>``. 62 63 Using libc++experimental and ``<experimental/...>`` 64 ===================================================== 65 66 Libc++ provides implementations of experimental technical specifications 67 in a separate library, ``libc++experimental.a``. Users of ``<experimental/...>`` 68 headers 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 74 Libc++experimental.a may not always be available, even when libc++ is already 75 installed. 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 79 Also see the `Experimental Library Implementation Status <http://libcxx.llvm.org/ts1z_status.html>`__ 80 page. 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 91 Using libc++ on Linux 92 ===================== 93 94 On Linux libc++ can typically be used with only '-stdlib=libc++'. However 95 some libc++ installations require the user manually link libc++abi themselves. 96 If you are running into linker errors when using libc++ try adding '-lc++abi' 97 to 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 103 Alternately, you could just add libc++abi to your libraries list, which in 104 most situations will give the same result: 105 106 .. code-block:: bash 107 108 $ clang++ -stdlib=libc++ test.cpp -lc++abi 109 110 111 Using libc++ with GCC 112 --------------------- 113 114 GCC does not provide a way to switch from libstdc++ to libc++. You must manually 115 configure the compile and link commands. 116 117 In particular, you must tell GCC to remove the libstdc++ include directories 118 using ``-nostdinc++`` and to not link libstdc++.so using ``-nodefaultlibs``. 119 120 Note that ``-nodefaultlibs`` removes all the standard system libraries and 121 not 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 129 GDB Pretty printers for libc++ 130 ------------------------------ 131 132 GDB does not support pretty-printing of libc++ symbols by default. Unfortunately 133 libc++ does not provide pretty-printers itself. However there are 3rd 134 party implementations available and although they are not officially 135 supported by libc++ they may be useful to users. 136 137 Known 3rd Party Implementations Include: 138 139 * `Koutheir's libc++ pretty-printers <https://github.com/koutheir/libcxx-pretty-printers>`_. 140 141 142 Libc++ Configuration Macros 143 =========================== 144 145 Libc++ provides a number of configuration macros which can be used to enable 146 or disable extended libc++ behavior, including enabling "debug mode" or 147 thread 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_DISABLE_ADDITIONAL_DIAGNOSTICS**: 169 This macro disables the additional diagnostics generated by libc++ using the 170 `diagnose_if` attribute. These additional diagnostics include checks for: 171 172 * Giving `set`, `map`, `multiset`, `multimap` and their `unordered_` 173 counterparts a comparator which is not const callable. 174 * Giving an unordered associative container a hasher that is not const 175 callable. 176 177 **_LIBCPP_NO_VCRUNTIME**: 178 Microsoft's C and C++ headers are fairly entangled, and some of their C++ 179 headers are fairly hard to avoid. In particular, `vcruntime_new.h` gets pulled 180 in from a lot of other headers and provides definitions which clash with 181 libc++ headers, such as `nothrow_t` (note that `nothrow_t` is a struct, so 182 there's no way for libc++ to provide a compatible definition, since you can't 183 have multiple definitions). 184 185 By default, libc++ solves this problem by deferring to Microsoft's vcruntime 186 headers where needed. However, it may be undesirable to depend on vcruntime 187 headers, since they may not always be available in cross-compilation setups, 188 or they may clash with other headers. The `_LIBCPP_NO_VCRUNTIME` macro 189 prevents libc++ from depending on vcruntime headers. Consequently, it also 190 prevents libc++ headers from being interoperable with vcruntime headers (from 191 the aforementioned clashes), so users of this macro are promising to not 192 attempt to combine libc++ headers with the problematic vcruntime headers. This 193 macro also currently prevents certain `operator new`/`operator delete` 194 replacement scenarios from working, e.g. replacing `operator new` and 195 expecting a non-replaced `operator new[]` to call the replaced `operator new`. 196 197 **_LIBCPP_ENABLE_NODISCARD**: 198 Allow the library to add ``[[nodiscard]]`` attributes to entities not specified 199 as ``[[nodiscard]]`` by the current language dialect. This includes 200 backporting applications of ``[[nodiscard]]`` from newer dialects and 201 additional extended applications at the discretion of the library. All 202 additional applications of ``[[nodiscard]]`` are disabled by default. 203 See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` for 204 more information. 205 206 **_LIBCPP_DISABLE_NODISCARD_EXT**: 207 This macro prevents the library from applying ``[[nodiscard]]`` to entities 208 purely as an extension. See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` 209 for more information. 210 211 **_LIBCPP_DISABLE_DEPRECATION_WARNINGS**: 212 This macro disables warnings when using deprecated components. For example, 213 using `std::auto_ptr` when compiling in C++11 mode will normally trigger a 214 warning saying that `std::auto_ptr` is deprecated. If the macro is defined, 215 no warning will be emitted. By default, this macro is not defined. 216 217 C++17 Specific Configuration Macros 218 ----------------------------------- 219 **_LIBCPP_ENABLE_CXX17_REMOVED_FEATURES**: 220 This macro is used to re-enable all the features removed in C++17. The effect 221 is equivalent to manually defining each macro listed below. 222 223 **_LIBCPP_ENABLE_CXX17_REMOVED_UNEXPECTED_FUNCTIONS**: 224 This macro is used to re-enable the `set_unexpected`, `get_unexpected`, and 225 `unexpected` functions, which were removed in C++17. 226 227 **_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**: 228 This macro is used to re-enable `std::auto_ptr` in C++17. 229 230 C++20 Specific Configuration Macros: 231 ------------------------------------ 232 **_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17**: 233 This macro can be used to disable diagnostics emitted from functions marked 234 ``[[nodiscard]]`` in dialects after C++17. See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` 235 for more information. 236 237 238 Libc++ Extensions 239 ================= 240 241 This section documents various extensions provided by libc++, how they're 242 provided, and any information regarding how to use them. 243 244 .. _nodiscard extension: 245 246 Extended applications of ``[[nodiscard]]`` 247 ------------------------------------------ 248 249 The ``[[nodiscard]]`` attribute is intended to help users find bugs where 250 function return values are ignored when they shouldn't be. After C++17 the 251 C++ standard has started to declared such library functions as ``[[nodiscard]]``. 252 However, this application is limited and applies only to dialects after C++17. 253 Users who want help diagnosing misuses of STL functions may desire a more 254 liberal application of ``[[nodiscard]]``. 255 256 For this reason libc++ provides an extension that does just that! The 257 extension must be enabled by defining ``_LIBCPP_ENABLE_NODISCARD``. The extended 258 applications of ``[[nodiscard]]`` takes two forms: 259 260 1. Backporting ``[[nodiscard]]`` to entities declared as such by the 261 standard in newer dialects, but not in the present one. 262 263 2. Extended applications of ``[[nodiscard]]``, at the library's discretion, 264 applied to entities never declared as such by the standard. 265 266 Users may also opt-out of additional applications ``[[nodiscard]]`` using 267 additional macros. 268 269 Applications of the first form, which backport ``[[nodiscard]]`` from a newer 270 dialect, may be disabled using macros specific to the dialect in which it was 271 added. For example, ``_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17``. 272 273 Applications of the second form, which are pure extensions, may be disabled 274 by defining ``_LIBCPP_DISABLE_NODISCARD_EXT``. 275 276 277 Entities declared with ``_LIBCPP_NODISCARD_EXT`` 278 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 279 280 This section lists all extended applications of ``[[nodiscard]]`` to entities 281 which no dialect declares as such (See the second form described above). 282 283 * ``adjacent_find`` 284 * ``all_of`` 285 * ``any_of`` 286 * ``binary_search`` 287 * ``clamp`` 288 * ``count_if`` 289 * ``count`` 290 * ``equal_range`` 291 * ``equal`` 292 * ``find_end`` 293 * ``find_first_of`` 294 * ``find_if_not`` 295 * ``find_if`` 296 * ``find`` 297 * ``get_temporary_buffer`` 298 * ``includes`` 299 * ``is_heap_until`` 300 * ``is_heap`` 301 * ``is_partitioned`` 302 * ``is_permutation`` 303 * ``is_sorted_until`` 304 * ``is_sorted`` 305 * ``lexicographical_compare`` 306 * ``lower_bound`` 307 * ``max_element`` 308 * ``max`` 309 * ``min_element`` 310 * ``min`` 311 * ``minmax_element`` 312 * ``minmax`` 313 * ``mismatch`` 314 * ``none_of`` 315 * ``remove_if`` 316 * ``remove`` 317 * ``search_n`` 318 * ``search`` 319 * ``unique`` 320 * ``upper_bound`` 321 * ``lock_guard``'s constructors 322 * ``as_const`` 323 * ``forward`` 324 * ``move`` 325 * ``move_if_noexcept`` 326 * ``identity::operator()`` 327 * ``to_integer`` 328 * ``to_underlying`` 329
Indexes created Thu Apr 16 00:22:31 UTC 2026