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>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=&lt;path-to-libcxx&gt;/lib</code>
 182     <li><code>clang++ -std=c++11 -stdlib=libc++ -nostdinc++
 183          -I&lt;path-to-libcxx&gt;/include -L&lt;path-to-libcxx&gt;/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>
 203 Building libc++ with <code>-fno-rtti</code> is not supported.  However linking
 204 against 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++/&lt;version&gt;</code> and
 221      <code>/usr/include/c++/&lt;version&gt;/&lt;target-triple&gt;</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
 228 ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu"
 229 ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include"
 230 #include "..." search starts here:
 231 #include &lt;...&gt; 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
 240 End 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                 &lt;libc++-source-dir&gt;</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="&lt;libc++abi-source-dir&gt;/include"
 287                 -DCMAKE_BUILD_TYPE=Release
 288                 -DCMAKE_INSTALL_PREFIX=/usr
 289                 &lt;libc++-source-dir&gt;</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="&lt;libcxxrt-source-dir&gt;/src"
 325                 -DCMAKE_BUILD_TYPE=Release
 326                 -DCMAKE_INSTALL_PREFIX=/usr
 327                 &lt;libc++-source-dir&gt;</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>&lt;atomic&gt;</tt></a></li>
 352 <li><a href="type_traits_design.html"><tt>&lt;type_traits&gt;</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>