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 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
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