1.. _BuildingLibunwind: 2 3================== 4Building libunwind 5================== 6 7.. contents:: 8 :local: 9 10.. _build instructions: 11 12Getting Started 13=============== 14 15On Mac OS, the easiest way to get this library is to link with -lSystem. 16However if you want to build tip-of-trunk from here (getting the bleeding 17edge), read on. 18 19The basic steps needed to build libc++ are: 20 21#. Checkout LLVM, libunwind, and related projects: 22 23 * ``cd where-you-want-llvm-to-live`` 24 * ``git clone https://github.com/llvm/llvm-project.git`` 25 26#. Configure and build libunwind: 27 28 CMake is the only supported configuration system. 29 30 Clang is the preferred compiler when building and using libunwind. 31 32 * ``cd where you want to build llvm`` 33 * ``mkdir build`` 34 * ``cd build`` 35 * ``cmake -G <generator> -DLLVM_ENABLE_PROJECTS=libunwind [options] <path to llvm sources>`` 36 37 For more information about configuring libunwind see :ref:`CMake Options`. 38 39 * ``make unwind`` --- will build libunwind. 40 * ``make check-unwind`` --- will run the test suite. 41 42 Shared and static libraries for libunwind should now be present in llvm/build/lib. 43 44#. **Optional**: Install libunwind 45 46 If your system already provides an unwinder, it is important to be careful 47 not to replace it. Remember Use the CMake option ``CMAKE_INSTALL_PREFIX`` to 48 select a safe place to install libunwind. 49 50 * ``make install-unwind`` --- Will install the libraries and the headers 51 52 53It is sometimes beneficial to build outside of the LLVM tree. An out-of-tree 54build would look like this: 55 56.. code-block:: bash 57 58 $ cd where-you-want-libunwind-to-live 59 $ # Check out llvm, and libunwind 60 $ ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm`` 61 $ ``svn co http://llvm.org/svn/llvm-project/libunwind/trunk libunwind`` 62 $ cd where-you-want-to-build 63 $ mkdir build && cd build 64 $ export CC=clang CXX=clang++ 65 $ cmake -DLLVM_PATH=path/to/llvm \ 66 path/to/libunwind 67 $ make 68 69 70.. _CMake Options: 71 72CMake Options 73============= 74 75Here are some of the CMake variables that are used often, along with a 76brief explanation and LLVM-specific notes. For full documentation, check the 77CMake docs or execute ``cmake --help-variable VARIABLE_NAME``. 78 79**CMAKE_BUILD_TYPE**:STRING 80 Sets the build type for ``make`` based generators. Possible values are 81 Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio 82 the user sets the build type with the IDE settings. 83 84**CMAKE_INSTALL_PREFIX**:PATH 85 Path where LLVM will be installed if "make install" is invoked or the 86 "INSTALL" target is built. 87 88**CMAKE_CXX_COMPILER**:STRING 89 The C++ compiler to use when building and testing libunwind. 90 91 92.. _libunwind-specific options: 93 94libunwind specific options 95-------------------------- 96 97.. option:: LIBUNWIND_BUILD_32_BITS:BOOL 98 99 **Default**: Same as LLVM_BUILD_32_BITS 100 101 Toggle whether libunwind should be built with -m32. 102 103.. option:: LIBUNWIND_ENABLE_ASSERTIONS:BOOL 104 105 **Default**: ``ON`` 106 107 Toggle assertions independent of the build mode. 108 109.. option:: LIBUNWIND_ENABLE_PEDANTIC:BOOL 110 111 **Default**: ``ON`` 112 113 Compile with -Wpedantic. 114 115.. option:: LIBUNWIND_ENABLE_WERROR:BOOL 116 117 **Default**: ``ON`` 118 119 Compile with -Werror 120 121.. option:: LIBUNWIND_ENABLE_SHARED:BOOL 122 123 **Default**: ``ON`` 124 125 Build libunwind as a shared library. 126 127.. option:: LIBUNWIND_ENABLE_STATIC:BOOL 128 129 **Default**: ``ON`` 130 131 Build libunwind as a static archive. 132 133.. option:: LIBUNWIND_ENABLE_CROSS_UNWINDING:BOOL 134 135 **Default**: ``OFF`` 136 137 Enable cross-platform unwinding support. 138 139.. option:: LIBUNWIND_ENABLE_ARM_WMMX:BOOL 140 141 **Default**: ``OFF`` 142 143 Enable unwinding support for ARM WMMX registers. 144 145.. option:: LIBUNWIND_ENABLE_THREADS:BOOL 146 147 **Default**: ``ON`` 148 149 Build libunwind with threading support. 150 151.. option:: LIBUNWIND_TARGET_TRIPLE:STRING 152 153 Target triple for cross compiling 154 155.. option:: LIBUNWIND_GCC_TOOLCHAIN:PATH 156 157 GCC toolchain for cross compiling 158 159.. option:: LIBUNWIND_SYSROOT 160 161 Sysroot for cross compiling 162