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 libunwind 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_RUNTIMES=libunwind [options] <llvm-monorepo>/runtimes`` 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 53.. _CMake Options: 54 55CMake Options 56============= 57 58Here are some of the CMake variables that are used often, along with a 59brief explanation and LLVM-specific notes. For full documentation, check the 60CMake docs or execute ``cmake --help-variable VARIABLE_NAME``. 61 62**CMAKE_BUILD_TYPE**:STRING 63 Sets the build type for ``make`` based generators. Possible values are 64 Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio 65 the user sets the build type with the IDE settings. 66 67**CMAKE_INSTALL_PREFIX**:PATH 68 Path where LLVM will be installed if "make install" is invoked or the 69 "INSTALL" target is built. 70 71**CMAKE_CXX_COMPILER**:STRING 72 The C++ compiler to use when building and testing libunwind. 73 74 75.. _libunwind-specific options: 76 77libunwind specific options 78-------------------------- 79 80.. option:: LIBUNWIND_ENABLE_ASSERTIONS:BOOL 81 82 **Default**: ``ON`` 83 84 Toggle assertions independent of the build mode. 85 86.. option:: LIBUNWIND_ENABLE_PEDANTIC:BOOL 87 88 **Default**: ``ON`` 89 90 Compile with -Wpedantic. 91 92.. option:: LIBUNWIND_ENABLE_WERROR:BOOL 93 94 **Default**: ``ON`` 95 96 Compile with -Werror 97 98.. option:: LIBUNWIND_ENABLE_SHARED:BOOL 99 100 **Default**: ``ON`` 101 102 Build libunwind as a shared library. 103 104.. option:: LIBUNWIND_ENABLE_STATIC:BOOL 105 106 **Default**: ``ON`` 107 108 Build libunwind as a static archive. 109 110.. option:: LIBUNWIND_ENABLE_CROSS_UNWINDING:BOOL 111 112 **Default**: ``OFF`` 113 114 Enable cross-platform unwinding support. 115 116.. option:: LIBUNWIND_ENABLE_ARM_WMMX:BOOL 117 118 **Default**: ``OFF`` 119 120 Enable unwinding support for ARM WMMX registers. 121 122.. option:: LIBUNWIND_ENABLE_THREADS:BOOL 123 124 **Default**: ``ON`` 125 126 Build libunwind with threading support. 127 128.. option:: LIBUNWIND_INSTALL_LIBRARY_DIR:PATH 129 130 **Default**: ``lib${LIBUNWIND_LIBDIR_SUFFIX}`` 131 132 Path where built libunwind libraries should be installed. If a relative path, 133 relative to ``CMAKE_INSTALL_PREFIX``. 134