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
52Using libc++experimental and ``<experimental/...>``
53=====================================================
54
55Libc++ provides implementations of experimental technical specifications
56in a separate library, ``libc++experimental.a``. Users of ``<experimental/...>``
57headers 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
63Libc++experimental.a may not always be available, even when libc++ is already
64installed. 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
68Also see the `Experimental Library Implementation Status <http://libcxx.llvm.org/ts1z_status.html>`__
69page.
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
77Using libc++ on Linux
78=====================
79
80On Linux libc++ can typically be used with only '-stdlib=libc++'. However
81some libc++ installations require the user manually link libc++abi themselves.
82If you are running into linker errors when using libc++ try adding '-lc++abi'
83to 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
89Alternately, you could just add libc++abi to your libraries list, which in
90most situations will give the same result:
91
92.. code-block:: bash
93
94  $ clang++ -stdlib=libc++ test.cpp -lc++abi
95
96
97Using libc++ with GCC
98---------------------
99
100GCC does not provide a way to switch from libstdc++ to libc++. You must manually
101configure the compile and link commands.
102
103In particular you must tell GCC to remove the libstdc++ include directories
104using ``-nostdinc++`` and to not link libstdc++.so using ``-nodefaultlibs``.
105
106Note that ``-nodefaultlibs`` removes all of the standard system libraries and
107not 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
115GDB Pretty printers for libc++
116------------------------------
117
118GDB does not support pretty-printing of libc++ symbols by default. Unfortunately
119libc++ does not provide pretty-printers itself. However there are 3rd
120party implementations available and although they are not officially
121supported by libc++ they may be useful to users.
122
123Known 3rd Party Implementations Include:
124
125* `Koutheir's libc++ pretty-printers <https://github.com/koutheir/libcxx-pretty-printers>`_.
126
127
128Libc++ Configuration Macros
129===========================
130
131Libc++ provides a number of configuration macros which can be used to enable
132or disable extended libc++ behavior, including enabling "debug mode" or
133thread 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**_LIBCPP_NO_VCRUNTIME**:
189  Microsoft's C and C++ headers are fairly entangled, and some of their C++
190  headers are fairly hard to avoid. In particular, `vcruntime_new.h` gets pulled
191  in from a lot of other headers and provides definitions which clash with
192  libc++ headers, such as `nothrow_t` (note that `nothrow_t` is a struct, so
193  there's no way for libc++ to provide a compatible definition, since you can't
194  have multiple definitions).
195
196  By default, libc++ solves this problem by deferring to Microsoft's vcruntime
197  headers where needed. However, it may be undesirable to depend on vcruntime
198  headers, since they may not always be available in cross-compilation setups,
199  or they may clash with other headers. The `_LIBCPP_NO_VCRUNTIME` macro
200  prevents libc++ from depending on vcruntime headers. Consequently, it also
201  prevents libc++ headers from being interoperable with vcruntime headers (from
202  the aforementioned clashes), so users of this macro are promising to not
203  attempt to combine libc++ headers with the problematic vcruntime headers. This
204  macro also currently prevents certain `operator new`/`operator delete`
205  replacement scenarios from working, e.g. replacing `operator new` and
206  expecting a non-replaced `operator new[]` to call the replaced `operator new`.
207
208C++17 Specific Configuration Macros
209-----------------------------------
210**_LIBCPP_ENABLE_CXX17_REMOVED_FEATURES**:
211  This macro is used to re-enable all the features removed in C++17. The effect
212  is equivalent to manually defining each macro listed below.
213
214**_LIBCPP_ENABLE_CXX17_REMOVED_UNEXPECTED_FUNCTIONS**:
215  This macro is used to re-enable the `set_unexpected`, `get_unexpected`, and
216  `unexpected` functions, which were removed in C++17.
217
218**_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**:
219  This macro is used to re-enable `std::auto_ptr` in C++17.
220