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 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
  55 CMake Options
  56 =============
  57
  58 Here are some of the CMake variables that are used often, along with a
  59 brief explanation and LLVM-specific notes. For full documentation, check the
  60 CMake 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
  77 libunwind 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``.