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> 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>Check out libcxx and <a href="http://libcxxabi.llvm.org/">libcxxabi</a> 188 into llvm/projects</li> 189 <li><code>cd llvm</code></li> 190 <li><code>mkdir build && cd build</code></li> 191 <li><code>cmake .. # Linux may require -DCMAKE_C_COMPILER=clang 192 -DCMAKE_CXX_COMPILER=clang++</code></li> 193 <li><code>make cxx</code></li> 194 </ul> 195 196 <p>Out-of-tree build:</p> 197 <ul> 198 <li>Check out libcxx</li> 199 <li>If not on a Mac, also check out 200 <a href="http://libcxxabi.llvm.org/">libcxxabi</a></li> 201 <li><code>cd libcxx</code></li> 202 <li><code>mkdir build && cd build</code></li> 203 <li><code>cmake -DLIBCXX_CXX_ABI=libcxxabi 204 -DLIBCXX_LIBCXXABI_INCLUDE_PATHS=path/to/libcxxabi/include 205 -DLIT_EXECUTABLE=path/to/llvm/utils/lit/lit.py .. # Linux may require 206 -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++</code></li> 207 <li><code>make</code></li> 208 </ul> 209 210 <p>To run the tests:</p> 211 <ul> 212 <li><code>make check-libcxx</code></li> 213 </ul> 214 215 <p>If you wish to run a subset of the test suite:</p> 216 <ul> 217 <li><code>cd path/to/libcxx/libcxx</code></li> 218 <li><code>alias lit='python path/to/llvm/utils/lit/lit.py'</code></li> 219 <li><code>export 220 LIBCXX_SITE_CONFIG=path/to/build/dir/projects/libcxx/test/lit.site.cfg 221 </code></li> 222 <li><code>lit -sv test/re/ # or whichever subset of tests you're interested 223 in</code></li> 224 </ul> 225 <p>The above is currently quite inconvenient. Sorry! We're working on it!</p> 226 227 <p>More information on using LIT can be found 228 <a href="http://llvm.org/docs/CommandGuide/lit.html">here</a>. For more 229 general information about the LLVM testing infrastructure, see the 230 <a href="http://llvm.org/docs/TestingGuide.html">LLVM Testing Infrastructure 231 Guide</a> 232 </p> 233 234 <p> 235 Shared libraries for libc++ should now be present in llvm/build/lib. Note 236 that it is safest to use this from its current location rather than 237 replacing your system's libc++ (if it has one, if not, go right ahead). 238 </p> 239 240 <p> 241 Mac users, remember to be careful when replacing the system's libc++. 242 <strong>Your system will not be able to boot without a funcioning 243 libc++.</strong> 244 </p> 245 246 <!--=====================================================================--> 247 <h3>Notes</h3> 248 <!--=====================================================================--> 249 250 <p> 251 Building libc++ with <code>-fno-rtti</code> is not supported. However 252 linking against it with <code>-fno-rtti</code> is supported. 253 </p> 254 255 <p>Send discussions to the 256 <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">clang mailing list</a>.</p> 257 258 <!--=====================================================================--> 259 <h2>Using libc++ in your programs</h2> 260 <!--=====================================================================--> 261 262 <!--=====================================================================--> 263 <h3>FreeBSD and Mac OS X</h3> 264 <!--=====================================================================--> 265 266 <p> 267 To use your system-installed libc++ with clang you can: 268 </p> 269 270 <ul> 271 <li><code>clang++ -stdlib=libc++ test.cpp</code></li> 272 <li><code>clang++ -std=c++11 -stdlib=libc++ test.cpp</code></li> 273 </ul> 274 275 <p> 276 To use your tip-of-trunk libc++ on Mac OS with clang you can: 277 </p> 278 279 <ul> 280 <li><code>export DYLD_LIBRARY_PATH=path/to/build/lib</code> 281 <li><code>clang++ -std=c++11 -stdlib=libc++ -nostdinc++ 282 -I<path-to-libcxx>/include -L<path-to-libcxx>/lib 283 test.cpp</code></li> 284 </ul> 285 286 <!--=====================================================================--> 287 <h3>Linux</h3> 288 <!--=====================================================================--> 289 290 <p> 291 You will need to keep the source tree of 292 <a href="http://libcxxabi.llvm.org">libc++abi</a> available on your build 293 machine and your copy of the libc++abi shared library must be placed where 294 your linker will find it. 295 </p> 296 297 <p> 298 Unfortunately you can't simply run clang with "-stdlib=libc++" at this 299 point, as clang is set up to link for libc++ linked to libsupc++. To get 300 around this you'll have to set up your linker yourself (or patch clang). 301 For example: 302 </p> 303 304 <ul> 305 <li><code>clang++ -stdlib=libc++ helloworld.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc</code></li> 306 </ul> 307 308 <p> 309 Alternately, you could just add libc++abi to your libraries list, which in 310 most situations will give the same result: 311 </p> 312 313 <ul> 314 <li><code>clang++ -stdlib=libc++ helloworld.cpp -lc++abi</code></li> 315 </ul> 316 317 <!--=====================================================================--> 318 <h2>Bug reports and patches</h2> 319 <!--=====================================================================--> 320 321 <p> 322 If you think you've found a bug in libc++, please report it using 323 the <a href="http://llvm.org/bugs">LLVM Bugzilla</a>. If you're not sure, you 324 can post a message to the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">cfe-dev</a> 325 mailing list or on IRC. Please include "libc++" in your subject. 326 </p> 327 328 <p> 329 If you want to contribute a patch to libc++, the best place for that is 330 <a href="http://llvm.org/docs/Phabricator.html">Phabricator</a>. Please 331 include [libc++] in the subject and add cfe-commits as a subscriber. 332 </p> 333 334 <!--=====================================================================--> 335 <h2 id="libsupcxx">Build on Linux using CMake and libsupc++.</h2> 336 <!--=====================================================================--> 337 338 <p> 339 You will need libstdc++ in order to provide libsupc++. 340 </p> 341 342 <p> 343 Figure out where the libsupc++ headers are on your system. On Ubuntu this 344 is <code>/usr/include/c++/<version></code> and 345 <code>/usr/include/c++/<version>/<target-triple></code> 346 </p> 347 348 <p> 349 You can also figure this out by running 350 <pre> 351 $ echo | g++ -Wp,-v -x c++ - -fsyntax-only 352 ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu" 353 ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include" 354 #include "..." search starts here: 355 #include <...> search starts here: 356 /usr/include/c++/4.7 357 /usr/include/c++/4.7/x86_64-linux-gnu 358 /usr/include/c++/4.7/backward 359 /usr/lib/gcc/x86_64-linux-gnu/4.7/include 360 /usr/local/include 361 /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed 362 /usr/include/x86_64-linux-gnu 363 /usr/include 364 End of search list. 365 </pre> 366 367 Note the first two entries happen to be what we are looking for. This 368 may not be correct on other platforms. 369 </p> 370 371 <p> 372 We can now run CMake: 373 <ul> 374 <li><code>CC=clang CXX=clang++ cmake -G "Unix Makefiles" 375 -DLIBCXX_CXX_ABI=libstdc++ 376 -DLIBCXX_LIBSUPCXX_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/" 377 -DCMAKE_BUILD_TYPE=Release 378 -DCMAKE_INSTALL_PREFIX=/usr 379 <libc++-source-dir></code></li> 380 <li>You can also substitute <code>-DLIBCXX_CXX_ABI=libsupc++</code> 381 above, which will cause the library to be linked to libsupc++ instead 382 of libstdc++, but this is only recommended if you know that you will 383 never need to link against libstdc++ in the same executable as libc++. 384 GCC ships libsupc++ separately but only as a static library. If a 385 program also needs to link against libstdc++, it will provide its 386 own copy of libsupc++ and this can lead to subtle problems. 387 <li><code>make</code></li> 388 <li><code>sudo make install</code></li> 389 </ul> 390 <p> 391 You can now run clang with -stdlib=libc++. 392 </p> 393 </p> 394 395 <!--=====================================================================--> 396 <h2 id="libcxxrt">Build on Linux using CMake and libcxxrt.</h2> 397 <!--=====================================================================--> 398 399 <p> 400 You will need to keep the source tree of 401 <a href="https://github.com/pathscale/libcxxrt/">libcxxrt</a> available 402 on your build machine and your copy of the libcxxrt shared library must 403 be placed where your linker will find it. 404 </p> 405 406 <p> 407 We can now run CMake: 408 <ul> 409 <li><code>CC=clang CXX=clang++ cmake -G "Unix Makefiles" 410 -DLIBCXX_CXX_ABI=libcxxrt 411 -DLIBCXX_LIBCXXRT_INCLUDE_PATHS="<libcxxrt-source-dir>/src" 412 -DCMAKE_BUILD_TYPE=Release 413 -DCMAKE_INSTALL_PREFIX=/usr 414 <libc++-source-dir></code></li> 415 <li><code>make</code></li> 416 <li><code>sudo make install</code></li> 417 </ul> 418 <p> 419 Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as 420 clang is set up to link for libc++ linked to libsupc++. To get around this 421 you'll have to set up your linker yourself (or patch clang). For example, 422 <ul> 423 <li><code>clang++ -stdlib=libc++ helloworld.cpp -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc</code></li> 424 </ul> 425 Alternately, you could just add libcxxrt to your libraries list, which in most 426 situations will give the same result: 427 <ul> 428 <li><code>clang++ -stdlib=libc++ helloworld.cpp -lcxxrt</code></li> 429 </ul> 430 </p> 431 </p> 432 433 <!--=====================================================================--> 434 <h2 id="local-abi">Using a local ABI library</h2> 435 <!--=====================================================================--> 436 <p> 437 <strong>Note: This is not recommended in almost all cases.</strong><br> 438 Generally these instructions should only be used when you can't install 439 your ABI library. 440 </p> 441 <p> 442 Normally you must link libc++ against a ABI shared library that the 443 linker can find. If you want to build and test libc++ against an ABI 444 library not in the linker's path you need to set 445 <code>-DLIBCXX_CXX_ABI_LIBRARY_PATH=/path/to/abi/lib</code> when 446 configuring CMake. 447 </p> 448 <p> 449 An example build using libc++abi would look like: 450 <ul> 451 <li><code>CC=clang CXX=clang++ cmake 452 -DLIBCXX_CXX_ABI=libc++abi 453 -DLIBCXX_LIBCXXABI_INCLUDE_PATHS="/path/to/libcxxabi/include" 454 -DLIBCXX_CXX_ABI_LIBRARY_PATH="/path/to/libcxxabi-build/lib" 455 path/to/libcxx</code></li> 456 <li><code>make</code></li> 457 </ul> 458 </p> 459 <p> 460 When testing libc++ LIT will automatically link against the proper ABI 461 library. 462 </p> 463 464 <!--=====================================================================--> 465 <h2>Design Documents</h2> 466 <!--=====================================================================--> 467 468 <ul> 469 <li><a href="atomic_design.html"><tt><atomic></tt></a></li> 470 <li><a href="type_traits_design.html"><tt><type_traits></tt></a></li> 471 <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> 472 <li><a href="debug_mode.html">Status of debug mode</a></li> 473 <li><a href="lit_usage.html">LIT usage guide</a></li> 474 </ul> 475 476 </div> 477 </body> 478 </html> 479
