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