Skip to content

Commit af9d03a

Browse files
jroelofsjroelofs
committed
[libunwind] Add sphinx docs
https://reviews.llvm.org/D31375 llvm-svn: 298922
1 parent 1fe3054 commit af9d03a

File tree

6 files changed

+544
-0
lines changed

6 files changed

+544
-0
lines changed

Diff for: ‎libunwind/CMakeLists.txt

+5
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,7 @@ option(LIBUNWIND_ENABLE_STATIC "Build libunwind as a static library." ON)
122122
option(LIBUNWIND_ENABLE_CROSS_UNWINDING "Enable cross-platform unwinding support." OFF)
123123
option(LIBUNWIND_ENABLE_ARM_WMMX "Enable unwinding support for ARM WMMX registers." OFF)
124124
option(LIBUNWIND_ENABLE_THREADS "Build libunwind with threading support." ON)
125+
option(LIBUNWIND_INCLUDE_DOCS "Build the libunwind documentation." ${LLVM_INCLUDE_DOCS})
125126

126127
set(LIBUNWIND_TARGET_TRIPLE "" CACHE STRING "Target triple for cross compiling.")
127128
set(LIBUNWIND_GCC_TOOLCHAIN "" CACHE PATH "GCC toolchain for cross compiling.")
@@ -303,3 +304,7 @@ if (NOT LIBUNWIND_CXX_INCLUDE_PATHS STREQUAL "")
303304
endif()
304305

305306
add_subdirectory(src)
307+
308+
if (LIBUNWIND_INCLUDE_DOCS)
309+
add_subdirectory(docs)
310+
endif()

Diff for: ‎libunwind/docs/BuildingLibunwind.rst

+167
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
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:
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+
59+
It is sometimes beneficial to build outside of the LLVM tree. An out-of-tree
60+
build 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+
78+
CMake Options
79+
=============
80+
81+
Here are some of the CMake variables that are used often, along with a
82+
brief explanation and LLVM-specific notes. For full documentation, check the
83+
CMake 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+
100+
libunwind 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

Diff for: ‎libunwind/docs/CMakeLists.txt

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
include(FindSphinx)
2+
if (SPHINX_FOUND)
3+
include(AddSphinxTarget)
4+
if (${SPHINX_OUTPUT_HTML})
5+
add_sphinx_target(html libunwind)
6+
endif()
7+
endif()

Diff for: ‎libunwind/docs/README.txt

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
libunwind Documentation
2+
====================
3+
4+
The libunwind documentation is written using the Sphinx documentation generator. It is
5+
currently tested with Sphinx 1.1.3.
6+
7+
To build the documents into html configure libunwind with the following cmake options:
8+
9+
* -DLLVM_ENABLE_SPHINX=ON
10+
* -DLIBUNWIND_INCLUDE_DOCS=ON
11+
12+
After configuring libunwind with these options the make rule `docs-libunwind-html`
13+
should be available.

0 commit comments

Comments
 (0)