2010-08-22 09:04:38 +08:00
|
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
2010-05-12 03:42:16 +08:00
|
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
|
|
|
<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
|
|
|
|
|
<html>
|
|
|
|
|
<head>
|
|
|
|
|
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
|
|
|
<title>"libc++" C++ Standard Library</title>
|
|
|
|
|
<link type="text/css" rel="stylesheet" href="menu.css">
|
|
|
|
|
<link type="text/css" rel="stylesheet" href="content.css">
|
|
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
<div id="menu">
|
|
|
|
|
<div>
|
|
|
|
|
<a href="http://llvm.org/">LLVM Home</a>
|
|
|
|
|
</div>
|
2010-08-22 09:04:38 +08:00
|
|
|
|
2010-05-12 03:42:16 +08:00
|
|
|
<div class="submenu">
|
|
|
|
|
<label>libc++ Info</label>
|
|
|
|
|
<a href="/index.html">About</a>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="submenu">
|
|
|
|
|
<label>Quick Links</label>
|
2010-05-12 04:53:16 +08:00
|
|
|
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">cfe-dev</a>
|
|
|
|
|
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits">cfe-commits</a>
|
2010-05-12 03:42:16 +08:00
|
|
|
<a href="http://llvm.org/bugs/">Bug Reports</a>
|
2010-05-12 04:51:20 +08:00
|
|
|
<a href="http://llvm.org/svn/llvm-project/libcxx/trunk/">Browse SVN</a>
|
|
|
|
|
<a href="http://llvm.org/viewvc/llvm-project/libcxx/trunk/">Browse ViewVC</a>
|
2010-05-12 03:42:16 +08:00
|
|
|
</div>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div id="content">
|
|
|
|
|
<!--*********************************************************************-->
|
|
|
|
|
<h1>"libc++" C++ Standard Library</h1>
|
|
|
|
|
<!--*********************************************************************-->
|
2010-08-22 09:04:38 +08:00
|
|
|
|
2010-05-12 03:42:16 +08:00
|
|
|
<p>libc++ is a new implementation of the C++ standard library, targeting
|
2012-07-19 23:57:51 +08:00
|
|
|
C++11.</p>
|
2010-05-12 03:42:16 +08:00
|
|
|
|
2010-11-17 05:40:19 +08:00
|
|
|
<p>All of the code in libc++ is <a
|
|
|
|
|
href="http://llvm.org/docs/DeveloperPolicy.html#license">dual licensed</a>
|
|
|
|
|
under the MIT license and the UIUC License (a BSD-like license).</p>
|
2010-08-22 09:04:38 +08:00
|
|
|
|
2010-05-12 03:42:16 +08:00
|
|
|
<!--=====================================================================-->
|
|
|
|
|
<h2 id="goals">Features and Goals</h2>
|
|
|
|
|
<!--=====================================================================-->
|
2010-08-22 09:04:38 +08:00
|
|
|
|
2010-05-12 03:42:16 +08:00
|
|
|
<ul>
|
2012-07-19 23:57:51 +08:00
|
|
|
<li>Correctness as defined by the C++11 standard.</li>
|
2010-05-12 03:42:16 +08:00
|
|
|
<li>Fast execution.</li>
|
|
|
|
|
<li>Minimal memory use.</li>
|
|
|
|
|
<li>Fast compile times.</li>
|
|
|
|
|
<li>ABI compatibility with gcc's libstdc++ for some low-level features
|
|
|
|
|
such as exception objects, rtti and memory allocation.</li>
|
|
|
|
|
<li>Extensive unit tests.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
2010-05-13 06:21:15 +08:00
|
|
|
<!--=====================================================================-->
|
2012-11-15 00:31:15 +08:00
|
|
|
<h2 id="why">Why a new C++ Standard Library for C++11?</h2>
|
2010-05-13 06:21:15 +08:00
|
|
|
<!--=====================================================================-->
|
2010-08-22 09:04:38 +08:00
|
|
|
|
2010-05-13 06:21:15 +08:00
|
|
|
<p>After its initial introduction, many people have asked "why start a new
|
|
|
|
|
library instead of contributing to an existing library?" (like Apache's
|
|
|
|
|
libstdcxx, GNU's libstdc++, STLport, etc). There are many contributing
|
|
|
|
|
reasons, but some of the major ones are:</p>
|
2010-08-22 09:04:38 +08:00
|
|
|
|
2010-05-13 06:21:15 +08:00
|
|
|
<ul>
|
|
|
|
|
<li><p>From years of experience (including having implemented the standard
|
|
|
|
|
library before), we've learned many things about implementing
|
|
|
|
|
the standard containers which require ABI breakage and fundamental changes
|
|
|
|
|
to how they are implemented. For example, it is generally accepted that
|
|
|
|
|
building std::string using the "short string optimization" instead of
|
|
|
|
|
using Copy On Write (COW) is a superior approach for multicore
|
2012-11-15 00:31:15 +08:00
|
|
|
machines (particularly in C++11, which has rvalue references). Breaking
|
2010-05-13 06:30:22 +08:00
|
|
|
ABI compatibility with old versions of the library was
|
2010-05-13 06:21:15 +08:00
|
|
|
determined to be critical to achieving the performance goals of
|
|
|
|
|
libc++.</p></li>
|
2010-08-22 09:04:38 +08:00
|
|
|
|
2010-05-13 06:21:15 +08:00
|
|
|
<li><p>Mainline libstdc++ has switched to GPL3, a license which the developers
|
|
|
|
|
of libc++ cannot use. libstdc++ 4.2 (the last GPL2 version) could be
|
2012-11-15 00:31:15 +08:00
|
|
|
independently extended to support C++11, but this would be a fork of the
|
2010-05-13 06:33:00 +08:00
|
|
|
codebase (which is often seen as worse for a project than starting a new
|
|
|
|
|
independent one). Another problem with libstdc++ is that it is tightly
|
|
|
|
|
integrated with G++ development, tending to be tied fairly closely to the
|
|
|
|
|
matching version of G++.</p>
|
2010-05-13 06:21:15 +08:00
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
<li><p>STLport and the Apache libstdcxx library are two other popular
|
2012-11-15 00:31:15 +08:00
|
|
|
candidates, but both lack C++11 support. Our experience (and the
|
2012-07-19 23:57:51 +08:00
|
|
|
experience of libstdc++ developers) is that adding support for C++11 (in
|
2010-05-13 06:21:15 +08:00
|
|
|
particular rvalue references and move-only types) requires changes to
|
|
|
|
|
almost every class and function, essentially amounting to a rewrite.
|
2010-05-13 06:34:21 +08:00
|
|
|
Faced with a rewrite, we decided to start from scratch and evaluate every
|
|
|
|
|
design decision from first principles based on experience.</p>
|
2010-08-22 09:04:38 +08:00
|
|
|
|
2010-05-13 06:21:15 +08:00
|
|
|
<p>Further, both projects are apparently abandoned: STLport 5.2.1 was
|
|
|
|
|
released in Oct'08, and STDCXX 4.2.1 in May'08.</p>
|
|
|
|
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
2010-05-12 03:42:16 +08:00
|
|
|
<!--=====================================================================-->
|
|
|
|
|
<h2 id="requirements">Platform Support</h2>
|
|
|
|
|
<!--=====================================================================-->
|
|
|
|
|
|
|
|
|
|
<p>libc++ is known to work on the following platforms, using g++-4.2 and
|
2012-07-19 23:57:51 +08:00
|
|
|
clang (lack of C++11 language support disables some functionality).</p>
|
2010-05-12 03:42:16 +08:00
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
|
<li>Mac OS X i386</li>
|
|
|
|
|
<li>Mac OS X x86_64</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<!--=====================================================================-->
|
|
|
|
|
<h2 id="dir-structure">Current Status</h2>
|
|
|
|
|
<!--=====================================================================-->
|
|
|
|
|
|
2012-11-28 02:52:32 +08:00
|
|
|
<p>libc++ is a 100% complete C++11 implementation on Apple's OS X. </p>
|
2013-01-01 03:34:21 +08:00
|
|
|
<p>LLVM and Clang can self host in C++ and C++11 mode with libc++ on Linux.</p>
|
2010-05-14 04:10:39 +08:00
|
|
|
|
2011-09-28 23:44:39 +08:00
|
|
|
<p>
|
2012-08-01 05:30:28 +08:00
|
|
|
Ports to other platforms are underway. Here are recent test
|
|
|
|
|
results for <a href="results.Windows.html">Windows</a>
|
|
|
|
|
and <a href="results.Linux.html">Linux</a>.
|
2011-09-28 23:44:39 +08:00
|
|
|
</p>
|
|
|
|
|
|
2010-05-12 03:42:16 +08:00
|
|
|
<!--=====================================================================-->
|
|
|
|
|
<h2>Get it and get involved!</h2>
|
|
|
|
|
<!--=====================================================================-->
|
2010-08-22 09:04:38 +08:00
|
|
|
|
2011-10-01 00:58:02 +08:00
|
|
|
<p>First please review our
|
|
|
|
|
<a href="http://llvm.org/docs/DeveloperPolicy.html">Developer's Policy</a>.
|
|
|
|
|
|
2010-05-12 03:42:16 +08:00
|
|
|
<p>To check out the code, use:</p>
|
2010-08-22 09:04:38 +08:00
|
|
|
|
2010-05-12 03:42:16 +08:00
|
|
|
<ul>
|
2010-05-12 04:37:52 +08:00
|
|
|
<li><code>svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx</code></li>
|
2011-01-28 07:18:19 +08:00
|
|
|
</ul>
|
|
|
|
|
|
2011-11-18 01:14:16 +08:00
|
|
|
<p>
|
2012-11-07 05:31:37 +08:00
|
|
|
On Mac OS 10.7 (Lion) and later, the easiest way to get this library is to install
|
2011-11-18 01:14:16 +08:00
|
|
|
Xcode 4.2 or later. However if you want to install tip-of-trunk from here
|
2012-04-03 23:08:42 +08:00
|
|
|
(getting the bleeding edge), read on. However, be warned that Mac OS
|
|
|
|
|
10.7 will not boot without a valid copy of <code>libc++.1.dylib</code> in
|
|
|
|
|
<code>/usr/lib</code>.
|
2011-11-18 01:14:16 +08:00
|
|
|
</p>
|
|
|
|
|
|
2011-01-28 07:18:19 +08:00
|
|
|
<p>
|
|
|
|
|
Next:
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>cd libcxx/lib</code></li>
|
|
|
|
|
<li><code>export TRIPLE=-apple-</code></li>
|
|
|
|
|
<li><code>./buildit</code></li>
|
2012-11-07 05:31:37 +08:00
|
|
|
<li><code>ln -sf libc++.1.dylib libc++.dylib</code></li>
|
2011-01-28 07:18:19 +08:00
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<p>
|
2012-11-07 05:31:37 +08:00
|
|
|
That should result in a libc++.1.dylib and libc++.dylib. The safest thing
|
|
|
|
|
to do is to use it from where your libcxx is installed instead of replacing
|
|
|
|
|
these in your Mac OS.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
To use your system-installed libc++ with clang you can:
|
2011-01-28 07:18:19 +08:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<ul>
|
2012-11-07 05:31:37 +08:00
|
|
|
<li><code>clang++ -stdlib=libc++ test.cpp</code></li>
|
|
|
|
|
<li><code>clang++ -std=c++11 -stdlib=libc++ test.cpp</code></li>
|
2011-01-28 07:18:19 +08:00
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<p>
|
2012-11-07 05:31:37 +08:00
|
|
|
To use your tip-of-trunk libc++ on Mac OS with clang you can:
|
2011-01-28 07:18:19 +08:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<ul>
|
2012-11-07 05:31:37 +08:00
|
|
|
<li><code>export DYLD_LIBRARY_PATH=<path-to-libcxx>/lib</code>
|
|
|
|
|
<li><code>clang++ -std=c++11 -stdlib=libc++ -nostdinc++
|
|
|
|
|
-I<path-to-libcxx>/include -L<path-to-libcxx>/lib
|
|
|
|
|
test.cpp</code></li>
|
2010-05-12 03:42:16 +08:00
|
|
|
</ul>
|
|
|
|
|
|
2012-08-22 08:57:11 +08:00
|
|
|
<p>To run the libc++ test suite (recommended):</p>
|
2010-05-12 03:42:16 +08:00
|
|
|
|
|
|
|
|
<ul>
|
2010-05-12 04:37:52 +08:00
|
|
|
<li><code>cd libcxx/test</code></li>
|
2010-05-12 03:42:16 +08:00
|
|
|
<li><code>./testit</code></li>
|
2011-06-22 20:13:55 +08:00
|
|
|
<ul>
|
2012-11-07 05:31:37 +08:00
|
|
|
<li>You can alter the command line options <code>testit</code> uses
|
|
|
|
|
with <code>export OPTIONS="whatever you need"</code></li>
|
2011-06-22 20:13:55 +08:00
|
|
|
</ul>
|
2010-05-12 03:42:16 +08:00
|
|
|
</ul>
|
|
|
|
|
|
2012-05-20 21:03:53 +08:00
|
|
|
<!--=====================================================================-->
|
|
|
|
|
<h3>Notes</h3>
|
|
|
|
|
<!--=====================================================================-->
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
Building libc++ with <code>-fno-rtti</code> is not supported. However linking
|
|
|
|
|
against it with <code>-fno-rtti</code> is supported.
|
|
|
|
|
</p>
|
|
|
|
|
|
2010-08-22 09:04:38 +08:00
|
|
|
<p>Send discussions to the
|
2010-05-12 03:53:34 +08:00
|
|
|
(<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">clang mailing list</a>).</p>
|
|
|
|
|
|
2013-01-01 03:34:21 +08:00
|
|
|
<!--=====================================================================-->
|
|
|
|
|
<h2>Build on Linux using CMake and libsupc++.</h2>
|
|
|
|
|
<!--=====================================================================-->
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
You will need libstdc++ in order to provide libsupc++.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
Figure out where the libsupc++ headers are on your system. On Ubuntu this
|
|
|
|
|
is <code>/usr/include/c++/<version></code> and
|
|
|
|
|
<code>/usr/include/c++/<version>/<target-triple></code>
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
You can also figure this out by running
|
|
|
|
|
<pre>
|
|
|
|
|
$ echo | g++ -Wp,-v -x c++ - -fsyntax-only
|
|
|
|
|
ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu"
|
|
|
|
|
ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include"
|
|
|
|
|
#include "..." search starts here:
|
|
|
|
|
#include <...> search starts here:
|
|
|
|
|
/usr/include/c++/4.7
|
|
|
|
|
/usr/include/c++/4.7/x86_64-linux-gnu
|
|
|
|
|
/usr/include/c++/4.7/backward
|
|
|
|
|
/usr/lib/gcc/x86_64-linux-gnu/4.7/include
|
|
|
|
|
/usr/local/include
|
|
|
|
|
/usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed
|
|
|
|
|
/usr/include/x86_64-linux-gnu
|
|
|
|
|
/usr/include
|
|
|
|
|
End of search list.
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
Note the first two entries happen to be what we are looking for. This
|
|
|
|
|
may not be correct on other platforms.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
We can now run CMake:
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>CC=clang CXX=clang++ cmake -G "Unix Makefiles"
|
|
|
|
|
-DLIBCXX_CXX_ABI=libsupc++
|
|
|
|
|
-DLIBCXX_LIBSUPCXX_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/"
|
|
|
|
|
-DCMAKE_BUILD_TYPE=Release
|
|
|
|
|
-DCMAKE_INSTALL_PREFIX=/usr
|
|
|
|
|
<libc++-source-dir></code></li>
|
|
|
|
|
<li><code>make</code></li>
|
|
|
|
|
<li><code>sudo make install</code></li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
You can now run clang with -stdlib=libc++.
|
|
|
|
|
</p>
|
|
|
|
|
</p>
|
|
|
|
|
|
2013-02-09 03:10:36 +08:00
|
|
|
<!--=====================================================================-->
|
|
|
|
|
<h2>Build on Linux using CMake and libc++abi.</h2>
|
|
|
|
|
<!--=====================================================================-->
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
You will need to keep the source tree of <a href="http://libcxxabi.llvm.org">libc++abi</a>
|
|
|
|
|
available on your build machine and your copy of the libc++abi shared library must
|
|
|
|
|
be placed where your linker will find it.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
We can now run CMake:
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>CC=clang CXX=clang++ cmake -G "Unix Makefiles"
|
|
|
|
|
-DLIBCXX_CXX_ABI=libcxxabi
|
|
|
|
|
-DLIBCXX_LIBCXXABI_INCLUDE_PATHS="<libc++abi-source-dir>/include"
|
|
|
|
|
-DCMAKE_BUILD_TYPE=Release
|
|
|
|
|
-DCMAKE_INSTALL_PREFIX=/usr
|
|
|
|
|
<libc++-source-dir></code></li>
|
|
|
|
|
<li><code>make</code></li>
|
|
|
|
|
<li><code>sudo make install</code></li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as
|
|
|
|
|
clang is set up to link for libc++ linked to libsupc++. To get around this
|
|
|
|
|
you'll have to set up your linker yourself (or patch clang). For example,
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>clang++ -stdlib=libc++ helloworld.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc</code></li>
|
|
|
|
|
</ul>
|
|
|
|
|
Alternately, you could just add libc++abi to your libraries list, which in most
|
|
|
|
|
situations will give the same result:
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>clang++ -stdlib=libc++ helloworld.cpp -lc++abi</code></li>
|
|
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<!--=====================================================================-->
|
|
|
|
|
<h2>Build on Linux using CMake and libcxxrt.</h2>
|
|
|
|
|
<!--=====================================================================-->
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
You will need to keep the source tree of
|
|
|
|
|
<a href="https://github.com/pathscale/libcxxrt/">libcxxrt</a> available
|
|
|
|
|
on your build machine and your copy of the libcxxrt shared library must
|
|
|
|
|
be placed where your linker will find it.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
We can now run CMake:
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>CC=clang CXX=clang++ cmake -G "Unix Makefiles"
|
|
|
|
|
-DLIBCXX_CXX_ABI=libcxxrt
|
|
|
|
|
-DLIBCXX_LIBCXXABI_INCLUDE_PATHS="<libcxxrt-source-dir>/src"
|
|
|
|
|
-DCMAKE_BUILD_TYPE=Release
|
|
|
|
|
-DCMAKE_INSTALL_PREFIX=/usr
|
|
|
|
|
<libc++-source-dir></code></li>
|
|
|
|
|
<li><code>make</code></li>
|
|
|
|
|
<li><code>sudo make install</code></li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as
|
|
|
|
|
clang is set up to link for libc++ linked to libsupc++. To get around this
|
|
|
|
|
you'll have to set up your linker yourself (or patch clang). For example,
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>clang++ -stdlib=libc++ helloworld.cpp -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc</code></li>
|
|
|
|
|
</ul>
|
|
|
|
|
Alternately, you could just add libcxxrt to your libraries list, which in most
|
|
|
|
|
situations will give the same result:
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>clang++ -stdlib=libc++ helloworld.cpp -lcxxrt</code></li>
|
|
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
</p>
|
|
|
|
|
|
2010-10-06 00:44:40 +08:00
|
|
|
<!--=====================================================================-->
|
|
|
|
|
<h2>Design Documents</h2>
|
|
|
|
|
<!--=====================================================================-->
|
|
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
|
<li><a href="atomic_design.html"><tt><atomic></tt></a></li>
|
2010-11-19 09:38:58 +08:00
|
|
|
<li><a href="type_traits_design.html"><tt><type_traits></tt></a></li>
|
2012-07-06 08:39:38 +08:00
|
|
|
<li><a href="http://marshall.calepin.co/llvmclang-and-standard-libraries-on-mac-os-x.html">Excellent notes by Marshall Clow</a></li>
|
2010-10-06 00:44:40 +08:00
|
|
|
</ul>
|
|
|
|
|
|
2010-05-12 03:42:16 +08:00
|
|
|
</div>
|
|
|
|
|
</body>
|
2010-05-12 04:37:52 +08:00
|
|
|
</html>
|
