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 OS X 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 OS X) 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 libc++experimental and ``<experimental/...>`` 53 ===================================================== 54 55 Libc++ provides implementations of experimental technical specifications 56 in a separate library, ``libc++experimental.a``. Users of ``<experimental/...>`` 57 headers may be required to link ``-lc++experimental``. 58 59 .. code-block:: bash 60 61 $ clang++ -std=c++14 -stdlib=libc++ test.cpp -lc++experimental 62 63 Libc++experimental.a may not always be available, even when libc++ is already 64 installed. For information on building libc++experimental from source see 65 :ref:`Building Libc++ <build instructions>` and 66 :ref:`libc++experimental CMake Options <libc++experimental options>`. 67 68 Also see the `Experimental Library Implementation Status <http://libcxx.llvm.org/ts1z_status.html>`__ 69 page. 70 71 .. warning:: 72 Experimental libraries are Experimental. 73 * The contents of the ``<experimental/...>`` headers and ``libc++experimental.a`` 74 library will not remain compatible between versions. 75 * No guarantees of API or ABI stability are provided. 76 77 Using libc++ on Linux 78 ===================== 79 80 On Linux libc++ can typically be used with only '-stdlib=libc++'. However 81 some libc++ installations require the user manually link libc++abi themselves. 82 If you are running into linker errors when using libc++ try adding '-lc++abi' 83 to the link line. For example: 84 85 .. code-block:: bash 86 87 $ clang++ -stdlib=libc++ test.cpp -lc++ -lc++abi -lm -lc -lgcc_s -lgcc 88 89 Alternately, you could just add libc++abi to your libraries list, which in 90 most situations will give the same result: 91 92 .. code-block:: bash 93 94 $ clang++ -stdlib=libc++ test.cpp -lc++abi 95 96 97 Using libc++ with GCC 98 --------------------- 99 100 GCC does not provide a way to switch from libstdc++ to libc++. You must manually 101 configure the compile and link commands. 102 103 In particular you must tell GCC to remove the libstdc++ include directories 104 using ``-nostdinc++`` and to not link libstdc++.so using ``-nodefaultlibs``. 105 106 Note that ``-nodefaultlibs`` removes all of the standard system libraries and 107 not just libstdc++ so they must be manually linked. For example: 108 109 .. code-block:: bash 110 111 $ g++ -nostdinc++ -I<libcxx-install-prefix>/include/c++/v1 \ 112 test.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc 113 114 115 GDB Pretty printers for libc++ 116 ------------------------------ 117 118 GDB does not support pretty-printing of libc++ symbols by default. Unfortunately 119 libc++ does not provide pretty-printers itself. However there are 3rd 120 party implementations available and although they are not officially 121 supported by libc++ they may be useful to users. 122 123 Known 3rd Party Implementations Include: 124 125 * `Koutheir's libc++ pretty-printers <https://github.com/koutheir/libcxx-pretty-printers>`_. 126 127 128 Libc++ Configuration Macros 129 =========================== 130 131 Libc++ provides a number of configuration macros which can be used to enable 132 or disable extended libc++ behavior, including enabling "debug mode" or 133 thread safety annotations. 134 135 **_LIBCPP_DEBUG**: 136 See :ref:`using-debug-mode` for more information. 137 138 **_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS**: 139 This macro is used to enable -Wthread-safety annotations on libc++'s 140 ``std::mutex`` and ``std::lock_guard``. By default these annotations are 141 disabled and must be manually enabled by the user. 142 143 **_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**: 144 This macro is used to disable all visibility annotations inside libc++. 145 Defining this macro and then building libc++ with hidden visibility gives a 146 build of libc++ which does not export any symbols, which can be useful when 147 building statically for inclusion into another library. 148 149 **_LIBCPP_DISABLE_EXTERN_TEMPLATE**: 150 This macro is used to disable extern template declarations in the libc++ 151 headers. The intended use case is for clients who wish to use the libc++ 152 headers without taking a dependency on the libc++ library itself. 153 154 **_LIBCPP_ENABLE_TUPLE_IMPLICIT_REDUCED_ARITY_EXTENSION**: 155 This macro is used to re-enable an extension in `std::tuple` which allowed 156 it to be implicitly constructed from fewer initializers than contained 157 elements. Elements without an initializer are default constructed. For example: 158 159 .. code-block:: cpp 160 161 std::tuple<std::string, int, std::error_code> foo() { 162 return {"hello world", 42}; // default constructs error_code 163 } 164 165 166 Since libc++ 4.0 this extension has been disabled by default. This macro 167 may be defined to re-enable it in order to support existing code that depends 168 on the extension. New use of this extension should be discouraged. 169 See `PR 27374 <http://llvm.org/PR27374>`_ for more information. 170 171 Note: The "reduced-arity-initialization" extension is still offered but only 172 for explicit conversions. Example: 173 174 .. code-block:: cpp 175 176 auto foo() { 177 using Tup = std::tuple<std::string, int, std::error_code>; 178 return Tup{"hello world", 42}; // explicit constructor called. OK. 179 } 180 181 **_LIBCPP_DISABLE_ADDITIONAL_DIAGNOSTICS**: 182 This macro disables the additional diagnostics generated by libc++ using the 183 `diagnose_if` attribute. These additional diagnostics include checks for: 184 185 * Giving `set`, `map`, `multiset`, `multimap` a comparator which is not 186 const callable. 187 188 C++17 Specific Configuration Macros 189 ----------------------------------- 190 **_LIBCPP_ENABLE_CXX17_REMOVED_FEATURES**: 191 This macro is used to re-enable all the features removed in C++17. The effect 192 is equivalent to manually defining each macro listed below. 193 194 **_LIBCPP_ENABLE_CXX17_REMOVED_UNEXPECTED_FUNCTIONS**: 195 This macro is used to re-enable the `set_unexpected`, `get_unexpected`, and 196 `unexpected` functions, which were removed in C++17. 197 198 **_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**: 199 This macro is used to re-enable `std::auto_ptr` in C++17. 200
