| .. _BuildingLibcxx: |
| |
| =============== |
| Building libc++ |
| =============== |
| |
| .. contents:: |
| :local: |
| |
| .. _build instructions: |
| |
| 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++. |
| |
| .. warning:: |
| * Replacing your systems libc++ installation could render the system non-functional. |
| * macOS will not boot without a valid copy of ``libc++.1.dylib`` in ``/usr/lib``. |
| |
| .. code-block:: bash |
| |
| $ 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 |
| <https://llvm.org/docs/GettingStarted.html>`_ 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: |
| |
| .. code-block:: bash |
| |
| $ 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 |
| |
| |
| Support for Windows |
| ------------------- |
| |
| libcxx supports being built with clang-cl, but not with MSVC's cl.exe, as |
| cl doesn't support the ``#include_next`` extension. Furthermore, VS 2017 or |
| newer (19.14) is required. |
| |
| libcxx also supports being built with clang targeting MinGW environments. |
| |
| CMake + Visual Studio |
| ~~~~~~~~~~~~~~~~~~~~~ |
| |
| Building with Visual Studio currently does not permit running tests. However, |
| it is the simplest way to build. |
| |
| .. code-block:: batch |
| |
| > cmake -G "Visual Studio 16 2019" ^ |
| -T "ClangCL" ^ |
| -DLIBCXX_ENABLE_SHARED=YES ^ |
| -DLIBCXX_ENABLE_STATIC=NO ^ |
| -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO ^ |
| \path\to\libcxx |
| > cmake --build . |
| |
| CMake + ninja (MSVC) |
| ~~~~~~~~~~~~~~~~~~~~ |
| |
| Building with ninja is required for development to enable tests. |
| Running the tests also requires a Bash shell and Python to be available. |
| |
| If Git for Windows is available, that can be used to provide the bash |
| shell by adding the right bin directory to the path, e.g. |
| ``set PATH=%PATH%;C:\Program Files\Git\usr\bin``. |
| |
| Alternatively, one can also choose to run the whole build in a MSYS2 |
| shell. That can be set up e.g. by starting a Visual Studio Tools Command |
| Prompt (for getting the environment variables pointing to the headers and |
| import libraries), and making sure that clang-cl is available in the |
| path. From there, launch an MSYS2 shell via e.g. |
| ``C:\msys64\msys2_shell.cmd -full-path -mingw64`` (preserving the earlier |
| environment, allowing the MSVC headers/libraries and clang-cl to be found). |
| |
| In either case, then run: |
| |
| .. code-block:: batch |
| |
| > cmake -G Ninja ^ |
| -DCMAKE_BUILD_TYPE=Release ^ |
| -DCMAKE_C_COMPILER=clang-cl ^ |
| -DCMAKE_CXX_COMPILER=clang-cl ^ |
| -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO ^ |
| path/to/libcxx |
| > ninja cxx |
| > ninja check-cxx |
| |
| If you are running in an MSYS2 shell and you have installed the |
| MSYS2-provided clang package (which defaults to a non-MSVC target), you |
| should add e.g. ``-DLIBCXX_TARGET_TRIPLE=x86_64-windows-msvc`` (replacing |
| ``x86_64`` with the architecture you're targeting) to the ``cmake`` command |
| line above. This will instruct ``check-cxx`` to use the right target triple |
| when invoking ``clang++``. |
| |
| Also note that if not building in Release mode, a failed assert in the tests |
| pops up a blocking dialog box, making it hard to run a larger number of tests. |
| |
| CMake + ninja (MinGW) |
| ~~~~~~~~~~~~~~~~~~~~~ |
| |
| libcxx can also be built in MinGW environments, e.g. with the MinGW |
| compilers in MSYS2. This requires clang to be available (installed with |
| e.g. the ``mingw-w64-x86_64-clang`` package), together with CMake and ninja. |
| |
| .. code-block:: bash |
| |
| > cmake -G Ninja \ |
| -DCMAKE_C_COMPILER=clang \ |
| -DCMAKE_CXX_COMPILER=clang++ \ |
| -DLIBCXX_HAS_WIN32_THREAD_API=ON \ |
| -DLIBCXX_CXX_ABI=libstdc++ \ |
| -DLIBCXX_TARGET_INFO="libcxx.test.target_info.MingwLocalTI" \ |
| path/to/libcxx |
| > ninja cxx |
| > cp /mingw64/bin/{libstdc++-6,libgcc_s_seh-1,libwinpthread-1}.dll lib |
| > ninja check-cxx |
| |
| As this build configuration ends up depending on a couple other DLLs that |
| aren't available in path while running tests, copy them into the same |
| directory as the tested libc++ DLL. |
| |
| (Building a libc++ that depends on libstdc++ isn't necessarily a config one |
| would want to deploy, but it simplifies the config for testing purposes.) |
| |
| .. _`libc++abi`: http://libcxxabi.llvm.org/ |
| |
| |
| .. _CMake Options: |
| |
| 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++. |
| |
| |
| .. _libcxx-specific options: |
| |
| libc++ specific options |
| ----------------------- |
| |
| .. option:: LIBCXX_INSTALL_LIBRARY:BOOL |
| |
| **Default**: ``ON`` |
| |
| Toggle the installation of the library portion of libc++. |
| |
| .. option:: LIBCXX_INSTALL_HEADERS:BOOL |
| |
| **Default**: ``ON`` |
| |
| Toggle the installation of the libc++ headers. |
| |
| .. option:: LIBCXX_ENABLE_ASSERTIONS:BOOL |
| |
| **Default**: ``OFF`` |
| |
| Build libc++ with assertions enabled. |
| |
| .. option:: LIBCXX_BUILD_32_BITS:BOOL |
| |
| **Default**: ``OFF`` |
| |
| Build libc++ as a 32 bit library. Also see `LLVM_BUILD_32_BITS`. |
| |
| .. option:: LIBCXX_ENABLE_SHARED:BOOL |
| |
| **Default**: ``ON`` |
| |
| Build libc++ as a shared library. Either `LIBCXX_ENABLE_SHARED` or |
| `LIBCXX_ENABLE_STATIC` has to be enabled. |
| |
| .. option:: LIBCXX_ENABLE_STATIC:BOOL |
| |
| **Default**: ``ON`` |
| |
| Build libc++ as a static library. Either `LIBCXX_ENABLE_SHARED` or |
| `LIBCXX_ENABLE_STATIC` has to be enabled. |
| |
| .. option:: LIBCXX_LIBDIR_SUFFIX:STRING |
| |
| Extra suffix to append to the directory where libraries are to be installed. |
| This option overrides `LLVM_LIBDIR_SUFFIX`. |
| |
| .. option:: LIBCXX_HERMETIC_STATIC_LIBRARY:BOOL |
| |
| **Default**: ``OFF`` |
| |
| Do not export any symbols from the static libc++ library. |
| This is useful when the static libc++ library is being linked into shared |
| libraries that may be used in with other shared libraries that use different |
| C++ library. We want to avoid exporting any libc++ symbols in that case. |
| |
| .. option:: LIBCXX_ENABLE_FILESYSTEM:BOOL |
| |
| **Default**: ``ON`` except on Windows. |
| |
| This option can be used to enable or disable the filesystem components on |
| platforms that may not support them. For example on Windows. |
| |
| .. _libc++experimental options: |
| |
| libc++experimental Specific Options |
| ------------------------------------ |
| |
| .. option:: LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY:BOOL |
| |
| **Default**: ``ON`` |
| |
| Build and test libc++experimental.a. |
| |
| .. option:: LIBCXX_INSTALL_EXPERIMENTAL_LIBRARY:BOOL |
| |
| **Default**: ``LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY AND LIBCXX_INSTALL_LIBRARY`` |
| |
| Install libc++experimental.a alongside libc++. |
| |
| |
| .. _ABI Library Specific Options: |
| |
| ABI Library Specific Options |
| ---------------------------- |
| |
| .. option:: LIBCXX_CXX_ABI:STRING |
| |
| **Values**: ``none``, ``libcxxabi``, ``libcxxrt``, ``libstdc++``, ``libsupc++``. |
| |
| Select the ABI library to build libc++ against. |
| |
| .. option:: LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS |
| |
| Provide additional search paths for the ABI library headers. |
| |
| .. option:: LIBCXX_CXX_ABI_LIBRARY_PATH:PATH |
| |
| Provide the path to the ABI library that libc++ should link against. |
| |
| .. option:: LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL |
| |
| **Default**: ``OFF`` |
| |
| If this option is enabled, libc++ will try and link the selected ABI library |
| statically. |
| |
| .. option:: 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. |
| |
| .. option:: 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 |
| ---------------------- |
| |
| .. option:: LIBCXX_ENABLE_EXCEPTIONS:BOOL |
| |
| **Default**: ``ON`` |
| |
| Build libc++ with exception support. |
| |
| .. option:: LIBCXX_ENABLE_RTTI:BOOL |
| |
| **Default**: ``ON`` |
| |
| Build libc++ with run time type information. |
| |
| .. option:: LIBCXX_INCLUDE_TESTS:BOOL |
| |
| **Default**: ``ON`` (or value of ``LLVM_INCLUDE_TESTS``) |
| |
| Build the libc++ tests. |
| |
| .. option:: LIBCXX_INCLUDE_BENCHMARKS:BOOL |
| |
| **Default**: ``ON`` |
| |
| Build the libc++ benchmark tests and the Google Benchmark library needed |
| to support them. |
| |
| .. option:: LIBCXX_BENCHMARK_TEST_ARGS:STRING |
| |
| **Default**: ``--benchmark_min_time=0.01`` |
| |
| A semicolon list of arguments to pass when running the libc++ benchmarks using the |
| ``check-cxx-benchmarks`` rule. By default we run the benchmarks for a very short amount of time, |
| since the primary use of ``check-cxx-benchmarks`` is to get test and sanitizer coverage, not to |
| get accurate measurements. |
| |
| .. option:: 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. |
| |
| .. option:: LIBCXX_BENCHMARK_NATIVE_GCC_TOOLCHAIN:STRING |
| |
| Use the specified GCC toolchain and standard library when building the native |
| stdlib benchmark tests. |
| |
| .. option:: 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. |
| |
| .. option:: LIBCXX_ABI_VERSION:STRING |
| |
| **Default**: ``1`` |
| |
| Defines the target ABI version of libc++. |
| |
| .. option:: 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. |
| |
| .. option:: LIBCXX_ABI_NAMESPACE:STRING |
| |
| **Default**: ``__n`` where ``n`` is the current ABI version. |
| |
| This option defines the name of the inline ABI versioning namespace. It can be used for building |
| custom versions of libc++ with unique symbol names in order to prevent conflicts or ODR issues |
| with other libc++ versions. |
| |
| .. warning:: |
| When providing a custom namespace, it's the users responsibility to ensure the name won't cause |
| conflicts with other names defined by libc++, both now and in the future. In particular, inline |
| namespaces of the form ``__[0-9]+`` are strictly reserved by libc++ and may not be used by users. |
| Doing otherwise could cause conflicts and hinder libc++ ABI evolution. |
| |
| .. option:: 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 variables: |
| |
| LLVM-specific options |
| --------------------- |
| |
| .. option:: 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``. |
| |
| .. option:: 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. |
| |
| .. option:: 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 Alternate ABI libraries |
| ============================= |
| |
| |
| .. _libsupcxx: |
| |
| 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 |
| |
| .. code-block:: bash |
| |
| $ 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: |
| |
| .. code-block:: bash |
| |
| $ 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. |
| |
| .. code-block:: bash |
| |
| $ make cxx |
| $ make install |
| |
| You can now run clang with -stdlib=libc++. |
| |
| |
| .. _libcxxrt_ref: |
| |
| 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: |
| |
| .. code-block:: bash |
| |
| $ 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, |
| |
| .. code-block:: bash |
| |
| $ 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: |
| |
| .. code-block:: bash |
| |
| $ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt |
| |
| .. _`libcxxrt`: https://github.com/pathscale/libcxxrt/ |
| |
| |
| Using a local ABI library installation |
| --------------------------------------- |
| |
| .. warning:: |
| This is not recommended in almost all cases. |
| |
| 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: |
| |
| .. code-block:: bash |
| |
| $ 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. |
