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
