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

libc++ specific options¶

LIBCXX_INSTALL_LIBRARY:BOOL¶

Default: ON

Toggle the installation of the library portion of libc++.

LIBCXX_INSTALL_HEADERS:BOOL¶

Default: ON

Toggle the installation of the libc++ headers.

LIBCXX_ENABLE_ASSERTIONS:BOOL¶

Default: ON

Build libc++ with assertions enabled.

LIBCXX_BUILD_32_BITS:BOOL¶

Default: OFF

Build libc++ as a 32 bit library. Also see LLVM_BUILD_32_BITS.

LIBCXX_ENABLE_SHARED:BOOL¶

Default: ON

Build libc++ as a shared library. Either LIBCXX_ENABLE_SHARED or LIBCXX_ENABLE_STATIC has to be enabled.

LIBCXX_ENABLE_STATIC:BOOL¶

Default: ON

Build libc++ as a static library. Either LIBCXX_ENABLE_SHARED or LIBCXX_ENABLE_STATIC has to be enabled.

LIBCXX_LIBDIR_SUFFIX:STRING¶

Extra suffix to append to the directory where libraries are to be installed. This option overrides LLVM_LIBDIR_SUFFIX.

LIBCXX_INSTALL_PREFIX:STRING¶

Default: ""

Define libc++ destination prefix.

libc++experimental Specific Options¶

LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY:BOOL¶

Default: ON

Build and test libc++experimental.a.

LIBCXX_INSTALL_EXPERIMENTAL_LIBRARY:BOOL¶

Default: LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY AND LIBCXX_INSTALL_LIBRARY

Install libc++experimental.a alongside libc++.

LIBCXX_ENABLE_FILESYSTEM:BOOL¶

Default: ON

Build filesystem as a standalone library libc++fs.a.

LIBCXX_INSTALL_FILESYSTEM_LIBRARY:BOOL¶

Default: LIBCXX_ENABLE_FILESYSTEM AND LIBCXX_INSTALL_LIBRARY

Install libc++fs.a alongside libc++.

ABI Library Specific Options¶

LIBCXX_CXX_ABI:STRING¶

Values: none, libcxxabi, libcxxrt, libstdc++, libsupc++.

Select the ABI library to build libc++ against.

LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS¶

Provide additional search paths for the ABI library headers.

LIBCXX_CXX_ABI_LIBRARY_PATH:PATH¶

Provide the path to the ABI library that libc++ should link against.

LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL¶

Default: OFF

If this option is enabled, libc++ will try and link the selected ABI library statically.

LIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL¶

Default: ON by default on UNIX platforms other than Apple unless ‘LIBCXX_ENABLE_STATIC_ABI_LIBRARY’ is ON. Otherwise the default value is OFF.

This option generate and installs a linker script as libc++.so which links the correct ABI library.

LIBCXXABI_USE_LLVM_UNWINDER:BOOL¶

Default: OFF

Build and use the LLVM unwinder. Note: This option can only be used when libc++abi is the C++ ABI library used.

libc++ Feature Options¶

LIBCXX_ENABLE_EXCEPTIONS:BOOL¶

Default: ON

Build libc++ with exception support.

LIBCXX_ENABLE_RTTI:BOOL¶

Default: ON

Build libc++ with run time type information.

LIBCXX_INCLUDE_BENCHMARKS:BOOL¶

Default: ON

Build the libc++ benchmark tests and the Google Benchmark library needed to support them.

LIBCXX_BENCHMARK_NATIVE_STDLIB:STRING¶

Default:: ""

Values:: libc++, libstdc++

Build the libc++ benchmark tests and Google Benchmark library against the specified standard library on the platform. On linux this can be used to compare libc++ to libstdc++ by building the benchmark tests against both standard libraries.

LIBCXX_BENCHMARK_NATIVE_GCC_TOOLCHAIN:STRING¶

Use the specified GCC toolchain and standard library when building the native stdlib benchmark tests.

LIBCXX_HIDE_FROM_ABI_PER_TU_BY_DEFAULT:BOOL¶

Default: OFF

Pick the default for whether to constrain ABI-unstable symbols to each individual translation unit. This setting controls whether _LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT is defined by default – see the documentation of that macro for details.

libc++ ABI Feature Options¶

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

LIBCXX_ABI_VERSION:STRING¶

Default: 1

Defines the target ABI version of libc++.

LIBCXX_ABI_UNSTABLE:BOOL¶

Default: OFF

Build the “unstable” ABI version of libc++. Includes all ABI changing features on top of the current stable version.

LIBCXX_ABI_DEFINES:STRING¶

Default: ""

A semicolon-separated list of ABI macros to persist in the site config header. See include/__config for the list of ABI macros.

LLVM-specific options¶

LLVM_LIBDIR_SUFFIX:STRING¶

Extra suffix to append to the directory where libraries are to be installed. On a 64-bit architecture, one could use -DLLVM_LIBDIR_SUFFIX=64 to install libraries to /usr/lib64.

LLVM_BUILD_32_BITS:BOOL¶

Build 32-bits executables and libraries on 64-bits systems. This option is available only on some 64-bits unix systems. Defaults to OFF.

LLVM_LIT_ARGS:STRING¶

Arguments given to lit. make check and make clang-test are affected. By default, '-sv --no-progress-bar' on Visual C++ and Xcode, '-sv' on others.

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