Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 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 | |
| 53 | |
| 54 | Using libc++ on Linux |
| 55 | ===================== |
| 56 | |
Eric Fiselier | bb856cc | 2015-10-15 22:41:51 +0000 | [diff] [blame] | 57 | On Linux libc++ can typically be used with only '-stdlib=libc++'. However |
| 58 | some libc++ installations require the user manually link libc++abi themselves. |
| 59 | If you are running into linker errors when using libc++ try adding '-lc++abi' |
| 60 | to the link line. For example: |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 61 | |
| 62 | .. code-block:: bash |
| 63 | |
| 64 | $ clang++ -stdlib=libc++ test.cpp -lc++ -lc++abi -lm -lc -lgcc_s -lgcc |
| 65 | |
| 66 | Alternately, you could just add libc++abi to your libraries list, which in |
| 67 | most situations will give the same result: |
| 68 | |
| 69 | .. code-block:: bash |
| 70 | |
| 71 | $ clang++ -stdlib=libc++ test.cpp -lc++abi |
| 72 | |
| 73 | |
| 74 | Using libc++ with GCC |
| 75 | --------------------- |
| 76 | |
| 77 | GCC does not provide a way to switch from libstdc++ to libc++. You must manually |
| 78 | configure the compile and link commands. |
| 79 | |
| 80 | In particular you must tell GCC to remove the libstdc++ include directories |
| 81 | using ``-nostdinc++`` and to not link libstdc++.so using ``-nodefaultlibs``. |
| 82 | |
| 83 | Note that ``-nodefaultlibs`` removes all of the standard system libraries and |
| 84 | not just libstdc++ so they must be manually linked. For example: |
| 85 | |
| 86 | .. code-block:: bash |
| 87 | |
| 88 | $ g++ -nostdinc++ -I<libcxx-install-prefix>/include/c++/v1 \ |
| 89 | test.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc |
Eric Fiselier | 14a9008 | 2016-01-20 01:26:30 +0000 | [diff] [blame^] | 90 | |
| 91 | |
| 92 | GDB Pretty printers for libc++ |
| 93 | ------------------------------ |
| 94 | |
| 95 | GDB does not support pretty-printing of libc++ symbols by default. Unfortunately |
| 96 | libc++ does not provide pretty-printers itself. However there are 3rd |
| 97 | party implementations available and although they are not officially |
| 98 | supported by libc++ they may be useful to users. |
| 99 | |
| 100 | Known 3rd Party Implementations Include: |
| 101 | |
| 102 | * `Koutheir's libc++ pretty-printers <https://github.com/koutheir/libcxx-pretty-printers>`_. |