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
52
53
54Using libc++ on Linux
55=====================
56
57On Linux libc++ can typically be used with only '-stdlib=libc++'. However
58some libc++ installations require the user manually link libc++abi themselves.
59If you are running into linker errors when using libc++ try adding '-lc++abi'
60to the link line.  For example:
61
62.. code-block:: bash
63
64  $ clang++ -stdlib=libc++ test.cpp -lc++ -lc++abi -lm -lc -lgcc_s -lgcc
65
66Alternately, you could just add libc++abi to your libraries list, which in
67most situations will give the same result:
68
69.. code-block:: bash
70
71  $ clang++ -stdlib=libc++ test.cpp -lc++abi
72
73
74Using libc++ with GCC
75---------------------
76
77GCC does not provide a way to switch from libstdc++ to libc++. You must manually
78configure the compile and link commands.
79
80In particular you must tell GCC to remove the libstdc++ include directories
81using ``-nostdinc++`` and to not link libstdc++.so using ``-nodefaultlibs``.
82
83Note that ``-nodefaultlibs`` removes all of the standard system libraries and
84not 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
90