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 OS X 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 OS X) 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 52 53Using ``<filesystem>`` and libc++fs 54==================================== 55 56Libc++ provides the implementation of the filesystem library in a separate 57library. Users of ``<filesystem>`` and ``<experimental/filesystem>`` are 58required to link ``-lc++fs``. 59 60.. note:: 61 Prior to libc++ 7.0, users of ``<experimental/filesystem>`` were required 62 to link libc++experimental. 63 64.. warning:: 65 The Filesystem library is still experimental in nature. As such normal 66 guarantees about ABI stability and backwards compatibility do not yet apply 67 to it. In the future, this restriction will be removed. 68 69 70Using libc++experimental and ``<experimental/...>`` 71===================================================== 72 73Libc++ provides implementations of experimental technical specifications 74in a separate library, ``libc++experimental.a``. Users of ``<experimental/...>`` 75headers may be required to link ``-lc++experimental``. 76 77.. code-block:: bash 78 79 $ clang++ -std=c++14 -stdlib=libc++ test.cpp -lc++experimental 80 81Libc++experimental.a may not always be available, even when libc++ is already 82installed. For information on building libc++experimental from source see 83:ref:`Building Libc++ <build instructions>` and 84:ref:`libc++experimental CMake Options <libc++experimental options>`. 85 86Note that as of libc++ 7.0 using the ``<experimental/filesystem>`` requires linking 87libc++fs instead of libc++experimental. 88 89Also see the `Experimental Library Implementation Status <http://libcxx.llvm.org/ts1z_status.html>`__ 90page. 91 92.. warning:: 93 Experimental libraries are Experimental. 94 * The contents of the ``<experimental/...>`` headers and ``libc++experimental.a`` 95 library will not remain compatible between versions. 96 * No guarantees of API or ABI stability are provided. 97 98Using libc++ on Linux 99===================== 100 101On Linux libc++ can typically be used with only '-stdlib=libc++'. However 102some libc++ installations require the user manually link libc++abi themselves. 103If you are running into linker errors when using libc++ try adding '-lc++abi' 104to the link line. For example: 105 106.. code-block:: bash 107 108 $ clang++ -stdlib=libc++ test.cpp -lc++ -lc++abi -lm -lc -lgcc_s -lgcc 109 110Alternately, you could just add libc++abi to your libraries list, which in 111most situations will give the same result: 112 113.. code-block:: bash 114 115 $ clang++ -stdlib=libc++ test.cpp -lc++abi 116 117 118Using libc++ with GCC 119--------------------- 120 121GCC does not provide a way to switch from libstdc++ to libc++. You must manually 122configure the compile and link commands. 123 124In particular you must tell GCC to remove the libstdc++ include directories 125using ``-nostdinc++`` and to not link libstdc++.so using ``-nodefaultlibs``. 126 127Note that ``-nodefaultlibs`` removes all of the standard system libraries and 128not just libstdc++ so they must be manually linked. For example: 129 130.. code-block:: bash 131 132 $ g++ -nostdinc++ -I<libcxx-install-prefix>/include/c++/v1 \ 133 test.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc 134 135 136GDB Pretty printers for libc++ 137------------------------------ 138 139GDB does not support pretty-printing of libc++ symbols by default. Unfortunately 140libc++ does not provide pretty-printers itself. However there are 3rd 141party implementations available and although they are not officially 142supported by libc++ they may be useful to users. 143 144Known 3rd Party Implementations Include: 145 146* `Koutheir's libc++ pretty-printers <https://github.com/koutheir/libcxx-pretty-printers>`_. 147 148 149Libc++ Configuration Macros 150=========================== 151 152Libc++ provides a number of configuration macros which can be used to enable 153or disable extended libc++ behavior, including enabling "debug mode" or 154thread safety annotations. 155 156**_LIBCPP_DEBUG**: 157 See :ref:`using-debug-mode` for more information. 158 159**_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS**: 160 This macro is used to enable -Wthread-safety annotations on libc++'s 161 ``std::mutex`` and ``std::lock_guard``. By default these annotations are 162 disabled and must be manually enabled by the user. 163 164**_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**: 165 This macro is used to disable all visibility annotations inside libc++. 166 Defining this macro and then building libc++ with hidden visibility gives a 167 build of libc++ which does not export any symbols, which can be useful when 168 building statically for inclusion into another library. 169 170**_LIBCPP_DISABLE_EXTERN_TEMPLATE**: 171 This macro is used to disable extern template declarations in the libc++ 172 headers. The intended use case is for clients who wish to use the libc++ 173 headers without taking a dependency on the libc++ library itself. 174 175**_LIBCPP_ENABLE_TUPLE_IMPLICIT_REDUCED_ARITY_EXTENSION**: 176 This macro is used to re-enable an extension in `std::tuple` which allowed 177 it to be implicitly constructed from fewer initializers than contained 178 elements. Elements without an initializer are default constructed. For example: 179 180 .. code-block:: cpp 181 182 std::tuple<std::string, int, std::error_code> foo() { 183 return {"hello world", 42}; // default constructs error_code 184 } 185 186 187 Since libc++ 4.0 this extension has been disabled by default. This macro 188 may be defined to re-enable it in order to support existing code that depends 189 on the extension. New use of this extension should be discouraged. 190 See `PR 27374 <http://llvm.org/PR27374>`_ for more information. 191 192 Note: The "reduced-arity-initialization" extension is still offered but only 193 for explicit conversions. Example: 194 195 .. code-block:: cpp 196 197 auto foo() { 198 using Tup = std::tuple<std::string, int, std::error_code>; 199 return Tup{"hello world", 42}; // explicit constructor called. OK. 200 } 201 202**_LIBCPP_DISABLE_ADDITIONAL_DIAGNOSTICS**: 203 This macro disables the additional diagnostics generated by libc++ using the 204 `diagnose_if` attribute. These additional diagnostics include checks for: 205 206 * Giving `set`, `map`, `multiset`, `multimap` and their `unordered_` 207 counterparts a comparator which is not const callable. 208 * Giving an unordered associative container a hasher that is not const 209 callable. 210 211**_LIBCPP_NO_VCRUNTIME**: 212 Microsoft's C and C++ headers are fairly entangled, and some of their C++ 213 headers are fairly hard to avoid. In particular, `vcruntime_new.h` gets pulled 214 in from a lot of other headers and provides definitions which clash with 215 libc++ headers, such as `nothrow_t` (note that `nothrow_t` is a struct, so 216 there's no way for libc++ to provide a compatible definition, since you can't 217 have multiple definitions). 218 219 By default, libc++ solves this problem by deferring to Microsoft's vcruntime 220 headers where needed. However, it may be undesirable to depend on vcruntime 221 headers, since they may not always be available in cross-compilation setups, 222 or they may clash with other headers. The `_LIBCPP_NO_VCRUNTIME` macro 223 prevents libc++ from depending on vcruntime headers. Consequently, it also 224 prevents libc++ headers from being interoperable with vcruntime headers (from 225 the aforementioned clashes), so users of this macro are promising to not 226 attempt to combine libc++ headers with the problematic vcruntime headers. This 227 macro also currently prevents certain `operator new`/`operator delete` 228 replacement scenarios from working, e.g. replacing `operator new` and 229 expecting a non-replaced `operator new[]` to call the replaced `operator new`. 230 231**_LIBCPP_ENABLE_NODISCARD**: 232 Allow the library to add ``[[nodiscard]]`` attributes to entities not specified 233 as ``[[nodiscard]]`` by the current language dialect. This includes 234 backporting applications of ``[[nodiscard]]`` from newer dialects and 235 additional extended applications at the discretion of the library. All 236 additional applications of ``[[nodiscard]]`` are disabled by default. 237 See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` for 238 more information. 239 240**_LIBCPP_DISABLE_NODISCARD_EXT**: 241 This macro prevents the library from applying ``[[nodiscard]]`` to entities 242 purely as an extension. See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` 243 for more information. 244 245**_LIBCPP_ENABLE_DEPRECATION_WARNINGS**: 246 This macro enables warnings when using deprecated components. For example, 247 when compiling in C++11 mode, using `std::auto_ptr` with the macro defined 248 will trigger a warning saying that `std::auto_ptr` is deprecated. By default, 249 this macro is not defined. 250 251C++17 Specific Configuration Macros 252----------------------------------- 253**_LIBCPP_ENABLE_CXX17_REMOVED_FEATURES**: 254 This macro is used to re-enable all the features removed in C++17. The effect 255 is equivalent to manually defining each macro listed below. 256 257**_LIBCPP_ENABLE_CXX17_REMOVED_UNEXPECTED_FUNCTIONS**: 258 This macro is used to re-enable the `set_unexpected`, `get_unexpected`, and 259 `unexpected` functions, which were removed in C++17. 260 261**_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**: 262 This macro is used to re-enable `std::auto_ptr` in C++17. 263 264C++2a Specific Configuration Macros: 265------------------------------------ 266**_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17**: 267 This macro can be used to disable diagnostics emitted from functions marked 268 ``[[nodiscard]]`` in dialects after C++17. See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` 269 for more information. 270 271 272Libc++ Extensions 273================= 274 275This section documents various extensions provided by libc++, how they're 276provided, and any information regarding how to use them. 277 278.. _nodiscard extension: 279 280Extended applications of ``[[nodiscard]]`` 281------------------------------------------ 282 283The ``[[nodiscard]]`` attribute is intended to help users find bugs where 284function return values are ignored when they shouldn't be. After C++17 the 285C++ standard has started to declared such library functions as ``[[nodiscard]]``. 286However, this application is limited and applies only to dialects after C++17. 287Users who want help diagnosing misuses of STL functions may desire a more 288liberal application of ``[[nodiscard]]``. 289 290For this reason libc++ provides an extension that does just that! The 291extension must be enabled by defining ``_LIBCPP_ENABLE_NODISCARD``. The extended 292applications of ``[[nodiscard]]`` takes two forms: 293 2941. Backporting ``[[nodiscard]]`` to entities declared as such by the 295 standard in newer dialects, but not in the present one. 296 2972. Extended applications of ``[[nodiscard]]``, at the libraries discretion, 298 applied to entities never declared as such by the standard. 299 300Users may also opt-out of additional applications ``[[nodiscard]]`` using 301additional macros. 302 303Applications of the first form, which backport ``[[nodiscard]]`` from a newer 304dialect may be disabled using macros specific to the dialect it was added. For 305example ``_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17``. 306 307Applications of the second form, which are pure extensions, may be disabled 308by defining ``_LIBCPP_DISABLE_NODISCARD_EXT``. 309 310 311Entities declared with ``_LIBCPP_NODISCARD_EXT`` 312~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 313 314This section lists all extended applications of ``[[nodiscard]]`` to entities 315which no dialect declares as such (See the second form described above). 316 317* ``get_temporary_buffer`` 318