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