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 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> 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> 112 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> 120 121 <!--=====================================================================--> 122 <h2 id="dir-structure">Current Status</h2> 123 <!--=====================================================================--> 124 125 <p>libc++ is a 100% complete C++11 implementation on Apple's OS X. </p> 126 <p>LLVM and Clang can self host in C++ and C++11 mode with libc++ on Linux.</p> 127 <p>libc++ is also a 100% complete C++14 implementation. A list of new features and changes for 128 C++14 can be found <a href="cxx1y_status.html">here</a>.</p> 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> 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> 133 <p> 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>. 137 </p> 138 139 <!--======================================================================--> 140 <h2 id="buildbots">Build Bots</h2> 141 <!--======================================================================--> 142 <p>The latest libc++ build results can be found at the following locations.</p> 143 <ul> 144 <li><a href="http://lab.llvm.org:8011/console"> 145 Buildbot libc++ builders 146 </a></li> 147 <li><a href="http://lab.llvm.org:8080/green/view/Libcxx/"> 148 Jenkins libc++ builders 149 </a></li> 150 </ul> 151 152 <!--=====================================================================--> 153 <h2>Get it and get involved!</h2> 154 <!--=====================================================================--> 155 156 <p>First please review our 157 <a href="http://llvm.org/docs/DeveloperPolicy.html">Developer's Policy</a>. 158 159 <p> 160 On Mac OS 10.7 (Lion) and later, the easiest way to get this library is to install 161 Xcode 4.2 or later. However if you want to install tip-of-trunk from here 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>. 165 </p> 166 167 <p>To check out the code, use:</p> 168 169 <ul> 170 <li><code>svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx</code></li> 171 </ul> 172 173 <p> 174 Note that for an in-tree build, you should check out libcxx to 175 llvm/projects. 176 </p> 177 178 <p> 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> 187 <li><code>cd where-you-want-to-live</code></li> 188 <li>Check out libcxx and <a href="http://libcxxabi.llvm.org/">libcxxabi</a> 189 into llvm/projects</li> 190 <li><code>cd where-you-want-to-build</code></li> 191 <li><code>mkdir build && cd build</code></li> 192 <li><code>cmake path/to/llvm # Linux may require -DCMAKE_C_COMPILER=clang 193 -DCMAKE_CXX_COMPILER=clang++</code></li> 194 <li><code>make cxx</code></li> 195 </ul> 196 197 <p>Out-of-tree buildc:</p> 198 <ul> 199 <li><code>cd where-you-want-to-live</code></li> 200 <li>Check out libcxx and llvm</li> 201 <li>If not on a Mac, also check out 202 <a href="http://libcxxabi.llvm.org/">libcxxabi</a></li> 203 <li><code>cd where-you-want-to-build</code></li> 204 <li><code>mkdir build && cd build</code></li> 205 <li><code>cmake -DLLVM_PATH=path/to/llvm 206 -DLIBCXX_CXX_ABI=libcxxabi 207 -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxabi/include 208 -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ 209 path/to/libcxx 210 </code></li> 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> 223 <li><code>export 224 LIBCXX_SITE_CONFIG=path/to/build/dir/projects/libcxx/test/lit.site.cfg 225 </code></li> 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++. 246 <strong>Your system will not be able to boot without a functioning 247 libc++.</strong> 248 </p> 249 250 <!--=====================================================================--> 251 <h3>Notes and Known Issues</h3> 252 <!--=====================================================================--> 253 254 <p> 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> 266 </p> 267 268 <p>Send discussions to the 269 <a href="http://lists.llvm.org/mailman/listinfo/cfe-dev">clang mailing list</a>.</p> 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: 281 </p> 282 283 <ul> 284 <li><code>clang++ -stdlib=libc++ test.cpp</code></li> 285 <li><code>clang++ -std=c++11 -stdlib=libc++ test.cpp</code></li> 286 </ul> 287 288 <p> 289 To use your tip-of-trunk libc++ on Mac OS with clang you can: 290 </p> 291 292 <ul> 293 <li><code>export DYLD_LIBRARY_PATH=path/to/build/lib</code> 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 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> 316 317 <ul> 318 <li><code>clang++ -stdlib=libc++ helloworld.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc</code></li> 319 </ul> 320 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> 325 326 <ul> 327 <li><code>clang++ -stdlib=libc++ helloworld.cpp -lc++abi</code></li> 328 </ul> 329 330 <!--=====================================================================--> 331 <h2>Bug reports and patches</h2> 332 <!--=====================================================================--> 333 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 337 can post a message to the <a href="http://lists.llvm.org/mailman/listinfo/cfe-dev">cfe-dev</a> 338 mailing list or on IRC. Please include "libc++" in your subject. 339 </p> 340 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> 346 347 <!--=====================================================================--> 348 <h2 id="libsupcxx">Build on Linux using CMake and libsupc++.</h2> 349 <!--=====================================================================--> 350 351 <p> 352 You will need libstdc++ in order to provide libsupc++. 353 </p> 354 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> 360 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> 383 384 <p> 385 We can now run CMake: 386 <ul> 387 <li><code>CC=clang CXX=clang++ cmake -G "Unix Makefiles" 388 -DLIBCXX_CXX_ABI=libstdc++ 389 -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/" 390 -DCMAKE_BUILD_TYPE=Release 391 -DCMAKE_INSTALL_PREFIX=/usr 392 <libc++-source-dir></code></li> 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. 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 <!--=====================================================================--> 409 <h2 id="libcxxrt">Build on Linux using CMake and libcxxrt.</h2> 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> 418 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 424 -DLIBCXX_CXX_ABI_INCLUDE_PATHS="<libcxxrt-source-dir>/src" 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 <!--=====================================================================--> 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 458 <code>-DLIBCXX_CXX_ABI_LIBRARY_PATH=/path/to/abi/lib</code> when 459 configuring CMake. 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 466 -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/path/to/libcxxabi/include" 467 -DLIBCXX_CXX_ABI_LIBRARY_PATH="/path/to/libcxxabi-build/lib" 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 <!--=====================================================================--> 478 <h2>Design Documents</h2> 479 <!--=====================================================================--> 480 481 <ul> 482 <li><a href="atomic_design.html"><tt><atomic></tt></a></li> 483 <li><a href="type_traits_design.html"><tt><type_traits></tt></a></li> 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> 485 <li><a href="debug_mode.html">Status of debug mode</a></li> 486 <li><a href="lit_usage.html">LIT usage guide</a></li> 487 </ul> 488 489 </div> 490 </body> 491 </html> 492
