libunwind/docs/BuildingLibunwind.rst

   1 .. _BuildingLibunwind:
   2
   3 ==================
   4 Building libunwind
   5 ==================
   6
   7 .. contents::
   8   :local:
   9
  10 .. _build instructions:
  11
  12 Getting Started
  13 ===============
  14
  15 On Mac OS, the easiest way to get this library is to link with -lSystem.
  16 However if you want to build tip-of-trunk from here (getting the bleeding
  17 edge), read on.
  18
  19 The 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_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 It is sometimes beneficial to build outside of the LLVM tree. An out-of-tree
  54 build 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 https://llvm.org/svn/llvm-project/llvm/trunk llvm``
  61   $ ``svn co https://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
  72 CMake Options
  73 =============
  74
  75 Here are some of the CMake variables that are used often, along with a
  76 brief explanation and LLVM-specific notes. For full documentation, check the
  77 CMake 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
  94 libunwind specific options
  95 --------------------------
  96
  97 .. option:: LIBUNWIND_ENABLE_ASSERTIONS:BOOL
  98
  99   **Default**: ``ON``
 100
 101   Toggle assertions independent of the build mode.
 102
 103 .. option:: LIBUNWIND_ENABLE_PEDANTIC:BOOL
 104
 105   **Default**: ``ON``
 106
 107   Compile with -Wpedantic.
 108
 109 .. option:: LIBUNWIND_ENABLE_WERROR:BOOL
 110
 111   **Default**: ``ON``
 112
 113   Compile with -Werror
 114
 115 .. option:: LIBUNWIND_ENABLE_SHARED:BOOL
 116
 117   **Default**: ``ON``
 118
 119   Build libunwind as a shared library.
 120
 121 .. option:: LIBUNWIND_ENABLE_STATIC:BOOL
 122
 123   **Default**: ``ON``
 124
 125   Build libunwind as a static archive.
 126
 127 .. option:: LIBUNWIND_ENABLE_CROSS_UNWINDING:BOOL
 128
 129   **Default**: ``OFF``
 130
 131   Enable cross-platform unwinding support.
 132
 133 .. option:: LIBUNWIND_ENABLE_ARM_WMMX:BOOL
 134
 135   **Default**: ``OFF``
 136
 137   Enable unwinding support for ARM WMMX registers.
 138
 139 .. option:: LIBUNWIND_ENABLE_THREADS:BOOL
 140
 141   **Default**: ``ON``
 142
 143   Build libunwind with threading support.
 144
 145 .. option:: LIBUNWIND_INSTALL_LIBRARY_DIR:PATH
 146
 147   **Default**: ``lib${LIBUNWIND_LIBDIR_SUFFIX}``
 148
 149   Path where built libunwind libraries should be installed. If a relative path,
 150   relative to ``CMAKE_INSTALL_PREFIX``.