Libc++

"Libc++" C + + standard Library

Libc++ is a new implementation of the C + + standard library, targeting c++11.

All of the code in libc++ are dual licensed under the MIT license and the UIUC license (a bsd-like license).

Features and goals

• Correctness as defined by the C++11 standard.
• Fast execution.
• Minimal memory use.
• Fast compile times.
• ABI compatibility with GCC's libstdc++ for some low-level features such as exception objects, RTTI and memory allocation.
• Extensive unit tests.

Why a new C + + standard Library for c++11?

After its initial introduction, many people has asked "why start a new library instead of contributing to an existing Lib Rary? " (like Apache ' s libstdcxx, GNU ' s libstdc++, STLport, etc). There is many contributing reasons, but some of the major ones is:

• From years of experience (including have implemented the standard library before), we ' ve learned many things about imple Menting the standard containers which require ABI breakage and fundamental changes to how they is implemented. For example, it's generally accepted that building std::string using the ' Short string optimization ' instead of using Cop Y on Write (COW) are a superior approach for multicore machines (particularly in c++11, which have rvalue references). Breaking ABI compatibility with old versions of the library is determined to being critical to achieving the performance Goa LS of libc++.

• Mainline libstdc++ have switched to GPL3, a license which the developers of libc++ cannot use. libstdc++ 4.2 (The LA St GPL2 version) could be independently extended to support c++11, but this would be a fork of the codebase (which is ofte n seen as worse for a project than starting a new independent one). Another problem with Libstdc++ was that it was tightly integrated with g++ development, tending to being tied fairly closely to The matching version of g++.

