Building libc++

Getting Started

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.

The following instructions describe how to checkout, build, test and (optionally) install libc++ and libc++abi.

If your system already provides a libc++ installation it is important to be careful not to replace it. Remember Use the CMake option CMAKE_INSTALL_PREFIX to select a safe place to install libc++.

$ git clone https://github.com/llvm/llvm-project.git
$ cd llvm-project
$ mkdir build && cd build
$ cmake -DCMAKE_C_COMPILER=clang \
        -DCMAKE_CXX_COMPILER=clang++ \
        -DLLVM_ENABLE_PROJECTS="libcxx;libcxxabi" \
        ../llvm
$ make # Build
$ make check-cxx # Test
$ make install-cxx install-cxxabi # Install

For more information about configuring libc++ see :ref:`CMake Options`. You may also want to read the LLVM getting started documentation.

Shared libraries for libc++ and libc++ abi should now be present in build/lib. See :ref:`using an alternate libc++ installation <alternate libcxx>` for information on how to use this libc++.

The instructions are for building libc++ on FreeBSD, Linux, or Mac using libc++abi as the C++ ABI library. On Linux, it is also possible to use :ref:`libsupc++ <libsupcxx>` or libcxxrt.

It is possible to build libc++ standalone (i.e. without building other LLVM projects). A standalone build would look like this:

$ git clone https://github.com/llvm/llvm-project.git llvm-project
$ cd llvm-project
$ mkdir build && cd build
$ cmake -DCMAKE_C_COMPILER=clang \
        -DCMAKE_CXX_COMPILER=clang++ \
        -DLIBCXX_CXX_ABI=libcxxabi \
        -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/separate/libcxxabi/include \
        ../libcxx
$ make
$ make check-cxx # optional

Experimental Support for Windows

The Windows support requires building with clang-cl as cl does not support one required extension: #include_next. Furthermore, VS 2015 or newer (19.00) is required. In the case of clang-cl, we need to specify the "MS Compatibility Version" as it defaults to 2014 (18.00).

CMake + Visual Studio

Building with Visual Studio currently does not permit running tests. However, it is the simplest way to build.

> cmake -G "Visual Studio 14 2015"              ^
        -T "LLVM-vs2014"                        ^
        -DLIBCXX_ENABLE_SHARED=YES              ^
        -DLIBCXX_ENABLE_STATIC=NO               ^
        -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO ^
        \path\to\libcxx
> cmake --build .

CMake + ninja

Building with ninja is required for development to enable tests. Unfortunately, doing so requires additional configuration as we cannot just specify a toolset.

> cmake -G Ninja                                                                    ^
        -DCMAKE_MAKE_PROGRAM=/path/to/ninja                                         ^
        -DCMAKE_SYSTEM_NAME=Windows                                                 ^
        -DCMAKE_C_COMPILER=clang-cl                                                 ^
        -DCMAKE_C_FLAGS="-fms-compatibility-version=19.00 --target=i686--windows"   ^
        -DCMAKE_CXX_COMPILER=clang-cl                                                ^
        -DCMAKE_CXX_FLAGS="-fms-compatibility-version=19.00 --target=i686--windows" ^
        -DLLVM_PATH=/path/to/llvm/tree                                              ^
        -DLIBCXX_ENABLE_SHARED=YES                                                  ^
        -DLIBCXX_ENABLE_STATIC=NO                                                   ^
        -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO                                     ^
        \path\to\libcxx
> /path/to/ninja cxx
> /path/to/ninja check-cxx

Note that the paths specified with backward slashes must use the \ as the directory separator as clang-cl may otherwise parse the path as an argument.

CMake Options

Here are some of the CMake variables that are used often, along with a brief explanation and LLVM-specific notes. For full documentation, check the CMake docs or execute cmake --help-variable VARIABLE_NAME.

CMAKE_BUILD_TYPE:STRING

Sets the build type for make based generators. Possible values are Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio the user sets the build type with the IDE settings.

CMAKE_INSTALL_PREFIX:PATH

Path where LLVM will be installed if "make install" is invoked or the "INSTALL" target is built.

CMAKE_CXX_COMPILER:STRING

The C++ compiler to use when building and testing libc++.

libc++ specific options

libc++experimental Specific Options

ABI Library Specific Options

libc++ Feature Options

libc++ ABI Feature Options

The following options allow building libc++ for a different ABI version.

LLVM-specific options

Using Alternate ABI libraries

Using libsupc++ on Linux

You will need libstdc++ in order to provide libsupc++.

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

You can also figure this out by running

$ 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.

Note that the first two entries happen to be what we are looking for. This may not be correct on other platforms.

We can now run CMake:

$ 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>

You can also substitute -DLIBCXX_CXX_ABI=libsupc++ 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.

$ make cxx
$ make install

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

Using libcxxrt on Linux

You will need to keep the source tree of libcxxrt available on your build machine and your copy of the libcxxrt shared library must be placed where your linker will find it.

We can now run CMake like:

$ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \
        -DLIBCXX_CXX_ABI=libcxxrt \
        -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src \
              -DCMAKE_BUILD_TYPE=Release \
              -DCMAKE_INSTALL_PREFIX=/usr \
              <libc++-source-directory>
$ make cxx
$ make install

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,

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

Alternately, you could just add libcxxrt to your libraries list, which in most situations will give the same result:

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

Using a local ABI library installation

These instructions should only be used when you can't install your ABI library.

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 -DLIBCXX_CXX_ABI_LIBRARY_PATH=/path/to/abi/lib when configuring CMake.

An example build using libc++abi would look like:

$ 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
$ make

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