docs/UsingLibcxx.rst

   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 **_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
 208 C++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.