1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 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> 17 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> 25 <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">cfe-dev</a> 26 <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits">cfe-commits</a> 27 <a href="http://llvm.org/bugs/">Bug Reports</a> 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> 30 </div> 31</div> 32 33<div id="content"> 34 <!--*********************************************************************--> 35 <h1>"libc++" C++ Standard Library</h1> 36 <!--*********************************************************************--> 37 38 <p>libc++ is a new implementation of the C++ standard library, targeting 39 C++11.</p> 40 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> 44 45 <!--=====================================================================--> 46 <h2 id="goals">Features and Goals</h2> 47 <!--=====================================================================--> 48 49 <ul> 50 <li>Correctness as defined by the C++11 standard.</li> 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 <!--=====================================================================--> 60 <h2 id="why">Why a new C++ Standard Library for C++11?</h2> 61 <!--=====================================================================--> 62 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> 67 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 75 machines (particularly in C++11, which has rvalue references). Breaking 76 ABI compatibility with old versions of the library was 77 determined to be critical to achieving the performance goals of 78 libc++.</p></li> 79 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 82 independently extended to support C++11, but this would be a fork of the 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> 87 </li> 88 89 <li><p>STLport and the Apache libstdcxx library are two other popular 90 candidates, but both lack C++11 support. Our experience (and the 91 experience of libstdc++ developers) is that adding support for C++11 (in 92 particular rvalue references and move-only types) requires changes to 93 almost every class and function, essentially amounting to a rewrite. 94 Faced with a rewrite, we decided to start from scratch and evaluate every 95 design decision from first principles based on experience.</p> 96 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 <!--=====================================================================--> 103 <h2 id="requirements">Platform Support</h2> 104 <!--=====================================================================--> 105 106 <p>libc++ is known to work on the following platforms, using g++-4.2 and 107 clang (lack of C++11 language support disables some functionality).</p> 108 109 <ul> 110 <li>Mac OS X i386</li> 111 <li>Mac OS X x86_64</li> 112 </ul> 113 114 <!--=====================================================================--> 115 <h2 id="dir-structure">Current Status</h2> 116 <!--=====================================================================--> 117 118 <p>libc++ is a 100% complete C++11 implementation on Apple's OS X. </p> 119 <p>LLVM and Clang can self host in C++ and C++11 mode with libc++ on Linux.</p> 120 <p>C++1Y (C++14) implementation is in progress. The current status is 121 <a href="cxx1y_status.html">here</a></p> 122 123 <p> 124 Ports to other platforms are underway. Here are recent test 125 results for <a href="results.Windows.html">Windows</a> 126 and <a href="results.Linux.html">Linux</a>. 127 </p> 128 129 <!--=====================================================================--> 130 <h2>Get it and get involved!</h2> 131 <!--=====================================================================--> 132 133 <p>First please review our 134 <a href="http://llvm.org/docs/DeveloperPolicy.html">Developer's Policy</a>. 135 136 <p>To check out the code, use:</p> 137 138 <ul> 139 <li><code>svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx</code></li> 140 </ul> 141 142 <p> 143 On Mac OS 10.7 (Lion) and later, the easiest way to get this library is to install 144 Xcode 4.2 or later. However if you want to install tip-of-trunk from here 145 (getting the bleeding edge), read on. However, be warned that Mac OS 146 10.7 will not boot without a valid copy of <code>libc++.1.dylib</code> in 147 <code>/usr/lib</code>. 148 </p> 149 150 <p> 151 Next: 152 </p> 153 154 <ul> 155 <li><code>cd libcxx/lib</code></li> 156 <li><code>export TRIPLE=-apple-</code></li> 157 <li><code>/buildit</code></li> 158 <li><code>ln -sf libc++.1.dylib libc++.dylib</code></li> 159 </ul> 160 161 <p> 162 That should result in a libc++.1.dylib and libc++.dylib. The safest thing 163 to do is to use it from where your libcxx is installed instead of replacing 164 these in your Mac OS. 165 </p> 166 167 <p> 168 To use your system-installed libc++ with clang you can: 169 </p> 170 171 <ul> 172 <li><code>clang++ -stdlib=libc++ test.cpp</code></li> 173 <li><code>clang++ -std=c++11 -stdlib=libc++ test.cpp</code></li> 174 </ul> 175 176 <p> 177 To use your tip-of-trunk libc++ on Mac OS with clang you can: 178 </p> 179 180 <ul> 181 <li><code>export DYLD_LIBRARY_PATH=<path-to-libcxx>/lib</code> 182 <li><code>clang++ -std=c++11 -stdlib=libc++ -nostdinc++ 183 -I<path-to-libcxx>/include -L<path-to-libcxx>/lib 184 test.cpp</code></li> 185 </ul> 186 187 <p>To run the libc++ test suite (recommended):</p> 188 189 <ul> 190 <li><code>cd libcxx/test</code></li> 191 <li><code>/testit</code></li> 192 <ul> 193 <li>You can alter the command line options <code>testit</code> uses 194 with <code>export OPTIONS="whatever you need"</code></li> 195 </ul> 196 </ul> 197 198 <!--=====================================================================--> 199 <h3>Notes</h3> 200 <!--=====================================================================--> 201 202<p> 203Building libc++ with <code>-fno-rtti</code> is not supported. However linking 204against it with <code>-fno-rtti</code> is supported. 205</p> 206 207 <p>Send discussions to the 208 (<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">clang mailing list</a>).</p> 209 210 <!--=====================================================================--> 211 <h2>Build on Linux using CMake and libsupc++.</h2> 212 <!--=====================================================================--> 213 214 <p> 215 You will need libstdc++ in order to provide libsupc++. 216 </p> 217 218 <p> 219 Figure out where the libsupc++ headers are on your system. On Ubuntu this 220 is <code>/usr/include/c++/<version></code> and 221 <code>/usr/include/c++/<version>/<target-triple></code> 222 </p> 223 224 <p> 225 You can also figure this out by running 226 <pre> 227$ echo | g++ -Wp,-v -x c++ - -fsyntax-only 228ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu" 229ignoring nonexistent directory "/usr/x86_64-linux-gnu/include" 230#include "..." search starts here: 231#include <...> search starts here: 232 /usr/include/c++/4.7 233 /usr/include/c++/4.7/x86_64-linux-gnu 234 /usr/include/c++/4.7/backward 235 /usr/lib/gcc/x86_64-linux-gnu/4.7/include 236 /usr/local/include 237 /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed 238 /usr/include/x86_64-linux-gnu 239 /usr/include 240End of search list. 241 </pre> 242 243 Note the first two entries happen to be what we are looking for. This 244 may not be correct on other platforms. 245 </p> 246 247 <p> 248 We can now run CMake: 249 <ul> 250 <li><code>CC=clang CXX=clang++ cmake -G "Unix Makefiles" 251 -DLIBCXX_CXX_ABI=libstdc++ 252 -DLIBCXX_LIBSUPCXX_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/" 253 -DCMAKE_BUILD_TYPE=Release 254 -DCMAKE_INSTALL_PREFIX=/usr 255 <libc++-source-dir></code></li> 256 <li>You can also substitute <code>-DLIBCXX_CXX_ABI=libsupc++</code> 257 above, which will cause the library to be linked to libsupc++ instead 258 of libstdc++, but this is only recommended if you know that you will 259 never need to link against libstdc++ in the same executable as libc++. 260 GCC ships libsupc++ separately but only as a static library. If a 261 program also needs to link against libstdc++, it will provide its 262 own copy of libsupc++ and this can lead to subtle problems. 263 <li><code>make</code></li> 264 <li><code>sudo make install</code></li> 265 </ul> 266 <p> 267 You can now run clang with -stdlib=libc++. 268 </p> 269 </p> 270 271 <!--=====================================================================--> 272 <h2>Build on Linux using CMake and libc++abi.</h2> 273 <!--=====================================================================--> 274 275 <p> 276 You will need to keep the source tree of <a href="http://libcxxabi.llvm.org">libc++abi</a> 277 available on your build machine and your copy of the libc++abi shared library must 278 be placed where your linker will find it. 279 </p> 280 281 <p> 282 We can now run CMake: 283 <ul> 284 <li><code>CC=clang CXX=clang++ cmake -G "Unix Makefiles" 285 -DLIBCXX_CXX_ABI=libcxxabi 286 -DLIBCXX_LIBCXXABI_INCLUDE_PATHS="<libc++abi-source-dir>/include" 287 -DCMAKE_BUILD_TYPE=Release 288 -DCMAKE_INSTALL_PREFIX=/usr 289 <libc++-source-dir></code></li> 290 <li><code>make</code></li> 291 <li><code>sudo make install</code></li> 292 </ul> 293 <p> 294 Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as 295 clang is set up to link for libc++ linked to libsupc++. To get around this 296 you'll have to set up your linker yourself (or patch clang). For example, 297 <ul> 298 <li><code>clang++ -stdlib=libc++ helloworld.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc</code></li> 299 </ul> 300 Alternately, you could just add libc++abi to your libraries list, which in most 301 situations will give the same result: 302 <ul> 303 <li><code>clang++ -stdlib=libc++ helloworld.cpp -lc++abi</code></li> 304 </ul> 305 </p> 306 </p> 307 308 <!--=====================================================================--> 309 <h2>Build on Linux using CMake and libcxxrt.</h2> 310 <!--=====================================================================--> 311 312 <p> 313 You will need to keep the source tree of 314 <a href="https://github.com/pathscale/libcxxrt/">libcxxrt</a> available 315 on your build machine and your copy of the libcxxrt shared library must 316 be placed where your linker will find it. 317 </p> 318 319 <p> 320 We can now run CMake: 321 <ul> 322 <li><code>CC=clang CXX=clang++ cmake -G "Unix Makefiles" 323 -DLIBCXX_CXX_ABI=libcxxrt 324 -DLIBCXX_LIBCXXRT_INCLUDE_PATHS="<libcxxrt-source-dir>/src" 325 -DCMAKE_BUILD_TYPE=Release 326 -DCMAKE_INSTALL_PREFIX=/usr 327 <libc++-source-dir></code></li> 328 <li><code>make</code></li> 329 <li><code>sudo make install</code></li> 330 </ul> 331 <p> 332 Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as 333 clang is set up to link for libc++ linked to libsupc++. To get around this 334 you'll have to set up your linker yourself (or patch clang). For example, 335 <ul> 336 <li><code>clang++ -stdlib=libc++ helloworld.cpp -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc</code></li> 337 </ul> 338 Alternately, you could just add libcxxrt to your libraries list, which in most 339 situations will give the same result: 340 <ul> 341 <li><code>clang++ -stdlib=libc++ helloworld.cpp -lcxxrt</code></li> 342 </ul> 343 </p> 344 </p> 345 346 <!--=====================================================================--> 347 <h2>Design Documents</h2> 348 <!--=====================================================================--> 349 350<ul> 351<li><a href="atomic_design.html"><tt><atomic></tt></a></li> 352<li><a href="type_traits_design.html"><tt><type_traits></tt></a></li> 353<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> 354<li><a href="debug_mode.html">Status of debug mode</a></li> 355</ul> 356 357</div> 358</body> 359</html> 360