• STLport and the Apache Libstdcxx Library is the other popular candidates, but both lack c++11 support. Our experience (and the experience of libstdc++ developers) are that adding support for c++11 (in particular rvalue Referen CES 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 E Xperience.

  Further, both projects is apparently Abandoned:stlport 5.2.1 is released in Oct ', and Stdcxx 4.2.1 in May ' 08.

Platform Support

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> are only functional with clang.

• Mac OS X i386
• Mac OS X x86_64
• FreeBSD i386
• FreeBSD x86_64
• FreeBSD + + ARM

Current Status

Libc++ is a 100% complete c++11 implementation on Apple's OS x.

LLVM and Clang can self host in C + + and c++11 mode with libc++ on Linux.

Libc++ is also a 100% complete c++14 implementation. A List of new features and changes for C++14 can is found here.

A List of features and changes for the next C + + standard, known this as "c++1z" (probably to be c++17) can is found here.

Implementation of the POST-C++14 Technical specifications are in progress. A List of features and the current status of these features can is found here.

Ports to other platforms is underway. Here is recent test results for Windows and Linux.

Build Bots

The latest libc++ build results can be found at the following locations.

• Buildbot libc++ Builders
• Jenkins libc++ Builders

Get it and get involved!

First please review our Developer ' s Policy.

On Mac OS 10.7 (Lion) and later, the easiest-to-get this library is to install Xcode 4.2 or later. However if want to install Tip-of-trunk from here (getting the bleeding edge), read on. However, be warned that Mac OS 10.7 would not boot without a valid copy of libc++.1.dylib in /usr/lib .

To check out the code, use:

• svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx

Note that for the In-tree build, you should check out libcxx to Llvm/projects.

The following instructions is for building libc++ on FreeBSD, Linux, or MAC using Libc++abi as the C + + ABI library. On Linux, it's also possible to use libsupc++ or LIBCXXRT.

In-tree Build:

• Check out Libcxx and Libcxxabi into llvm/projects
• cd llvm
• mkdir build && cd build
• cmake .. # Linux may require -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
• make cxx

Out-of-tree Build:

• Check out Libcxx
• If not on a Mac, also check out Libcxxabi
• cd libcxx
• mkdir build && cd build
• cmake -DLIBCXX_CXX_ABI=libcxxabi -DLIBCXX_LIBCXXABI_INCLUDE_PATHS=path/to/libcxxabi/include -DLIT_EXECUTABLE=path/to/llvm/utils/lit/lit.py .. # Linux may require -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
• make

To run the tests:

• make check-libcxx

If you wish to run a subset of the test suite:

• cd path/to/libcxx/libcxx
• alias lit=‘python path/to/llvm/utils/lit/lit.py‘
• ln -s path/to/build/dir/projects/libcxx/test/lit.site.cfg test/lit.site.cfg
• lit -sv test/re/ # or whichever subset of tests you‘re interested in

The above is currently quite inconvenient. sorry! We ' re working on it!

More information on using LIT can is found here. For more general information on the LLVM testing infrastructure, see the LLVM Testing infrastructure guide

Shared libraries for libc++ should now is present in Llvm/build/lib. Note that it was safest to the use of this from their current location rather than replacing your system's libc++ (if it has one, if Not, go right ahead).

Mac users, remember to is careful when replacing the system ' s libc++. Your System is not being able to boot without a funcioning libc++.

Notes

Building libc++ with are not -fno-rtti supported. However linking against it with IS -fno-rtti supported.

Send discussions to the Clang mailing list.

Using libc++ in your Programsfreebsd and Mac OS X

To use your system-installed libc++ with clang can:

• clang++ -stdlib=libc++ test.cpp
• clang++ -std=c++11 -stdlib=libc++ test.cpp

To use your tip-of-trunk libc++ on Mac OS with clang can:

• export DYLD_LIBRARY_PATH=path/to/build/lib
• clang++ -std=c++11 -stdlib=libc++ -nostdinc++ -I<path-to-libcxx>/include -L<path-to-libcxx>/lib test.cpp

Linux

You'll need to keep the source tree of Libc++abi available on your build machine and your copy of the Libc++abi shared L Ibrary must be placed where your linker would find it.

Unfortunately you can ' t simply run clang with "-stdlib=libc++" at this point, as clang are set up to link for libc++ linked To libsupc++. To get around this you'll have the to set up your linker yourself (or patch clang). For example:

• clang++ -stdlib=libc++ helloworld.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc

Alternately, could just add Libc++abi to your libraries list, which in most situations would give the same result:

• clang++ -stdlib=libc++ helloworld.cpp -lc++abi

Bug reports and Patches

If you think your found a bug in libc++, please report it using the LLVM Bugzilla. If you ' re not sure, you can post a message to the Cfe-dev mailing list or on IRC. Please include "libc++" in your subject.

If you are want to contribute a patch to libc++, the best place for so is the Cfe-commits mailing list. Please include "libc++" and "patches" in your subject.

Build on Linux using CMake and libsupc++.

You'll need libstdc++ in order to provide libsupc++.

Figure out where the libsupc++ headers is on your system. On Ubuntu this is and /usr/include/c++/<version>/usr/include/c++/<version>/<target-triple>

You can also figure this out by running

$ echo | g++-wp,-v-x C + +--fsyntax-onlyignoring 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/includeend of search list.     

Note the first and the entries happen to be, we are looking for. This May is correct on other platforms.

We can now run CMake:

• CC=clang CXX=clang++ cmake -G "Unix Makefiles" -DLIBCXX_CXX_ABI=libstdc++ -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>
• You can also substitute -DLIBCXX_CXX_ABI=libsupc++ above, which would cause the library to being linked to libsupc++ instead of libstdc++ is only recommended if you know so you'll 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'll provide its own copy of libsupc++ and this can leads to subtle p Roblems.
• make
• sudo make install

You can now run Clang with-stdlib=libc++.

Build on Linux using CMake and LIBCXXRT.

You'll need to keep the source tree of LIBCXXRT available on your build machine and your copy of the LIBCXXRT shared Lib Rary must be placed where your linker would find it.

We can now run CMake:

• CC=clang CXX=clang++ cmake -G "Unix Makefiles" -DLIBCXX_CXX_ABI=libcxxrt -DLIBCXX_LIBCXXRT_INCLUDE_PATHS="<libcxxrt-source-dir>/src" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr <libc++-source-dir>
• make
• sudo make install

Unfortunately you can ' t simply run clang with "-stdlib=libc++" at this point, as clang are set up to link for libc++ linked To libsupc++. To get around this you'll have the to set up your linker yourself (or patch clang). For example,

• clang++ -stdlib=libc++ helloworld.cpp -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc

Alternately, could just add LIBCXXRT to your libraries list, which in most situations would give the same result:

• clang++ -stdlib=libc++ helloworld.cpp -lcxxrt

Using a local ABI library

Note:this is not recommended in almost all cases.
Generally these instructions should only being used when you can ' t install your ABI library.

Normally must link libc++ against a ABI shared library that the linker can find. If you want to build and test libc++ against a ABI library not in the linker's path you need to set when -DLIBCXX_CXX_ABI_LIBRARY_PATH=/path/to/abi/lib Configurin G CMake.

A example build using Libc++abi would look like:

• CC=clang CXX=clang++ cmake -DLIBCXX_CXX_ABI=libc++abi -DLIBCXX_LIBCXXABI_INCLUDE_PATHS="/path/to/libcxxabi/include" -DLIBCXX_CXX_ABI_LIBRARY_PATH="/path/to/libcxxabi-build/lib" path/to/libcxx
• make

When testing libc++ LIT would automatically link against the proper ABI library.

Design Documents

• <atomic>
• <type_traits>
• Excellent notes by Marshall Clow
• Status of Debug mode

Libc++