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_ENABLE_TUPLE_IMPLICIT_REDUCED_ARITY_EXTENSION**:
150  This macro is used to re-enable an extension in `std::tuple` which allowed
151  it to be implicitly constructed from fewer initializers than contained
152  elements. Elements without an initializer are default constructed. For example:
153
154  .. code-block:: cpp
155
156    std::tuple<std::string, int, std::error_code> foo() {
157      return {"hello world", 42}; // default constructs error_code
158    }
159
160
161  Since libc++ 4.0 this extension has been disabled by default. This macro
162  may be defined to re-enable it in order to support existing code that depends
163  on the extension. New use of this extension should be discouraged.
164  See `PR 27374 <http://llvm.org/PR27374>`_ for more information.
165
166  Note: The "reduced-arity-initialization" extension is still offered but only
167  for explicit conversions. Example:
168
169  .. code-block:: cpp
170
171    auto foo() {
172      using Tup = std::tuple<std::string, int, std::error_code>;
173      return Tup{"hello world", 42}; // explicit constructor called. OK.
174    }
175
176**_LIBCPP_DISABLE_ADDITIONAL_DIAGNOSTICS**:
177  This macro disables the additional diagnostics generated by libc++ using the
178  `diagnose_if` attribute. These additional diagnostics include checks for:
179
180    * Giving `set`, `map`, `multiset`, `multimap` a comparator which is not
181      const callable.
182
183C++17 Specific Configuration Macros
184-----------------------------------
185**_LIBCPP_ENABLE_CXX17_REMOVED_FEATURES**:
186  This macro is used to re-enable all the features removed in C++17. The effect
187  is equivalent to manually defining each macro listed below.
188
189**_LIBCPP_ENABLE_CXX17_REMOVED_UNEXPECTED_FUNCTIONS**:
190  This macro is used to re-enable the `set_unexpected`, `get_unexpected`, and
191  `unexpected` functions, which were removed in C++17.
192
193**_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**:
194  This macro is used to re-enable `std::auto_ptr` in C++17.
195