Howard Hinnant | d2bb032 | 2010-08-22 01:04:38 +0000 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
Howard Hinnant | bc8d3f9 | 2010-05-11 19:42:16 +0000 | [diff] [blame] | 2 | "http://www.w3.org/TR/html4/strict.dtd"> |
| 3 | <!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ --> |
| 4 | <html> |
| 5 | <head> |
| 6 | <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| 7 | <title>"libc++" C++ Standard Library</title> |
| 8 | <link type="text/css" rel="stylesheet" href="menu.css"> |
| 9 | <link type="text/css" rel="stylesheet" href="content.css"> |
| 10 | </head> |
| 11 | |
| 12 | <body> |
| 13 | <div id="menu"> |
| 14 | <div> |
| 15 | <a href="http://llvm.org/">LLVM Home</a> |
| 16 | </div> |
Howard Hinnant | d2bb032 | 2010-08-22 01:04:38 +0000 | [diff] [blame] | 17 | |
Howard Hinnant | bc8d3f9 | 2010-05-11 19:42:16 +0000 | [diff] [blame] | 18 | <div class="submenu"> |
| 19 | <label>libc++ Info</label> |
| 20 | <a href="/index.html">About</a> |
| 21 | </div> |
| 22 | |
| 23 | <div class="submenu"> |
| 24 | <label>Quick Links</label> |
Tanya Lattner | d08dbfc | 2015-08-05 03:59:14 +0000 | [diff] [blame] | 25 | <a href="http://lists.llvm.org/mailman/listinfo/cfe-dev">cfe-dev</a> |
| 26 | <a href="http://lists.llvm.org/mailman/listinfo/cfe-commits">cfe-commits</a> |
Howard Hinnant | bc8d3f9 | 2010-05-11 19:42:16 +0000 | [diff] [blame] | 27 | <a href="http://llvm.org/bugs/">Bug Reports</a> |
Howard Hinnant | 76e1ffc | 2010-05-11 20:51:20 +0000 | [diff] [blame] | 28 | <a href="http://llvm.org/svn/llvm-project/libcxx/trunk/">Browse SVN</a> |
| 29 | <a href="http://llvm.org/viewvc/llvm-project/libcxx/trunk/">Browse ViewVC</a> |
Howard Hinnant | bc8d3f9 | 2010-05-11 19:42:16 +0000 | [diff] [blame] | 30 | </div> |
| 31 | </div> |
| 32 | |
| 33 | <div id="content"> |
| 34 | <!--*********************************************************************--> |
| 35 | <h1>"libc++" C++ Standard Library</h1> |
| 36 | <!--*********************************************************************--> |
Howard Hinnant | d2bb032 | 2010-08-22 01:04:38 +0000 | [diff] [blame] | 37 | |
Howard Hinnant | bc8d3f9 | 2010-05-11 19:42:16 +0000 | [diff] [blame] | 38 | <p>libc++ is a new implementation of the C++ standard library, targeting |
Howard Hinnant | af34734 | 2012-07-19 15:57:51 +0000 | [diff] [blame] | 39 | C++11.</p> |
Howard Hinnant | bc8d3f9 | 2010-05-11 19:42:16 +0000 | [diff] [blame] | 40 | |
Chris Lattner | f38bc6e | 2010-11-16 21:40:19 +0000 | [diff] [blame] | 41 | <p>All of the code in libc++ is <a |
| 42 | href="http://llvm.org/docs/DeveloperPolicy.html#license">dual licensed</a> |
| 43 | under the MIT license and the UIUC License (a BSD-like license).</p> |
Howard Hinnant | d2bb032 | 2010-08-22 01:04:38 +0000 | [diff] [blame] | 44 | |
Howard Hinnant | bc8d3f9 | 2010-05-11 19:42:16 +0000 | [diff] [blame] | 45 | <!--=====================================================================--> |
| 46 | <h2 id="goals">Features and Goals</h2> |
| 47 | <!--=====================================================================--> |
Howard Hinnant | d2bb032 | 2010-08-22 01:04:38 +0000 | [diff] [blame] | 48 | |
Howard Hinnant | bc8d3f9 | 2010-05-11 19:42:16 +0000 | [diff] [blame] | 49 | <ul> |
Howard Hinnant | af34734 | 2012-07-19 15:57:51 +0000 | [diff] [blame] | 50 | <li>Correctness as defined by the C++11 standard.</li> |
Howard Hinnant | bc8d3f9 | 2010-05-11 19:42:16 +0000 | [diff] [blame] | 51 | <li>Fast execution.</li> |
| 52 | <li>Minimal memory use.</li> |
| 53 | <li>Fast compile times.</li> |
| 54 | <li>ABI compatibility with gcc's libstdc++ for some low-level features |
| 55 | such as exception objects, rtti and memory allocation.</li> |
| 56 | <li>Extensive unit tests.</li> |
| 57 | </ul> |
| 58 | |
| 59 | <!--=====================================================================--> |
Marshall Clow | faa1716 | 2012-11-14 16:31:15 +0000 | [diff] [blame] | 60 | <h2 id="why">Why a new C++ Standard Library for C++11?</h2> |
Chris Lattner | 24173b8 | 2010-05-12 22:21:15 +0000 | [diff] [blame] | 61 | <!--=====================================================================--> |
Howard Hinnant | d2bb032 | 2010-08-22 01:04:38 +0000 | [diff] [blame] | 62 | |
Chris Lattner | 24173b8 | 2010-05-12 22:21:15 +0000 | [diff] [blame] | 63 | <p>After its initial introduction, many people have asked "why start a new |
| 64 | library instead of contributing to an existing library?" (like Apache's |
| 65 | libstdcxx, GNU's libstdc++, STLport, etc). There are many contributing |
| 66 | reasons, but some of the major ones are:</p> |
Howard Hinnant | d2bb032 | 2010-08-22 01:04:38 +0000 | [diff] [blame] | 67 | |
Chris Lattner | 24173b8 | 2010-05-12 22:21:15 +0000 | [diff] [blame] | 68 | <ul> |
| 69 | <li><p>From years of experience (including having implemented the standard |
| 70 | library before), we've learned many things about implementing |
| 71 | the standard containers which require ABI breakage and fundamental changes |
| 72 | to how they are implemented. For example, it is generally accepted that |
| 73 | building std::string using the "short string optimization" instead of |
| 74 | using Copy On Write (COW) is a superior approach for multicore |
Marshall Clow | faa1716 | 2012-11-14 16:31:15 +0000 | [diff] [blame] | 75 | machines (particularly in C++11, which has rvalue references). Breaking |
Chris Lattner | a5058d9 | 2010-05-12 22:30:22 +0000 | [diff] [blame] | 76 | ABI compatibility with old versions of the library was |
Chris Lattner | 24173b8 | 2010-05-12 22:21:15 +0000 | [diff] [blame] | 77 | determined to be critical to achieving the performance goals of |
| 78 | libc++.</p></li> |
Howard Hinnant | d2bb032 | 2010-08-22 01:04:38 +0000 | [diff] [blame] | 79 | |
Chris Lattner | 24173b8 | 2010-05-12 22:21:15 +0000 | [diff] [blame] | 80 | <li><p>Mainline libstdc++ has switched to GPL3, a license which the developers |
| 81 | of libc++ cannot use. libstdc++ 4.2 (the last GPL2 version) could be |
Marshall Clow | faa1716 | 2012-11-14 16:31:15 +0000 | [diff] [blame] | 82 | independently extended to support C++11, but this would be a fork of the |
Chris Lattner | f338249 | 2010-05-12 22:33:00 +0000 | [diff] [blame] | 83 | codebase (which is often seen as worse for a project than starting a new |
| 84 | independent one). Another problem with libstdc++ is that it is tightly |
| 85 | integrated with G++ development, tending to be tied fairly closely to the |
| 86 | matching version of G++.</p> |
Chris Lattner | 24173b8 | 2010-05-12 22:21:15 +0000 | [diff] [blame] | 87 | </li> |
| 88 | |
| 89 | <li><p>STLport and the Apache libstdcxx library are two other popular |
Marshall Clow | faa1716 | 2012-11-14 16:31:15 +0000 | [diff] [blame] | 90 | candidates, but both lack C++11 support. Our experience (and the |
Howard Hinnant | af34734 | 2012-07-19 15:57:51 +0000 | [diff] [blame] | 91 | experience of libstdc++ developers) is that adding support for C++11 (in |
Chris Lattner | 24173b8 | 2010-05-12 22:21:15 +0000 | [diff] [blame] | 92 | particular rvalue references and move-only types) requires changes to |
| 93 | almost every class and function, essentially amounting to a rewrite. |
Chris Lattner | bfa808e | 2010-05-12 22:34:21 +0000 | [diff] [blame] | 94 | Faced with a rewrite, we decided to start from scratch and evaluate every |
| 95 | design decision from first principles based on experience.</p> |
Howard Hinnant | d2bb032 | 2010-08-22 01:04:38 +0000 | [diff] [blame] | 96 | |
Chris Lattner | 24173b8 | 2010-05-12 22:21:15 +0000 | [diff] [blame] | 97 | <p>Further, both projects are apparently abandoned: STLport 5.2.1 was |
| 98 | released in Oct'08, and STDCXX 4.2.1 in May'08.</p> |
| 99 | |
| 100 | </ul> |
| 101 | |
| 102 | <!--=====================================================================--> |
Howard Hinnant | bc8d3f9 | 2010-05-11 19:42:16 +0000 | [diff] [blame] | 103 | <h2 id="requirements">Platform Support</h2> |
| 104 | <!--=====================================================================--> |
| 105 | |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 106 | <p> |
| 107 | libc++ is known to work on the following platforms, using g++-4.2 and |
| 108 | clang (lack of C++11 language support disables some functionality). Note |
| 109 | that functionality provided by <atomic> is only functional with |
| 110 | clang. |
| 111 | </p> |
Howard Hinnant | bc8d3f9 | 2010-05-11 19:42:16 +0000 | [diff] [blame] | 112 | |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 113 | <ul> |
| 114 | <li>Mac OS X i386</li> |
| 115 | <li>Mac OS X x86_64</li> |
| 116 | <li>FreeBSD 10+ i386</li> |
| 117 | <li>FreeBSD 10+ x86_64</li> |
| 118 | <li>FreeBSD 10+ ARM</li> |
| 119 | </ul> |
Howard Hinnant | bc8d3f9 | 2010-05-11 19:42:16 +0000 | [diff] [blame] | 120 | |
| 121 | <!--=====================================================================--> |
| 122 | <h2 id="dir-structure">Current Status</h2> |
| 123 | <!--=====================================================================--> |
| 124 | |
Howard Hinnant | b0895ff | 2012-11-27 18:52:32 +0000 | [diff] [blame] | 125 | <p>libc++ is a 100% complete C++11 implementation on Apple's OS X. </p> |
Michael J. Spencer | db8a030 | 2012-12-31 19:34:21 +0000 | [diff] [blame] | 126 | <p>LLVM and Clang can self host in C++ and C++11 mode with libc++ on Linux.</p> |
Dan Albert | e3eda9d | 2015-01-30 22:33:41 +0000 | [diff] [blame] | 127 | <p>libc++ is also a 100% complete C++14 implementation. A list of new features and changes for |
Marshall Clow | e4915d9 | 2014-04-03 02:35:29 +0000 | [diff] [blame] | 128 | C++14 can be found <a href="cxx1y_status.html">here</a>.</p> |
Marshall Clow | 1e895c1 | 2014-11-10 15:43:20 +0000 | [diff] [blame] | 129 | <p>A list of features and changes for the next C++ standard, known here as |
| 130 | "C++1z" (probably to be C++17) can be found <a href="cxx1z_status.html">here</a>.</p> |
Marshall Clow | d2f0b5c | 2014-06-02 23:37:13 +0000 | [diff] [blame] | 131 | <p>Implementation of the post-c++14 Technical Specifications is in progress. A list of features and |
| 132 | the current status of these features can be found <a href="ts1z_status.html">here</a>.</p> |
Howard Hinnant | 0cbb3a1 | 2011-09-28 15:44:39 +0000 | [diff] [blame] | 133 | <p> |
Howard Hinnant | ee7a0bf | 2012-07-31 21:30:28 +0000 | [diff] [blame] | 134 | Ports to other platforms are underway. Here are recent test |
| 135 | results for <a href="results.Windows.html">Windows</a> |
| 136 | and <a href="results.Linux.html">Linux</a>. |
Howard Hinnant | 0cbb3a1 | 2011-09-28 15:44:39 +0000 | [diff] [blame] | 137 | </p> |
| 138 | |
Eric Fiselier | caf1c02 | 2014-08-18 05:25:04 +0000 | [diff] [blame] | 139 | <!--======================================================================--> |
Dan Albert | e3eda9d | 2015-01-30 22:33:41 +0000 | [diff] [blame] | 140 | <h2 id="buildbots">Build Bots</h2> |
Eric Fiselier | caf1c02 | 2014-08-18 05:25:04 +0000 | [diff] [blame] | 141 | <!--======================================================================--> |
Eric Fiselier | 453a500 | 2014-12-09 22:53:21 +0000 | [diff] [blame] | 142 | <p>The latest libc++ build results can be found at the following locations.</p> |
Eric Fiselier | caf1c02 | 2014-08-18 05:25:04 +0000 | [diff] [blame] | 143 | <ul> |
Eric Fiselier | 453a500 | 2014-12-09 22:53:21 +0000 | [diff] [blame] | 144 | <li><a href="http://lab.llvm.org:8011/console"> |
| 145 | Buildbot libc++ builders |
Eric Fiselier | caf1c02 | 2014-08-18 05:25:04 +0000 | [diff] [blame] | 146 | </a></li> |
Eric Fiselier | 453a500 | 2014-12-09 22:53:21 +0000 | [diff] [blame] | 147 | <li><a href="http://lab.llvm.org:8080/green/view/Libcxx/"> |
| 148 | Jenkins libc++ builders |
Eric Fiselier | a43d114 | 2014-10-16 02:48:59 +0000 | [diff] [blame] | 149 | </a></li> |
Eric Fiselier | caf1c02 | 2014-08-18 05:25:04 +0000 | [diff] [blame] | 150 | </ul> |
| 151 | |
Howard Hinnant | bc8d3f9 | 2010-05-11 19:42:16 +0000 | [diff] [blame] | 152 | <!--=====================================================================--> |
| 153 | <h2>Get it and get involved!</h2> |
| 154 | <!--=====================================================================--> |
Howard Hinnant | d2bb032 | 2010-08-22 01:04:38 +0000 | [diff] [blame] | 155 | |
Howard Hinnant | 2481cba | 2011-09-30 16:58:02 +0000 | [diff] [blame] | 156 | <p>First please review our |
| 157 | <a href="http://llvm.org/docs/DeveloperPolicy.html">Developer's Policy</a>. |
| 158 | |
Howard Hinnant | 704f09b | 2011-11-17 17:14:16 +0000 | [diff] [blame] | 159 | <p> |
Howard Hinnant | 22b781b | 2012-11-06 21:31:37 +0000 | [diff] [blame] | 160 | On Mac OS 10.7 (Lion) and later, the easiest way to get this library is to install |
Howard Hinnant | 704f09b | 2011-11-17 17:14:16 +0000 | [diff] [blame] | 161 | Xcode 4.2 or later. However if you want to install tip-of-trunk from here |
Howard Hinnant | 271a1c0 | 2012-04-03 15:08:42 +0000 | [diff] [blame] | 162 | (getting the bleeding edge), read on. However, be warned that Mac OS |
| 163 | 10.7 will not boot without a valid copy of <code>libc++.1.dylib</code> in |
| 164 | <code>/usr/lib</code>. |
Howard Hinnant | 704f09b | 2011-11-17 17:14:16 +0000 | [diff] [blame] | 165 | </p> |
| 166 | |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 167 | <p>To check out the code, use:</p> |
| 168 | |
Howard Hinnant | 65451f1 | 2011-01-27 23:18:19 +0000 | [diff] [blame] | 169 | <ul> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 170 | <li><code>svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx</code></li> |
Howard Hinnant | 65451f1 | 2011-01-27 23:18:19 +0000 | [diff] [blame] | 171 | </ul> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 172 | |
Howard Hinnant | 65451f1 | 2011-01-27 23:18:19 +0000 | [diff] [blame] | 173 | <p> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 174 | Note that for an in-tree build, you should check out libcxx to |
| 175 | llvm/projects. |
Howard Hinnant | 65451f1 | 2011-01-27 23:18:19 +0000 | [diff] [blame] | 176 | </p> |
| 177 | |
Howard Hinnant | 65451f1 | 2011-01-27 23:18:19 +0000 | [diff] [blame] | 178 | <p> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 179 | The following instructions are for building libc++ on FreeBSD, Linux, or Mac |
| 180 | using <a href="http://libcxxabi.llvm.org/">libc++abi</a> as the C++ ABI |
| 181 | library. On Linux, it is also possible to use |
| 182 | <a href="#libsupcxx">libsupc++</a> or <a href="#libcxxrt">libcxxrt</a>. |
| 183 | </p> |
| 184 | |
| 185 | <p>In-tree build:</p> |
| 186 | <ul> |
Eric Fiselier | eb6e2ea | 2015-07-30 22:30:34 +0000 | [diff] [blame] | 187 | <li><code>cd where-you-want-to-live</code></li> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 188 | <li>Check out libcxx and <a href="http://libcxxabi.llvm.org/">libcxxabi</a> |
| 189 | into llvm/projects</li> |
Eric Fiselier | eb6e2ea | 2015-07-30 22:30:34 +0000 | [diff] [blame] | 190 | <li><code>cd where-you-want-to-build</code></li> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 191 | <li><code>mkdir build && cd build</code></li> |
Eric Fiselier | eb6e2ea | 2015-07-30 22:30:34 +0000 | [diff] [blame] | 192 | <li><code>cmake path/to/llvm # Linux may require -DCMAKE_C_COMPILER=clang |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 193 | -DCMAKE_CXX_COMPILER=clang++</code></li> |
| 194 | <li><code>make cxx</code></li> |
| 195 | </ul> |
| 196 | |
Eric Fiselier | eb6e2ea | 2015-07-30 22:30:34 +0000 | [diff] [blame] | 197 | <p>Out-of-tree buildc:</p> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 198 | <ul> |
Eric Fiselier | eb6e2ea | 2015-07-30 22:30:34 +0000 | [diff] [blame] | 199 | <li><code>cd where-you-want-to-live</code></li> |
| 200 | <li>Check out libcxx and llvm</li> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 201 | <li>If not on a Mac, also check out |
| 202 | <a href="http://libcxxabi.llvm.org/">libcxxabi</a></li> |
Eric Fiselier | eb6e2ea | 2015-07-30 22:30:34 +0000 | [diff] [blame] | 203 | <li><code>cd where-you-want-to-build</code></li> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 204 | <li><code>mkdir build && cd build</code></li> |
Eric Fiselier | eb6e2ea | 2015-07-30 22:30:34 +0000 | [diff] [blame] | 205 | <li><code>cmake -DLLVM_PATH=path/to/llvm |
| 206 | -DLIBCXX_CXX_ABI=libcxxabi |
Eric Fiselier | 02c24c1 | 2015-03-19 20:59:45 +0000 | [diff] [blame] | 207 | -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxabi/include |
Eric Fiselier | eb6e2ea | 2015-07-30 22:30:34 +0000 | [diff] [blame] | 208 | -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ |
| 209 | path/to/libcxx |
| 210 | </code></li> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 211 | <li><code>make</code></li> |
| 212 | </ul> |
| 213 | |
| 214 | <p>To run the tests:</p> |
| 215 | <ul> |
| 216 | <li><code>make check-libcxx</code></li> |
| 217 | </ul> |
| 218 | |
| 219 | <p>If you wish to run a subset of the test suite:</p> |
| 220 | <ul> |
| 221 | <li><code>cd path/to/libcxx/libcxx</code></li> |
| 222 | <li><code>alias lit='python path/to/llvm/utils/lit/lit.py'</code></li> |
Eric Fiselier | 4778eed | 2014-12-20 03:16:55 +0000 | [diff] [blame] | 223 | <li><code>export |
| 224 | LIBCXX_SITE_CONFIG=path/to/build/dir/projects/libcxx/test/lit.site.cfg |
| 225 | </code></li> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 226 | <li><code>lit -sv test/re/ # or whichever subset of tests you're interested |
| 227 | in</code></li> |
| 228 | </ul> |
| 229 | <p>The above is currently quite inconvenient. Sorry! We're working on it!</p> |
| 230 | |
| 231 | <p>More information on using LIT can be found |
| 232 | <a href="http://llvm.org/docs/CommandGuide/lit.html">here</a>. For more |
| 233 | general information about the LLVM testing infrastructure, see the |
| 234 | <a href="http://llvm.org/docs/TestingGuide.html">LLVM Testing Infrastructure |
| 235 | Guide</a> |
| 236 | </p> |
| 237 | |
| 238 | <p> |
| 239 | Shared libraries for libc++ should now be present in llvm/build/lib. Note |
| 240 | that it is safest to use this from its current location rather than |
| 241 | replacing your system's libc++ (if it has one, if not, go right ahead). |
| 242 | </p> |
| 243 | |
| 244 | <p> |
| 245 | Mac users, remember to be careful when replacing the system's libc++. |
Jonathan Roelofs | d20675f | 2015-05-08 21:11:49 +0000 | [diff] [blame] | 246 | <strong>Your system will not be able to boot without a functioning |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 247 | libc++.</strong> |
| 248 | </p> |
| 249 | |
| 250 | <!--=====================================================================--> |
Eric Fiselier | a5ad9ac | 2015-05-12 22:55:30 +0000 | [diff] [blame] | 251 | <h3>Notes and Known Issues</h3> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 252 | <!--=====================================================================--> |
| 253 | |
| 254 | <p> |
Eric Fiselier | a5ad9ac | 2015-05-12 22:55:30 +0000 | [diff] [blame] | 255 | <ul> |
| 256 | <li> |
| 257 | Building libc++ with <code>-fno-rtti</code> is not supported. However |
| 258 | linking against it with <code>-fno-rtti</code> is supported. |
| 259 | </li> |
| 260 | <li> |
| 261 | On OS X v10.8 and older the CMake option |
| 262 | <code>-DLIBCXX_LIBCPPABI_VERSION=""</code> must be used during |
| 263 | configuration. |
| 264 | </li> |
| 265 | </ul> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 266 | </p> |
| 267 | |
| 268 | <p>Send discussions to the |
Tanya Lattner | d08dbfc | 2015-08-05 03:59:14 +0000 | [diff] [blame] | 269 | <a href="http://lists.llvm.org/mailman/listinfo/cfe-dev">clang mailing list</a>.</p> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 270 | |
| 271 | <!--=====================================================================--> |
| 272 | <h2>Using libc++ in your programs</h2> |
| 273 | <!--=====================================================================--> |
| 274 | |
| 275 | <!--=====================================================================--> |
| 276 | <h3>FreeBSD and Mac OS X</h3> |
| 277 | <!--=====================================================================--> |
| 278 | |
| 279 | <p> |
| 280 | To use your system-installed libc++ with clang you can: |
Howard Hinnant | 65451f1 | 2011-01-27 23:18:19 +0000 | [diff] [blame] | 281 | </p> |
| 282 | |
| 283 | <ul> |
| 284 | <li><code>clang++ -stdlib=libc++ test.cpp</code></li> |
Howard Hinnant | af34734 | 2012-07-19 15:57:51 +0000 | [diff] [blame] | 285 | <li><code>clang++ -std=c++11 -stdlib=libc++ test.cpp</code></li> |
Howard Hinnant | bc8d3f9 | 2010-05-11 19:42:16 +0000 | [diff] [blame] | 286 | </ul> |
| 287 | |
Howard Hinnant | 22b781b | 2012-11-06 21:31:37 +0000 | [diff] [blame] | 288 | <p> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 289 | To use your tip-of-trunk libc++ on Mac OS with clang you can: |
Howard Hinnant | 22b781b | 2012-11-06 21:31:37 +0000 | [diff] [blame] | 290 | </p> |
| 291 | |
| 292 | <ul> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 293 | <li><code>export DYLD_LIBRARY_PATH=path/to/build/lib</code> |
Howard Hinnant | 22b781b | 2012-11-06 21:31:37 +0000 | [diff] [blame] | 294 | <li><code>clang++ -std=c++11 -stdlib=libc++ -nostdinc++ |
| 295 | -I<path-to-libcxx>/include -L<path-to-libcxx>/lib |
| 296 | test.cpp</code></li> |
| 297 | </ul> |
| 298 | |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 299 | <!--=====================================================================--> |
| 300 | <h3>Linux</h3> |
| 301 | <!--=====================================================================--> |
| 302 | |
| 303 | <p> |
| 304 | You will need to keep the source tree of |
| 305 | <a href="http://libcxxabi.llvm.org">libc++abi</a> available on your build |
| 306 | machine and your copy of the libc++abi shared library must be placed where |
| 307 | your linker will find it. |
| 308 | </p> |
| 309 | |
| 310 | <p> |
| 311 | Unfortunately you can't simply run clang with "-stdlib=libc++" at this |
| 312 | point, as clang is set up to link for libc++ linked to libsupc++. To get |
| 313 | around this you'll have to set up your linker yourself (or patch clang). |
| 314 | For example: |
| 315 | </p> |
Howard Hinnant | bc8d3f9 | 2010-05-11 19:42:16 +0000 | [diff] [blame] | 316 | |
| 317 | <ul> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 318 | <li><code>clang++ -stdlib=libc++ helloworld.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc</code></li> |
Howard Hinnant | bc8d3f9 | 2010-05-11 19:42:16 +0000 | [diff] [blame] | 319 | </ul> |
| 320 | |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 321 | <p> |
| 322 | Alternately, you could just add libc++abi to your libraries list, which in |
| 323 | most situations will give the same result: |
| 324 | </p> |
Howard Hinnant | 5106565 | 2012-05-20 13:03:53 +0000 | [diff] [blame] | 325 | |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 326 | <ul> |
| 327 | <li><code>clang++ -stdlib=libc++ helloworld.cpp -lc++abi</code></li> |
| 328 | </ul> |
Howard Hinnant | 8c21737 | 2010-05-11 19:53:34 +0000 | [diff] [blame] | 329 | |
Howard Hinnant | 56f0d5b | 2010-10-05 16:44:40 +0000 | [diff] [blame] | 330 | <!--=====================================================================--> |
Marshall Clow | 992f9d5 | 2014-04-03 03:13:12 +0000 | [diff] [blame] | 331 | <h2>Bug reports and patches</h2> |
| 332 | <!--=====================================================================--> |
| 333 | |
Dan Albert | e3eda9d | 2015-01-30 22:33:41 +0000 | [diff] [blame] | 334 | <p> |
| 335 | If you think you've found a bug in libc++, please report it using |
| 336 | the <a href="http://llvm.org/bugs">LLVM Bugzilla</a>. If you're not sure, you |
Tanya Lattner | d08dbfc | 2015-08-05 03:59:14 +0000 | [diff] [blame] | 337 | can post a message to the <a href="http://lists.llvm.org/mailman/listinfo/cfe-dev">cfe-dev</a> |
Dan Albert | e3eda9d | 2015-01-30 22:33:41 +0000 | [diff] [blame] | 338 | mailing list or on IRC. Please include "libc++" in your subject. |
| 339 | </p> |
Marshall Clow | 992f9d5 | 2014-04-03 03:13:12 +0000 | [diff] [blame] | 340 | |
Dan Albert | e3eda9d | 2015-01-30 22:33:41 +0000 | [diff] [blame] | 341 | <p> |
| 342 | If you want to contribute a patch to libc++, the best place for that is |
| 343 | <a href="http://llvm.org/docs/Phabricator.html">Phabricator</a>. Please |
| 344 | include [libc++] in the subject and add cfe-commits as a subscriber. |
| 345 | </p> |
Marshall Clow | 992f9d5 | 2014-04-03 03:13:12 +0000 | [diff] [blame] | 346 | |
| 347 | <!--=====================================================================--> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 348 | <h2 id="libsupcxx">Build on Linux using CMake and libsupc++.</h2> |
Michael J. Spencer | db8a030 | 2012-12-31 19:34:21 +0000 | [diff] [blame] | 349 | <!--=====================================================================--> |
| 350 | |
| 351 | <p> |
| 352 | You will need libstdc++ in order to provide libsupc++. |
| 353 | </p> |
Dan Albert | e3eda9d | 2015-01-30 22:33:41 +0000 | [diff] [blame] | 354 | |
Michael J. Spencer | db8a030 | 2012-12-31 19:34:21 +0000 | [diff] [blame] | 355 | <p> |
| 356 | Figure out where the libsupc++ headers are on your system. On Ubuntu this |
| 357 | is <code>/usr/include/c++/<version></code> and |
| 358 | <code>/usr/include/c++/<version>/<target-triple></code> |
| 359 | </p> |
Dan Albert | e3eda9d | 2015-01-30 22:33:41 +0000 | [diff] [blame] | 360 | |
Michael J. Spencer | db8a030 | 2012-12-31 19:34:21 +0000 | [diff] [blame] | 361 | <p> |
| 362 | You can also figure this out by running |
| 363 | <pre> |
| 364 | $ echo | g++ -Wp,-v -x c++ - -fsyntax-only |
| 365 | ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu" |
| 366 | ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include" |
| 367 | #include "..." search starts here: |
| 368 | #include <...> search starts here: |
| 369 | /usr/include/c++/4.7 |
| 370 | /usr/include/c++/4.7/x86_64-linux-gnu |
| 371 | /usr/include/c++/4.7/backward |
| 372 | /usr/lib/gcc/x86_64-linux-gnu/4.7/include |
| 373 | /usr/local/include |
| 374 | /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed |
| 375 | /usr/include/x86_64-linux-gnu |
| 376 | /usr/include |
| 377 | End of search list. |
| 378 | </pre> |
| 379 | |
| 380 | Note the first two entries happen to be what we are looking for. This |
| 381 | may not be correct on other platforms. |
| 382 | </p> |
Dan Albert | e3eda9d | 2015-01-30 22:33:41 +0000 | [diff] [blame] | 383 | |
Michael J. Spencer | db8a030 | 2012-12-31 19:34:21 +0000 | [diff] [blame] | 384 | <p> |
| 385 | We can now run CMake: |
| 386 | <ul> |
| 387 | <li><code>CC=clang CXX=clang++ cmake -G "Unix Makefiles" |
Peter Collingbourne | d0d308f | 2013-10-06 22:13:19 +0000 | [diff] [blame] | 388 | -DLIBCXX_CXX_ABI=libstdc++ |
Eric Fiselier | 02c24c1 | 2015-03-19 20:59:45 +0000 | [diff] [blame] | 389 | -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/" |
Michael J. Spencer | db8a030 | 2012-12-31 19:34:21 +0000 | [diff] [blame] | 390 | -DCMAKE_BUILD_TYPE=Release |
| 391 | -DCMAKE_INSTALL_PREFIX=/usr |
| 392 | <libc++-source-dir></code></li> |
Peter Collingbourne | d0d308f | 2013-10-06 22:13:19 +0000 | [diff] [blame] | 393 | <li>You can also substitute <code>-DLIBCXX_CXX_ABI=libsupc++</code> |
| 394 | above, which will cause the library to be linked to libsupc++ instead |
| 395 | of libstdc++, but this is only recommended if you know that you will |
| 396 | never need to link against libstdc++ in the same executable as libc++. |
| 397 | GCC ships libsupc++ separately but only as a static library. If a |
| 398 | program also needs to link against libstdc++, it will provide its |
| 399 | own copy of libsupc++ and this can lead to subtle problems. |
Michael J. Spencer | db8a030 | 2012-12-31 19:34:21 +0000 | [diff] [blame] | 400 | <li><code>make</code></li> |
| 401 | <li><code>sudo make install</code></li> |
| 402 | </ul> |
| 403 | <p> |
| 404 | You can now run clang with -stdlib=libc++. |
| 405 | </p> |
| 406 | </p> |
| 407 | |
| 408 | <!--=====================================================================--> |
Dan Albert | 35d775d | 2014-08-11 15:12:46 +0000 | [diff] [blame] | 409 | <h2 id="libcxxrt">Build on Linux using CMake and libcxxrt.</h2> |
Howard Hinnant | af4d161 | 2013-02-08 19:10:36 +0000 | [diff] [blame] | 410 | <!--=====================================================================--> |
| 411 | |
| 412 | <p> |
| 413 | You will need to keep the source tree of |
| 414 | <a href="https://github.com/pathscale/libcxxrt/">libcxxrt</a> available |
| 415 | on your build machine and your copy of the libcxxrt shared library must |
| 416 | be placed where your linker will find it. |
| 417 | </p> |
Dan Albert | e3eda9d | 2015-01-30 22:33:41 +0000 | [diff] [blame] | 418 | |
Howard Hinnant | af4d161 | 2013-02-08 19:10:36 +0000 | [diff] [blame] | 419 | <p> |
| 420 | We can now run CMake: |
| 421 | <ul> |
| 422 | <li><code>CC=clang CXX=clang++ cmake -G "Unix Makefiles" |
| 423 | -DLIBCXX_CXX_ABI=libcxxrt |
Eric Fiselier | 02c24c1 | 2015-03-19 20:59:45 +0000 | [diff] [blame] | 424 | -DLIBCXX_CXX_ABI_INCLUDE_PATHS="<libcxxrt-source-dir>/src" |
Howard Hinnant | af4d161 | 2013-02-08 19:10:36 +0000 | [diff] [blame] | 425 | -DCMAKE_BUILD_TYPE=Release |
| 426 | -DCMAKE_INSTALL_PREFIX=/usr |
| 427 | <libc++-source-dir></code></li> |
| 428 | <li><code>make</code></li> |
| 429 | <li><code>sudo make install</code></li> |
| 430 | </ul> |
| 431 | <p> |
| 432 | Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as |
| 433 | clang is set up to link for libc++ linked to libsupc++. To get around this |
| 434 | you'll have to set up your linker yourself (or patch clang). For example, |
| 435 | <ul> |
| 436 | <li><code>clang++ -stdlib=libc++ helloworld.cpp -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc</code></li> |
| 437 | </ul> |
| 438 | Alternately, you could just add libcxxrt to your libraries list, which in most |
| 439 | situations will give the same result: |
| 440 | <ul> |
| 441 | <li><code>clang++ -stdlib=libc++ helloworld.cpp -lcxxrt</code></li> |
| 442 | </ul> |
| 443 | </p> |
| 444 | </p> |
| 445 | |
| 446 | <!--=====================================================================--> |
Eric Fiselier | 9071bc0 | 2014-10-18 01:15:17 +0000 | [diff] [blame] | 447 | <h2 id="local-abi">Using a local ABI library</h2> |
| 448 | <!--=====================================================================--> |
| 449 | <p> |
| 450 | <strong>Note: This is not recommended in almost all cases.</strong><br> |
| 451 | Generally these instructions should only be used when you can't install |
| 452 | your ABI library. |
| 453 | </p> |
| 454 | <p> |
| 455 | Normally you must link libc++ against a ABI shared library that the |
| 456 | linker can find. If you want to build and test libc++ against an ABI |
| 457 | library not in the linker's path you need to set |
Eric Fiselier | cb7e32c | 2014-10-19 00:42:41 +0000 | [diff] [blame] | 458 | <code>-DLIBCXX_CXX_ABI_LIBRARY_PATH=/path/to/abi/lib</code> when |
| 459 | configuring CMake. |
Eric Fiselier | 9071bc0 | 2014-10-18 01:15:17 +0000 | [diff] [blame] | 460 | </p> |
| 461 | <p> |
| 462 | An example build using libc++abi would look like: |
| 463 | <ul> |
| 464 | <li><code>CC=clang CXX=clang++ cmake |
| 465 | -DLIBCXX_CXX_ABI=libc++abi |
Eric Fiselier | 02c24c1 | 2015-03-19 20:59:45 +0000 | [diff] [blame] | 466 | -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/path/to/libcxxabi/include" |
Eric Fiselier | cb7e32c | 2014-10-19 00:42:41 +0000 | [diff] [blame] | 467 | -DLIBCXX_CXX_ABI_LIBRARY_PATH="/path/to/libcxxabi-build/lib" |
Eric Fiselier | 9071bc0 | 2014-10-18 01:15:17 +0000 | [diff] [blame] | 468 | path/to/libcxx</code></li> |
| 469 | <li><code>make</code></li> |
| 470 | </ul> |
| 471 | </p> |
| 472 | <p> |
| 473 | When testing libc++ LIT will automatically link against the proper ABI |
| 474 | library. |
| 475 | </p> |
| 476 | |
| 477 | <!--=====================================================================--> |
Howard Hinnant | 56f0d5b | 2010-10-05 16:44:40 +0000 | [diff] [blame] | 478 | <h2>Design Documents</h2> |
| 479 | <!--=====================================================================--> |
| 480 | |
| 481 | <ul> |
| 482 | <li><a href="atomic_design.html"><tt><atomic></tt></a></li> |
Howard Hinnant | 9835d76 | 2010-11-19 01:38:58 +0000 | [diff] [blame] | 483 | <li><a href="type_traits_design.html"><tt><type_traits></tt></a></li> |
Marshall Clow | e47bc9b | 2013-03-14 19:00:34 +0000 | [diff] [blame] | 484 | <li><a href="http://cplusplusmusings.wordpress.com/2012/07/05/clang-and-standard-libraries-on-mac-os-x/">Excellent notes by Marshall Clow</a></li> |
Howard Hinnant | c7cbe50 | 2013-03-14 18:37:48 +0000 | [diff] [blame] | 485 | <li><a href="debug_mode.html">Status of debug mode</a></li> |
Eric Fiselier | 71dc14e | 2014-12-22 20:49:45 +0000 | [diff] [blame] | 486 | <li><a href="lit_usage.html">LIT usage guide</a></li> |
Howard Hinnant | 56f0d5b | 2010-10-05 16:44:40 +0000 | [diff] [blame] | 487 | </ul> |
| 488 | |
Howard Hinnant | bc8d3f9 | 2010-05-11 19:42:16 +0000 | [diff] [blame] | 489 | </div> |
| 490 | </body> |
Chris Lattner | 4b74895 | 2010-05-11 20:37:52 +0000 | [diff] [blame] | 491 | </html> |