Blame - www/index.html - platform/external/libcxx

blob: 9c0eee3f5d8acbd9d14277e9808696543ebe928f [file] [log] [blame]

Howard Hinnant	d2bb032	2010-08-22 01:04:38 +0000	[diff] [blame]	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
Howard Hinnant	bc8d3f9	2010-05-11 19:42:16 +0000	[diff] [blame]	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>
Howard Hinnant	d2bb032	2010-08-22 01:04:38 +0000	[diff] [blame]	17
Howard Hinnant	bc8d3f9	2010-05-11 19:42:16 +0000	[diff] [blame]	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>
Chris Lattner	a535ffd	2010-05-11 20:53:16 +0000	[diff] [blame]	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>
Howard Hinnant	bc8d3f9	2010-05-11 19:42:16 +0000	[diff] [blame]	27	<a href="http://llvm.org/bugs/">Bug Reports</a>
Howard Hinnant	76e1ffc	2010-05-11 20:51:20 +0000	[diff] [blame]	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>
Howard Hinnant	bc8d3f9	2010-05-11 19:42:16 +0000	[diff] [blame]	30	</div>
				31	</div>
				32
				33	<div id="content">
				34	<!--*********************************************************************-->
				35	<h1>"libc++" C++ Standard Library</h1>
				36	<!--*********************************************************************-->
Howard Hinnant	d2bb032	2010-08-22 01:04:38 +0000	[diff] [blame]	37
Howard Hinnant	bc8d3f9	2010-05-11 19:42:16 +0000	[diff] [blame]	38	<p>libc++ is a new implementation of the C++ standard library, targeting
				39	C++0X.</p>
				40
Chris Lattner	f38bc6e	2010-11-16 21:40:19 +0000	[diff] [blame]	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>
Howard Hinnant	d2bb032	2010-08-22 01:04:38 +0000	[diff] [blame]	44
Howard Hinnant	bc8d3f9	2010-05-11 19:42:16 +0000	[diff] [blame]	45	<!--=====================================================================-->
				46	<h2 id="goals">Features and Goals</h2>
				47	<!--=====================================================================-->
Howard Hinnant	d2bb032	2010-08-22 01:04:38 +0000	[diff] [blame]	48
Howard Hinnant	bc8d3f9	2010-05-11 19:42:16 +0000	[diff] [blame]	49	<ul>
				50	<li>Correctness as defined by the (currently draft) C++0X 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	<!--=====================================================================-->
Chris Lattner	24173b8	2010-05-12 22:21:15 +0000	[diff] [blame]	60	<h2 id="why">Why a new C++ Standard Library for C++'0x?</h2>
				61	<!--=====================================================================-->
Howard Hinnant	d2bb032	2010-08-22 01:04:38 +0000	[diff] [blame]	62
Chris Lattner	24173b8	2010-05-12 22:21:15 +0000	[diff] [blame]	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>
Howard Hinnant	d2bb032	2010-08-22 01:04:38 +0000	[diff] [blame]	67
Chris Lattner	24173b8	2010-05-12 22:21:15 +0000	[diff] [blame]	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
Chris Lattner	a5058d9	2010-05-12 22:30:22 +0000	[diff] [blame]	75	machines (particularly in C++'0x, which has rvalue references). Breaking
				76	ABI compatibility with old versions of the library was
Chris Lattner	24173b8	2010-05-12 22:21:15 +0000	[diff] [blame]	77	determined to be critical to achieving the performance goals of
				78	libc++.</p></li>
Howard Hinnant	d2bb032	2010-08-22 01:04:38 +0000	[diff] [blame]	79
Chris Lattner	24173b8	2010-05-12 22:21:15 +0000	[diff] [blame]	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++'0x, but this would be a fork of the
Chris Lattner	f338249	2010-05-12 22:33:00 +0000	[diff] [blame]	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>
Chris Lattner	24173b8	2010-05-12 22:21:15 +0000	[diff] [blame]	87	</li>
				88
				89	<li><p>STLport and the Apache libstdcxx library are two other popular
				90	candidates, but both lack C++'0x support. Our experience (and the
				91	experience of libstdc++ developers) is that adding support for C++0x (in
				92	particular rvalue references and move-only types) requires changes to
				93	almost every class and function, essentially amounting to a rewrite.
