index.html revision 641f6c1f655cb9936369ff7d069c7846771be040
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 implemenation on Apple's OS X. </p> 119 120 <p> 121 Ports to other platforms are underway. Here are recent test 122 results for <a href="results.Windows.html">Windows</a> 123 and <a href="results.Linux.html">Linux</a>. 124 </p> 125 126 <!--=====================================================================--> 127 <h2>Get it and get involved!</h2> 128 <!--=====================================================================--> 129 130 <p>First please review our 131 <a href="http://llvm.org/docs/DeveloperPolicy.html">Developer's Policy</a>. 132 133 <p>To check out the code, use:</p> 134 135 <ul> 136 <li><code>svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx</code></li> 137 </ul> 138 139 <p> 140 On Mac OS 10.7 (Lion) and later, the easiest way to get this library is to install 141 Xcode 4.2 or later. However if you want to install tip-of-trunk from here 142 (getting the bleeding edge), read on. However, be warned that Mac OS 143 10.7 will not boot without a valid copy of <code>libc++.1.dylib</code> in 144 <code>/usr/lib</code>. 145 </p> 146 147 <p> 148 Next: 149 </p> 150 151 <ul> 152 <li><code>cd libcxx/lib</code></li> 153 <li><code>export TRIPLE=-apple-</code></li> 154 <li><code>/buildit</code></li> 155 <li><code>ln -sf libc++.1.dylib libc++.dylib</code></li> 156 </ul> 157 158 <p> 159 That should result in a libc++.1.dylib and libc++.dylib. The safest thing 160 to do is to use it from where your libcxx is installed instead of replacing 161 these in your Mac OS. 162 </p> 163 164 <p> 165 To use your system-installed libc++ with clang you can: 166 </p> 167 168 <ul> 169 <li><code>clang++ -stdlib=libc++ test.cpp</code></li> 170 <li><code>clang++ -std=c++11 -stdlib=libc++ test.cpp</code></li> 171 </ul> 172 173 <p> 174 To use your tip-of-trunk libc++ on Mac OS with clang you can: 175 </p> 176 177 <ul> 178 <li><code>export DYLD_LIBRARY_PATH=<path-to-libcxx>/lib</code> 179 <li><code>clang++ -std=c++11 -stdlib=libc++ -nostdinc++ 180 -I<path-to-libcxx>/include -L<path-to-libcxx>/lib 181 test.cpp</code></li> 182 </ul> 183 184 <p>To run the libc++ test suite (recommended):</p> 185 186 <ul> 187 <li><code>cd libcxx/test</code></li> 188 <li><code>/testit</code></li> 189 <ul> 190 <li>You can alter the command line options <code>testit</code> uses 191 with <code>export OPTIONS="whatever you need"</code></li> 192 </ul> 193 </ul> 194 195 <!--=====================================================================--> 196 <h3>Notes</h3> 197 <!--=====================================================================--> 198 199<p> 200Building libc++ with <code>-fno-rtti</code> is not supported. However linking 201against it with <code>-fno-rtti</code> is supported. 202</p> 203 204 <p>Send discussions to the 205 (<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">clang mailing list</a>).</p> 206 207 <!--=====================================================================--> 208 <h2>Design Documents</h2> 209 <!--=====================================================================--> 210 211<ul> 212<li><a href="atomic_design.html"><tt><atomic></tt></a></li> 213<li><a href="type_traits_design.html"><tt><type_traits></tt></a></li> 214<li><a href="http://marshall.calepin.co/llvmclang-and-standard-libraries-on-mac-os-x.html">Excellent notes by Marshall Clow</a></li> 215</ul> 216 217</div> 218</body> 219</html> 220