| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" | |
| "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> | |
| <div class="submenu"> | |
| <label>libc++ Info</label> | |
| <a href="/index.html">About</a> | |
| </div> | |
| <div class="submenu"> | |
| <label>Quick Links</label> | |
| <a href="http://lists.llvm.org/mailman/listinfo/cfe-dev">cfe-dev</a> | |
| <a href="http://lists.llvm.org/mailman/listinfo/cfe-commits">cfe-commits</a> | |
| <a href="http://llvm.org/bugs/">Bug Reports</a> | |
| <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> | |
| </div> | |
| </div> | |
| <div id="content"> | |
| <!--*********************************************************************--> | |
| <h1>"libc++" C++ Standard Library</h1> | |
| <!--*********************************************************************--> | |
| <p>libc++ is a new implementation of the C++ standard library, targeting | |
| C++11.</p> | |
| <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> | |
| <!--=====================================================================--> | |
| <h2>New Documentation Coming Soon!</h2> | |
| <!--=====================================================================--> | |
| <p> Looking for documentation on how to use, build and test libc++? If so | |
| checkout the new libc++ documentation.</p> | |
| <p><a href="http://libcxx.llvm.org/docs/"> | |
| Click here for the new libc++ documentation.</a></p> | |
| <!--=====================================================================--> | |
| <h2 id="goals">Features and Goals</h2> | |
| <!--=====================================================================--> | |
| <ul> | |
| <li>Correctness as defined by the C++11 standard.</li> | |
| <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> | |
| <!--=====================================================================--> | |
| <h2 id="why">Why a new C++ Standard Library for C++11?</h2> | |
| <!--=====================================================================--> | |
| <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> | |
| <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 | |
| machines (particularly in C++11, which has rvalue references). Breaking | |
| ABI compatibility with old versions of the library was | |
| determined to be critical to achieving the performance goals of | |
| libc++.</p></li> | |
| <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 | |
| independently extended to support C++11, but this would be a fork of the | |
| 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> | |
| </li> | |
| <li><p>STLport and the Apache libstdcxx library are two other popular | |
| candidates, but both lack C++11 support. Our experience (and the | |
| experience of libstdc++ developers) is that adding support for C++11 (in | |
| particular rvalue references and move-only types) requires changes to | |
| almost every class and function, essentially amounting to a rewrite. | |
| Faced with a rewrite, we decided to start from scratch and evaluate every | |
| design decision from first principles based on experience.</p> | |
| <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> | |
| <!--=====================================================================--> | |
| <h2 id="requirements">Platform Support</h2> | |
| <!--=====================================================================--> | |
| <p> | |
| libc++ is known to work on the following platforms, using g++-4.2 and | |
| clang (lack of C++11 language support disables some functionality). Note | |
| that functionality provided by <atomic> is only functional with | |
| clang. | |
| </p> | |
| <ul> | |
| <li>Mac OS X i386</li> | |
| <li>Mac OS X x86_64</li> | |
| <li>FreeBSD 10+ i386</li> | |
| <li>FreeBSD 10+ x86_64</li> | |
| <li>FreeBSD 10+ ARM</li> | |
| </ul> | |
| <!--=====================================================================--> | |
| <h2 id="dir-structure">Current Status</h2> | |
| <!--=====================================================================--> | |
| <p>libc++ is a 100% complete C++11 implementation on Apple's OS X. </p> | |
| <p>LLVM and Clang can self host in C++ and C++11 mode with libc++ on Linux.</p> | |
| <p>libc++ is also a 100% complete C++14 implementation. A list of new features and changes for | |
| C++14 can be found <a href="cxx1y_status.html">here</a>.</p> | |
| <p>A list of features and changes for the next C++ standard, known here as | |
| "C++1z" (probably to be C++17) can be found <a href="cxx1z_status.html">here</a>.</p> | |
| <p>Implementation of the post-c++14 Technical Specifications is in progress. A list of features and | |
| the current status of these features can be found <a href="ts1z_status.html">here</a>.</p> | |
| <p> | |
| 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>. | |
| </p> | |
| <!--======================================================================--> | |
| <h2 id="buildbots">Build Bots</h2> | |
| <!--======================================================================--> | |
| <p>The latest libc++ build results can be found at the following locations.</p> | |
| <ul> | |
| <li><a href="http://lab.llvm.org:8011/console"> | |
| Buildbot libc++ builders | |
| </a></li> | |
| <li><a href="http://lab.llvm.org:8080/green/view/Libcxx/"> | |
| Jenkins libc++ builders | |
| </a></li> | |
| </ul> | |
| <!--=====================================================================--> | |
| <h2>Get it and get involved!</h2> | |
| <!--=====================================================================--> | |
| <p>First please review our | |
| <a href="http://llvm.org/docs/DeveloperPolicy.html">Developer's Policy</a>. | |
| <p> | |
| On Mac OS 10.7 (Lion) and later, the easiest way to get this library is to install | |
| Xcode 4.2 or later. However if you want to install tip-of-trunk from here | |
| (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>. | |
| </p> | |
| <p>To check out the code, use:</p> | |
| <ul> | |
| <li><code>svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx</code></li> | |
| </ul> | |
| <p> | |
| Note that for an in-tree build, you should check out libcxx to | |
| llvm/projects. | |
| </p> | |
| <p> | |
| The following instructions are for building libc++ on FreeBSD, Linux, or Mac | |
| using <a href="http://libcxxabi.llvm.org/">libc++abi</a> as the C++ ABI | |
| library. On Linux, it is also possible to use | |
| <a href="#libsupcxx">libsupc++</a> or <a href="#libcxxrt">libcxxrt</a>. | |
| </p> | |
| <p>In-tree build:</p> | |
| <ul> | |
| <li><code>cd where-you-want-to-live</code></li> | |
| <li>Check out libcxx and <a href="http://libcxxabi.llvm.org/">libcxxabi</a> | |
| into llvm/projects</li> | |
| <li><code>cd where-you-want-to-build</code></li> | |
| <li><code>mkdir build && cd build</code></li> | |
| <li><code>cmake path/to/llvm # Linux may require -DCMAKE_C_COMPILER=clang | |
| -DCMAKE_CXX_COMPILER=clang++</code></li> | |
| <li><code>make cxx</code></li> | |
| </ul> | |
| <p>Out-of-tree buildc:</p> | |
| <ul> | |
| <li><code>cd where-you-want-to-live</code></li> | |
| <li>Check out libcxx and llvm</li> | |
| <li>If not on a Mac, also check out | |
| <a href="http://libcxxabi.llvm.org/">libcxxabi</a></li> | |
| <li><code>cd where-you-want-to-build</code></li> | |
| <li><code>mkdir build && cd build</code></li> | |
| <li><code>cmake -DLLVM_PATH=path/to/llvm | |
| -DLIBCXX_CXX_ABI=libcxxabi | |
| -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxabi/include | |
| -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ | |
| path/to/libcxx | |
| </code></li> | |
| <li><code>make</code></li> | |
| </ul> | |
| <p>To run the tests:</p> | |
| <ul> | |
| <li><code>make check-libcxx</code></li> | |
| </ul> | |
| <p>If you wish to run a subset of the test suite:</p> | |
| <ul> | |
| <li><code>cd path/to/libcxx/libcxx</code></li> | |
| <li><code>alias lit='python path/to/llvm/utils/lit/lit.py'</code></li> | |
| <li><code>export | |
| LIBCXX_SITE_CONFIG=path/to/build/dir/projects/libcxx/test/lit.site.cfg | |
| </code></li> | |
| <li><code>lit -sv test/re/ # or whichever subset of tests you're interested | |
| in</code></li> | |
| </ul> | |
| <p>The above is currently quite inconvenient. Sorry! We're working on it!</p> | |
| <p>More information on using LIT can be found | |
| <a href="http://llvm.org/docs/CommandGuide/lit.html">here</a>. For more | |
| general information about the LLVM testing infrastructure, see the | |
| <a href="http://llvm.org/docs/TestingGuide.html">LLVM Testing Infrastructure | |
| Guide</a> | |
| </p> | |
| <p> | |
| Shared libraries for libc++ should now be present in llvm/build/lib. Note | |
| that it is safest to use this from its current location rather than | |
| replacing your system's libc++ (if it has one, if not, go right ahead). | |
| </p> | |
| <p> | |
| Mac users, remember to be careful when replacing the system's libc++. | |
| <strong>Your system will not be able to boot without a functioning | |
| libc++.</strong> | |
| </p> | |
| <!--=====================================================================--> | |
| <h3>Notes and Known Issues</h3> | |
| <!--=====================================================================--> | |
| <p> | |
| <ul> | |
| <li> | |
| Building libc++ with <code>-fno-rtti</code> is not supported. However | |
| linking against it with <code>-fno-rtti</code> is supported. | |
| </li> | |
| <li> | |
| On OS X v10.8 and older the CMake option | |
| <code>-DLIBCXX_LIBCPPABI_VERSION=""</code> must be used during | |
| configuration. | |
| </li> | |
| </ul> | |
| </p> | |
| <p>Send discussions to the | |
| <a href="http://lists.llvm.org/mailman/listinfo/cfe-dev">clang mailing list</a>.</p> | |
| <!--=====================================================================--> | |
| <h2>Using libc++ in your programs</h2> | |
| <!--=====================================================================--> | |
| <!--=====================================================================--> | |
| <h3>FreeBSD and Mac OS X</h3> | |
| <!--=====================================================================--> | |
| <p> | |
| To use your system-installed libc++ with clang you can: | |
| </p> | |
| <ul> | |
| <li><code>clang++ -stdlib=libc++ test.cpp</code></li> | |
| <li><code>clang++ -std=c++11 -stdlib=libc++ test.cpp</code></li> | |
| </ul> | |
| <p> | |
| To use your tip-of-trunk libc++ on Mac OS with clang you can: | |
| </p> | |
| <ul> | |
| <li><code>export DYLD_LIBRARY_PATH=path/to/build/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> | |
| </ul> | |
| <!--=====================================================================--> | |
| <h3>Linux</h3> | |
| <!--=====================================================================--> | |
| <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> | |
| 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: | |
| </p> | |
| <ul> | |
| <li><code>clang++ -stdlib=libc++ helloworld.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc</code></li> | |
| </ul> | |
| <p> | |
| Alternately, you could just add libc++abi to your libraries list, which in | |
| most situations will give the same result: | |
| </p> | |
| <ul> | |
| <li><code>clang++ -stdlib=libc++ helloworld.cpp -lc++abi</code></li> | |
| </ul> | |
| <!--=====================================================================--> | |
| <h2>Bug reports and patches</h2> | |
| <!--=====================================================================--> | |
| <p> | |
| If you think you've found a bug in libc++, please report it using | |
| the <a href="http://llvm.org/bugs">LLVM Bugzilla</a>. If you're not sure, you | |
| can post a message to the <a href="http://lists.llvm.org/mailman/listinfo/cfe-dev">cfe-dev</a> | |
| mailing list or on IRC. Please include "libc++" in your subject. | |
| </p> | |
| <p> | |
| If you want to contribute a patch to libc++, the best place for that is | |
| <a href="http://llvm.org/docs/Phabricator.html">Phabricator</a>. Please | |
| include [libc++] in the subject and add cfe-commits as a subscriber. | |
| </p> | |
| <!--=====================================================================--> | |
| <h2 id="libsupcxx">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=libstdc++ | |
| -DLIBCXX_CXX_ABI_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>You can also substitute <code>-DLIBCXX_CXX_ABI=libsupc++</code> | |
| above, which will cause the library to be linked to libsupc++ instead | |
| of libstdc++, but this is only recommended if you know that you will | |
| never need to link against libstdc++ in the same executable as libc++. | |
| GCC ships libsupc++ separately but only as a static library. If a | |
| program also needs to link against libstdc++, it will provide its | |
| own copy of libsupc++ and this can lead to subtle problems. | |
| <li><code>make</code></li> | |
| <li><code>sudo make install</code></li> | |
| </ul> | |
| <p> | |
| You can now run clang with -stdlib=libc++. | |
| </p> | |
| </p> | |
| <!--=====================================================================--> | |
| <h2 id="libcxxrt">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_CXX_ABI_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> | |
| <!--=====================================================================--> | |
| <h2 id="local-abi">Using a local ABI library</h2> | |
| <!--=====================================================================--> | |
| <p> | |
| <strong>Note: This is not recommended in almost all cases.</strong><br> | |
| Generally these instructions should only be used when you can't install | |
| your ABI library. | |
| </p> | |
| <p> | |
| Normally you must link libc++ against a ABI shared library that the | |
| linker can find. If you want to build and test libc++ against an ABI | |
| library not in the linker's path you need to set | |
| <code>-DLIBCXX_CXX_ABI_LIBRARY_PATH=/path/to/abi/lib</code> when | |
| configuring CMake. | |
| </p> | |
| <p> | |
| An example build using libc++abi would look like: | |
| <ul> | |
| <li><code>CC=clang CXX=clang++ cmake | |
| -DLIBCXX_CXX_ABI=libc++abi | |
| -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/path/to/libcxxabi/include" | |
| -DLIBCXX_CXX_ABI_LIBRARY_PATH="/path/to/libcxxabi-build/lib" | |
| path/to/libcxx</code></li> | |
| <li><code>make</code></li> | |
| </ul> | |
| </p> | |
| <p> | |
| When testing libc++ LIT will automatically link against the proper ABI | |
| library. | |
| </p> | |
| <!--=====================================================================--> | |
| <h2>Design Documents</h2> | |
| <!--=====================================================================--> | |
| <ul> | |
| <li><a href="atomic_design.html"><tt><atomic></tt></a></li> | |
| <li><a href="type_traits_design.html"><tt><type_traits></tt></a></li> | |
| <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> | |
| <li><a href="debug_mode.html">Status of debug mode</a></li> | |
| <li><a href="lit_usage.html">LIT usage guide</a></li> | |
| </ul> | |
| </div> | |
| </body> | |
| </html> |