Chris Lattner	bfa808e	2010-05-12 22:34:21 +0000	[diff] [blame]	94	Faced with a rewrite, we decided to start from scratch and evaluate every
				95	design decision from first principles based on experience.</p>
Howard Hinnant	d2bb032	2010-08-22 01:04:38 +0000	[diff] [blame]	96
Chris Lattner	24173b8	2010-05-12 22:21:15 +0000	[diff] [blame]	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	<!--=====================================================================-->
Howard Hinnant	bc8d3f9	2010-05-11 19:42:16 +0000	[diff] [blame]	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++0X 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
Howard Hinnant	f6547cb	2010-09-05 17:31:48 +0000	[diff] [blame]	118	<p>libc++ is still under development. It has about 98% of
				119	<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3126.pdf">N3126</a>
Chris Lattner	24173b8	2010-05-12 22:21:15 +0000	[diff] [blame]	120	implemented/tested. C++'98 support is fully featured, and most of C++'0x
Howard Hinnant	f6547cb	2010-09-05 17:31:48 +0000	[diff] [blame]	121	support is as well. The only major missing piece of C++'0x support is
				122	<code><atomic></code>.</p>
Howard Hinnant	bc8d3f9	2010-05-11 19:42:16 +0000	[diff] [blame]	123
Howard Hinnant	d0e811a	2010-05-13 20:10:39 +0000	[diff] [blame]	124	<p><a href="libcxx_by_chapter.pdf">Here</a> is a by-chapter breakdown of what
				125	is passing tests and what isn't. This chart is currently based on testing
Dan Gohman	4b3a088	2010-06-04 14:16:02 +0000	[diff] [blame]	126	against g++-4.4.0 with -std=c++0x. </p>
Howard Hinnant	d0e811a	2010-05-13 20:10:39 +0000	[diff] [blame]	127
Howard Hinnant	0cbb3a1	2011-09-28 15:44:39 +0000	[diff] [blame]	128	<p>
				129	A Windows port is underway. <a href="results.Windows.html">Here</a> are
				130	recent test results.
				131	</p>
				132
Howard Hinnant	bc8d3f9	2010-05-11 19:42:16 +0000	[diff] [blame]	133	<!--=====================================================================-->
				134	<h2>Get it and get involved!</h2>
				135	<!--=====================================================================-->
Howard Hinnant	d2bb032	2010-08-22 01:04:38 +0000	[diff] [blame]	136
Howard Hinnant	2481cba	2011-09-30 16:58:02 +0000	[diff] [blame]	137	<p>First please review our
				138	<a href="http://llvm.org/docs/DeveloperPolicy.html">Developer's Policy</a>.
				139
Howard Hinnant	bc8d3f9	2010-05-11 19:42:16 +0000	[diff] [blame]	140	<p>To check out the code, use:</p>
Howard Hinnant	d2bb032	2010-08-22 01:04:38 +0000	[diff] [blame]	141
Howard Hinnant	bc8d3f9	2010-05-11 19:42:16 +0000	[diff] [blame]	142	<ul>
Chris Lattner	4b74895	2010-05-11 20:37:52 +0000	[diff] [blame]	143	<li><code>svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx</code></li>
Howard Hinnant	65451f1	2011-01-27 23:18:19 +0000	[diff] [blame]	144	</ul>
				145
Howard Hinnant	704f09b	2011-11-17 17:14:16 +0000	[diff] [blame]	146	<p>
				147	On Mac OS 10.7 (Lion), the easiest way to get this library is to install
				148	Xcode 4.2 or later. However if you want to install tip-of-trunk from here
				149	(getting the bleeding edge), read on.
				150	</p>
				151
				152	<p>To build on Mac OS X 10.6 (Snow Leopard), you need a helper library and header
Howard Hinnant	65451f1	2011-01-27 23:18:19 +0000	[diff] [blame]	153	<a href="http://home.roadrunner.com/~hinnant/libcppabi.zip">found here</a>.
Howard Hinnant	704f09b	2011-11-17 17:14:16 +0000	[diff] [blame]	154	cp cxxabi.h to /usr/include, and cp libc++abi.dylib to /usr/lib. On Mac OS
				155	X 10.7 (Lion) and later, this helper library and header are already installed
				156	for you.
Howard Hinnant	65451f1	2011-01-27 23:18:19 +0000	[diff] [blame]	157	<p>
				158
				159	<p>
				160	Next:
				161	</p>
				162
				163	<ul>
				164	<li><code>cd libcxx/lib</code></li>
				165	<li><code>export TRIPLE=-apple-</code></li>
