src/third_party/libc++/trunk/www/index.html

   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 &lt;atomic&gt; 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>Implementation of the post-c++14 Technical Specifications is in progress. A list of features and
 130       the current status of these features can be found <a href="ts1z_status.html">here</a>.</p>
 131    <p>
 132    Ports to other platforms are underway. Here are recent test
 133    results for <a href="results.Windows.html">Windows</a>
 134    and <a href="results.Linux.html">Linux</a>.
 135    </p>
 136
 137    <!--======================================================================-->
 138    <h2 id="dir-structure">Build Bots</h2>
 139    <!--======================================================================-->
 140    <p>These are the libc++ build bots</p>
 141    <ul>
 142       <li><a href="http://lab.llvm.org:8013/builders/libcxx_clang-x86_64-darwin11-RA">
 143         clang-libcxxabi-x86_64-darwin11
 144       </a></li>
 145       <li><a href="http://llvm-amd64.freebsd.your.org/b/builders/libcxx-amd64-freebsd">
 146         clang-libcxxrt-x86_64-freebsd10
 147       </a></li>
 148       <li><a href="http://llvm-amd64.freebsd.your.org/b/builders/libcxx-i386-freebsd">
 149         clang-libcxxrt-i386-freebsd10
 150       </a></li>
 151       <li><a href="http://lab.llvm.org:8011/builders/libcxx-libcxxabi-x86_64-linux-debian">
 152         clang-libcxxabi-x86_64-linux-debian
 153       </a></li>
 154     </ul>
 155
 156   <!--=====================================================================-->
 157   <h2>Get it and get involved!</h2>
 158   <!--=====================================================================-->
 159
 160   <p>First please review our
 161      <a href="http://llvm.org/docs/DeveloperPolicy.html">Developer's Policy</a>.
 162
 163   <p>
 164      On Mac OS 10.7 (Lion) and later, the easiest way to get this library is to install
 165      Xcode 4.2 or later.  However if you want to install tip-of-trunk from here
 166      (getting the bleeding edge), read on.  However, be warned that Mac OS
 167      10.7 will not boot without a valid copy of <code>libc++.1.dylib</code> in
 168      <code>/usr/lib</code>.
 169   </p>
 170
 171   <p>To check out the code, use:</p>
 172
 173   <ul>
 174   <li><code>svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx</code></li>
 175   </ul>
 176
 177   <p>
 178     Note that for an in-tree build, you should check out libcxx to
 179     llvm/projects.
 180   </p>
 181
 182   <p>
 183     The following instructions are for building libc++ on FreeBSD, Linux, or Mac
 184     using <a href="http://libcxxabi.llvm.org/">libc++abi</a> as the C++ ABI
 185     library. On Linux, it is also possible to use
 186     <a href="#libsupcxx">libsupc++</a> or <a href="#libcxxrt">libcxxrt</a>.
 187   </p>
 188
 189   <p>In-tree build:</p>
 190   <ul>
 191     <li>Check out libcxx and <a href="http://libcxxabi.llvm.org/">libcxxabi</a>
 192       into llvm/projects</li>
 193     <li><code>cd llvm</code></li>
 194     <li><code>mkdir build &amp;&amp; cd build</code></li>
 195     <li><code>cmake .. # Linux may require -DCMAKE_C_COMPILER=clang
 196         -DCMAKE_CXX_COMPILER=clang++</code></li>
 197     <li><code>make cxx</code></li>
 198   </ul>
 199
 200   <p>Out-of-tree build:</p>
 201   <ul>
 202     <li>Check out libcxx</li>
 203     <li>If not on a Mac, also check out
 204       <a href="http://libcxxabi.llvm.org/">libcxxabi</a></li>
 205     <li><code>cd libcxx</code></li>
 206     <li><code>mkdir build &amp;&amp; cd build</code></li>
 207     <li><code>cmake -DLIBCXX_CXX_ABI=libcxxabi
 208         -DLIBCXX_LIBCXXABI_INCLUDE_PATHS=path/to/libcxxabi/include
 209         -DLIT_EXECUTABLE=path/to/llvm/utils/lit/lit.py .. # Linux may require
 210         -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++</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>ln -s path/to/build/dir/projects/libcxx/test/lit.site.cfg
 224         test/lit.site.cfg</code></li>
 225     <li><code>lit -sv test/re/ # or whichever subset of tests you're interested
 226         in</code></li>
 227   </ul>
 228   <p>The above is currently quite inconvenient. Sorry! We're working on it!</p>
 229
 230   <p>More information on using LIT can be found
 231     <a href="http://llvm.org/docs/CommandGuide/lit.html">here</a>. For more
 232     general information about the LLVM testing infrastructure, see the
 233     <a href="http://llvm.org/docs/TestingGuide.html">LLVM Testing Infrastructure
 234       Guide</a>
 235   </p>
 236
 237   <p>
 238     Shared libraries for libc++ should now be present in llvm/build/lib. Note
 239     that it is safest to use this from its current location rather than
 240     replacing your system's libc++ (if it has one, if not, go right ahead).
 241   </p>
 242
 243   <p>
 244     Mac users, remember to be careful when replacing the system's libc++.
 245     <strong>Your system will not be able to boot without a funcioning
 246     libc++.</strong>
 247   </p>
 248
 249   <!--=====================================================================-->
 250   <h3>Notes</h3>
 251   <!--=====================================================================-->
 252
 253   <p>
 254     Building libc++ with <code>-fno-rtti</code> is not supported.  However
 255     linking against it with <code>-fno-rtti</code> is supported.
 256   </p>
 257
 258   <p>Send discussions to the
 259     <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">clang mailing list</a>.</p>
 260
 261   <!--=====================================================================-->
 262   <h2>Using libc++ in your programs</h2>
 263   <!--=====================================================================-->
 264
 265   <!--=====================================================================-->
 266   <h3>FreeBSD and Mac OS X</h3>
 267   <!--=====================================================================-->
 268
 269   <p>
 270     To use your system-installed libc++ with clang you can:
 271   </p>
 272
 273   <ul>
 274     <li><code>clang++ -stdlib=libc++ test.cpp</code></li>
 275     <li><code>clang++ -std=c++11 -stdlib=libc++ test.cpp</code></li>
 276   </ul>
 277
 278   <p>
 279     To use your tip-of-trunk libc++ on Mac OS with clang you can:
 280   </p>
 281
 282   <ul>
 283     <li><code>export DYLD_LIBRARY_PATH=path/to/build/lib</code>
 284     <li><code>clang++ -std=c++11 -stdlib=libc++ -nostdinc++
 285          -I&lt;path-to-libcxx&gt;/include -L&lt;path-to-libcxx&gt;/lib
 286          test.cpp</code></li>
 287   </ul>
 288
 289   <!--=====================================================================-->
 290   <h3>Linux</h3>
 291   <!--=====================================================================-->
 292
 293   <p>
 294     You will need to keep the source tree of
 295     <a href="http://libcxxabi.llvm.org">libc++abi</a> available on your build
 296     machine and your copy of the libc++abi shared library must be placed where
 297     your linker will find it.
 298   </p>
 299
 300   <p>
 301     Unfortunately you can't simply run clang with "-stdlib=libc++" at this
 302     point, as clang is set up to link for libc++ linked to libsupc++.  To get
 303     around this you'll have to set up your linker yourself (or patch clang).
 304     For example:
 305   </p>
 306
 307   <ul>
 308     <li><code>clang++ -stdlib=libc++ helloworld.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc</code></li>
 309   </ul>
 310
 311   <p>
 312     Alternately, you could just add libc++abi to your libraries list, which in
 313     most situations will give the same result:
 314   </p>
 315
 316   <ul>
 317     <li><code>clang++ -stdlib=libc++ helloworld.cpp -lc++abi</code></li>
 318   </ul>
 319
 320   <!--=====================================================================-->
 321   <h2>Bug reports and patches</h2>
 322   <!--=====================================================================-->
 323
 324 <p>
 325 If you think you've found a bug in libc++, please report it using
 326 the <a href="http://llvm.org/bugs">LLVM Bugzilla</a>. If you're not sure, you
 327 can post a message to the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">cfe-dev</a>
 328 mailing list or on IRC. Please include "libc++" in your subject.
 329 </p>
 330
 331 <p>
 332 If you want to contribute a patch to libc++, the best place for that is the
 333 <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits">cfe-commits</a>
 334 mailing list. Please include "libc++" and "PATCH" in your subject.
 335 </p>
 336
 337   <!--=====================================================================-->
 338   <h2 id="libsupcxx">Build on Linux using CMake and libsupc++.</h2>
 339   <!--=====================================================================-->
 340
 341   <p>
 342      You will need libstdc++ in order to provide libsupc++.
 343   </p>
 344
 345   <p>
 346      Figure out where the libsupc++ headers are on your system. On Ubuntu this
 347      is <code>/usr/include/c++/&lt;version&gt;</code> and
 348      <code>/usr/include/c++/&lt;version&gt;/&lt;target-triple&gt;</code>
 349   </p>
 350
 351   <p>
 352      You can also figure this out by running
 353      <pre>
 354 $ echo | g++ -Wp,-v -x c++ - -fsyntax-only
 355 ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu"
 356 ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include"
 357 #include "..." search starts here:
 358 #include &lt;...&gt; search starts here:
 359  /usr/include/c++/4.7
 360  /usr/include/c++/4.7/x86_64-linux-gnu
 361  /usr/include/c++/4.7/backward
 362  /usr/lib/gcc/x86_64-linux-gnu/4.7/include
 363  /usr/local/include
 364  /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed
 365  /usr/include/x86_64-linux-gnu
 366  /usr/include
 367 End of search list.
 368      </pre>
 369
 370       Note the first two entries happen to be what we are looking for. This
 371       may not be correct on other platforms.
 372   </p>
 373
 374   <p>
 375      We can now run CMake:
 376      <ul>
 377        <li><code>CC=clang CXX=clang++ cmake -G "Unix Makefiles"
 378                 -DLIBCXX_CXX_ABI=libstdc++
 379                 -DLIBCXX_LIBSUPCXX_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/"
 380                 -DCMAKE_BUILD_TYPE=Release
 381                 -DCMAKE_INSTALL_PREFIX=/usr
 382                 &lt;libc++-source-dir&gt;</code></li>
 383        <li>You can also substitute <code>-DLIBCXX_CXX_ABI=libsupc++</code>
 384        above, which will cause the library to be linked to libsupc++ instead
 385        of libstdc++, but this is only recommended if you know that you will
 386        never need to link against libstdc++ in the same executable as libc++.
 387        GCC ships libsupc++ separately but only as a static library.  If a
 388        program also needs to link against libstdc++, it will provide its
 389        own copy of libsupc++ and this can lead to subtle problems.
 390        <li><code>make</code></li>
 391        <li><code>sudo make install</code></li>
 392      </ul>
 393      <p>
 394         You can now run clang with -stdlib=libc++.
 395      </p>
 396   </p>
 397
 398   <!--=====================================================================-->
 399   <h2 id="libcxxrt">Build on Linux using CMake and libcxxrt.</h2>
 400   <!--=====================================================================-->
 401
 402   <p>
 403      You will need to keep the source tree of
 404      <a href="https://github.com/pathscale/libcxxrt/">libcxxrt</a> available
 405      on your build machine and your copy of the libcxxrt shared library must
 406      be placed where your linker will find it.
 407   </p>
 408
 409   <p>
 410      We can now run CMake:
 411      <ul>
 412        <li><code>CC=clang CXX=clang++ cmake -G "Unix Makefiles"
 413                 -DLIBCXX_CXX_ABI=libcxxrt
 414                 -DLIBCXX_LIBCXXRT_INCLUDE_PATHS="&lt;libcxxrt-source-dir&gt;/src"
 415                 -DCMAKE_BUILD_TYPE=Release
 416                 -DCMAKE_INSTALL_PREFIX=/usr
 417                 &lt;libc++-source-dir&gt;</code></li>
 418        <li><code>make</code></li>
 419        <li><code>sudo make install</code></li>
 420      </ul>
 421      <p>
 422         Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as
 423         clang is set up to link for libc++ linked to libsupc++.  To get around this
 424         you'll have to set up your linker yourself (or patch clang).  For example,
 425         <ul>
 426           <li><code>clang++ -stdlib=libc++ helloworld.cpp -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc</code></li>
 427         </ul>
 428         Alternately, you could just add libcxxrt to your libraries list, which in most
 429         situations will give the same result:
 430         <ul>
 431           <li><code>clang++ -stdlib=libc++ helloworld.cpp -lcxxrt</code></li>
 432         </ul>
 433      </p>
 434   </p>
 435
 436   <!--=====================================================================-->
 437   <h2>Design Documents</h2>
 438   <!--=====================================================================-->
 439
 440 <ul>
 441 <li><a href="atomic_design.html"><tt>&lt;atomic&gt;</tt></a></li>
 442 <li><a href="type_traits_design.html"><tt>&lt;type_traits&gt;</tt></a></li>
 443 <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>
 444 <li><a href="debug_mode.html">Status of debug mode</a></li>
 445 </ul>
 446
 447 </div>
 448 </body>
 449 </html>