Howard Hinnant	704f09b	2011-11-17 17:14:16 +0000	[diff] [blame]	166	<li>Only on 10.6: <code>export MACOSX_DEPLOYMENT_TARGET=10.6</code></li>
Howard Hinnant	65451f1	2011-01-27 23:18:19 +0000	[diff] [blame]	167	<li><code>./buildit</code></li>
				168	</ul>
				169
				170	<p>
				171	That should result in a libc++.1.dylib. To install it I like to use links
				172	instead of copying, but either should work:
				173	</p>
				174
				175	<ul>
				176	<li><code>cd /usr/lib</code></li>
Howard Hinnant	5a245db	2011-02-22 14:18:34 +0000	[diff] [blame]	177	<li><code>sudo ln -sf path-to-libcxx/lib/libc++.1.dylib libc++.1.dylib</code></li>
				178	<li><code>sudo ln -sf libc++.1.dylib libc++.dylib</code></li>
Howard Hinnant	65451f1	2011-01-27 23:18:19 +0000	[diff] [blame]	179	<li><code>cd /usr/include/c++</code></li>
				180	<li><code>sudo ln -sf path-to-libcxx/include v1</code></li>
				181	</ul>
				182
				183	<p>
				184	To use with clang you can:
				185	</p>
				186
				187	<ul>
				188	<li><code>clang++ -stdlib=libc++ test.cpp</code></li>
				189	<li><code>clang++ -std=c++0x -stdlib=libc++ test.cpp</code></li>
Howard Hinnant	bc8d3f9	2010-05-11 19:42:16 +0000	[diff] [blame]	190	</ul>
				191
				192	<p>To run the libc++ test suit (recommended):</p>
				193
				194	<ul>
Chris Lattner	4b74895	2010-05-11 20:37:52 +0000	[diff] [blame]	195	<li><code>cd libcxx/test</code></li>
Howard Hinnant	bc8d3f9	2010-05-11 19:42:16 +0000	[diff] [blame]	196	<li><code>./testit</code></li>
Howard Hinnant	f5d76a7	2011-06-22 12:13:55 +0000	[diff] [blame]	197	<ul>
Howard Hinnant	8b3fae3	2011-09-12 14:15:45 +0000	[diff] [blame]	198	<li>On Mac OS 10.6, to work around bugs in libc headers like
				199	math.h and inttypes.h, add "-U__STRICT_ANSI__" and
				200	"-D__STDC_FORMAT_MACROS" to the command line with:
				201	<blockquote>
				202	<pre>export OPTIONS="-std=c++0x -stdlib=libc++ -U__STRICT_ANSI__ -D__STDC_FORMAT_MACROS"</pre>
				203	</blockquote></li>
				204	<li>People porting libc++ to other OSes will likely have to
				205	define similar macros.</li>
Howard Hinnant	f5d76a7	2011-06-22 12:13:55 +0000	[diff] [blame]	206	</ul>
Howard Hinnant	bc8d3f9	2010-05-11 19:42:16 +0000	[diff] [blame]	207	</ul>
				208
Howard Hinnant	d2bb032	2010-08-22 01:04:38 +0000	[diff] [blame]	209	<p>Send discussions to the
Howard Hinnant	8c21737	2010-05-11 19:53:34 +0000	[diff] [blame]	210	(<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">clang mailing list</a>).</p>
				211
Howard Hinnant	56f0d5b	2010-10-05 16:44:40 +0000	[diff] [blame]	212	<!--=====================================================================-->
				213	<h2>Design Documents</h2>
				214	<!--=====================================================================-->
				215
				216	<ul>
				217	<li><a href="atomic_design.html"><tt><atomic></tt></a></li>
Howard Hinnant	9835d76	2010-11-19 01:38:58 +0000	[diff] [blame]	218	<li><a href="type_traits_design.html"><tt><type_traits></tt></a></li>
Howard Hinnant	56f0d5b	2010-10-05 16:44:40 +0000	[diff] [blame]	219	</ul>
				220
Howard Hinnant	bc8d3f9	2010-05-11 19:42:16 +0000	[diff] [blame]	221	</div>
				222	</body>
Chris Lattner	4b74895	2010-05-11 20:37:52 +0000	[diff] [blame]	223	</html>