Add docs for libunwind

[jroelofs]

Summary

I'm still iffy about the build goop for this. I started mostly cargo-culting the stuff from libcxx, but couldn't get that to work. What's in the patch seems to work for the standalone build, but does not work for in tree builds (and I have no idea why).

Comments / corrections / feedback would be much appreciated.

[krytarowski]

docs/index.rst

51

NetBSD amd64 Clang, GCC confirmed

[compnerd]

What happens when you try building it in tree?

docs/index.rst

83

ITYM libunwind :)

[jroelofs]

In D31375#710891, @compnerd wrote:

What happens when you try building it in tree?

The docs-libunwind-html target is missing, and the docs don't get built.

docs/index.rst

83

doh

[EricWF]

This LGTM. We should also get a bot setup to build it.

[EricWF]

In D31375#710897, @jroelofs wrote:

In D31375#710891, @compnerd wrote:

What happens when you try building it in tree?

The docs-libunwind-html target is missing, and the docs don't get built.

Shouldn't that be what happens when libunwind is built "out-of-tree"/standalone, not the other way around?

[jroelofs]

In D31375#711839, @EricWF wrote:

In D31375#710897, @jroelofs wrote:

In D31375#710891, @compnerd wrote:

What happens when you try building it in tree?

The docs-libunwind-html target is missing, and the docs don't get built.

Shouldn't that be what happens when libunwind is built "out-of-tree"/standalone, not the other way around?

"is" != "ought". That's what /is/ happening, not necessarily what we want to happen.

[jroelofs]

In D31375#712152, @jroelofs wrote:

In D31375#711839, @EricWF wrote:

In D31375#710897, @jroelofs wrote:

In D31375#710891, @compnerd wrote:

What happens when you try building it in tree?

The docs-libunwind-html target is missing, and the docs don't get built.

Shouldn't that be what happens when libunwind is built "out-of-tree"/standalone, not the other way around?

"is" != "ought". That's what /is/ happening, not necessarily what we want to happen.

And FWIW, it looks like libcxx's docs behave the same way... So this might be a problem with the way the runtimes dir works.

[jroelofs]

r298922

[jroelofs]

Review for adding a builder in: D31422

CMakeLists.txt

 option(LIBUNWIND_ENABLE_CROSS_UNWINDING "Enable cross-platform unwinding support." OFF)
 option(LIBUNWIND_ENABLE_ARM_WMMX "Enable unwinding support for ARM WMMX registers." OFF)
 option(LIBUNWIND_ENABLE_THREADS "Build libunwind with threading support." ON)
+option(LIBUNWIND_INCLUDE_DOCS "Build the libunwind documentation." ${LLVM_INCLUDE_DOCS})
 
 set(LIBUNWIND_TARGET_TRIPLE "" CACHE STRING "Target triple for cross compiling.")
 set(LIBUNWIND_GCC_TOOLCHAIN "" CACHE PATH "GCC toolchain for cross compiling.")

 endif()
 
 add_subdirectory(src)
+
+if (LIBUNWIND_INCLUDE_DOCS)
+  add_subdirectory(docs)
+endif()

docs/BuildingLibunwind.rst

+.. _BuildingLibunwind:
+
+==================
+Building libunwind
+==================
+
+.. contents::
+  :local:
+
+.. _build instructions:
+
+Getting Started
+===============
+
+On Mac OS, the easiest way to get this library is to link with -lSystem.
+However if you want to build tip-of-trunk from here (getting the bleeding
+edge), read on.
+
+The basic steps needed to build libc++ are:
+
+#. Checkout LLVM:
+
+   * ``cd where-you-want-llvm-to-live``
+   * ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm``
+
+#. Checkout libunwind:
+
+   * ``cd where-you-want-llvm-to-live``
+   * ``cd llvm/runtimes``
+   * ``svn co http://llvm.org/svn/llvm-project/libunwind/trunk libunwind``
+
+#. Configure and build libunwind:
+
+   CMake is the only supported configuration system.
+
+   Clang is the preferred compiler when building and using libunwind.
+
+   * ``cd where you want to build llvm``
+   * ``mkdir build``
+   * ``cd build``
+   * ``cmake -G <generator> [options] <path to llvm sources>``
+
+   For more information about configuring libunwind see :ref:`CMake Options`.
+
+   * ``make unwind`` --- will build libunwind.
+   * ``make check-unwind`` --- will run the test suite.
+
+   Shared and static libraries for libunwind should now be present in llvm/build/lib.
+
+#. **Optional**: Install libunwind
+
+   If your system already provides an unwinder, it is important to be careful
+   not to replace it. Remember Use the CMake option ``CMAKE_INSTALL_PREFIX`` to
+   select a safe place to install libunwind.
+
+   * ``make install-unwind`` --- Will install the libraries and the headers
+
+
+It is sometimes beneficial to build outside of the LLVM tree. An out-of-tree
+build would look like this:
+
+.. code-block:: bash
+
+  $ cd where-you-want-libunwind-to-live
+  $ # Check out llvm, and libunwind
+  $ ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm``
+  $ ``svn co http://llvm.org/svn/llvm-project/libunwind/trunk libunwind``
+  $ cd where-you-want-to-build
+  $ mkdir build && cd build
+  $ export CC=clang CXX=clang++
+  $ cmake -DLLVM_PATH=path/to/llvm \
+          path/to/libunwind
+  $ make
+
+
+.. _CMake Options:
+
+CMake Options
+=============
+
+Here are some of the CMake variables that are used often, along with a
+brief explanation and LLVM-specific notes. For full documentation, check the
+CMake docs or execute ``cmake --help-variable VARIABLE_NAME``.
+
+**CMAKE_BUILD_TYPE**:STRING
+  Sets the build type for ``make`` based generators. Possible values are
+  Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio
+  the user sets the build type with the IDE settings.
+
+**CMAKE_INSTALL_PREFIX**:PATH
+  Path where LLVM will be installed if "make install" is invoked or the
+  "INSTALL" target is built.
+
+**CMAKE_CXX_COMPILER**:STRING
+  The C++ compiler to use when building and testing libunwind.
+
+
+.. _libunwind-specific options:
+
+libunwind specific options
+--------------------------
+
+.. option:: LIBUNWIND_BUILD_32_BITS:BOOL
+
+  **Default**: Same as LLVM_BUILD_32_BITS
+
+  Toggle whether libunwind should be built with -m32.
+
+.. option:: LIBUNWIND_ENABLE_ASSERTIONS:BOOL
+
+  **Default**: ``ON``
+
+  Toggle assertions independent of the build mode.
+
+.. option:: LIBUNWIND_ENABLE_PEDANTIC:BOOL
+
+  **Default**: ``ON``
+
+  Compile with -Wpedantic.
+
+.. option:: LIBUNWIND_ENABLE_WERROR:BOOL
+
+  **Default**: ``ON``
+
+  Compile with -Werror
+
+.. option:: LIBUNWIND_ENABLE_SHARED:BOOL
+
+  **Default**: ``ON``
+
+  Build libunwind as a shared library.
+
+.. option:: LIBUNWIND_ENABLE_STATIC:BOOL
+
+  **Default**: ``ON``
+
+  Build libunwind as a static archive.
+
+.. option:: LIBUNWIND_ENABLE_CROSS_UNWINDING:BOOL
+
+  **Default**: ``OFF``
+
+  Enable cross-platform unwinding support.
+
+.. option:: LIBUNWIND_ENABLE_ARM_WMMX:BOOL
+
+  **Default**: ``OFF``
+
+  Enable unwinding support for ARM WMMX registers.
+
+.. option:: LIBUNWIND_ENABLE_THREADS:BOOL
+
+  **Default**: ``ON``
+
+  Build libunwind with threading support.
+
+.. option:: LIBUNWIND_TARGET_TRIPLE:STRING
+
+  Target triple for cross compiling
+
+.. option:: LIBUNWIND_GCC_TOOLCHAIN:PATH
+
+  GCC toolchain for cross compiling
+
+.. option:: LIBUNWIND_SYSROOT
+
+  Sysroot for cross compiling

docs/CMakeLists.txt

+include(FindSphinx)
+if (SPHINX_FOUND)
+  include(AddSphinxTarget)
+  if (${SPHINX_OUTPUT_HTML})
+    add_sphinx_target(html libunwind)
+  endif()
+endif()

docs/README.txt

+libunwind Documentation
+====================
+
+The libunwind documentation is written using the Sphinx documentation generator. It is
+currently tested with Sphinx 1.1.3.
+
+To build the documents into html configure libunwind with the following cmake options:
+
+  * -DLLVM_ENABLE_SPHINX=ON
+  * -DLIBUNWIND_INCLUDE_DOCS=ON
+
+After configuring libunwind with these options the make rule `docs-libunwind-html`
+should be available.

docs/conf.py

+# -*- coding: utf-8 -*-
+#
+# libunwind documentation build configuration file.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.todo']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'libunwind'
+copyright = u'2011-2017, LLVM Project'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '5.0'
+# The full version, including alpha/beta/rc tags.
+release = '5.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%Y-%m-%d'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+show_authors = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'friendly'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'haiku'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'libunwinddoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('contents', 'libunwind.tex', u'libunwind Documentation',
+   u'LLVM project', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('contents', 'libunwind', u'libunwind Documentation',
+     [u'LLVM project'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('contents', 'libunwind', u'libunwind Documentation',
+   u'LLVM project', 'libunwind', 'LLVM Unwinder',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+
+# FIXME: Define intersphinx configration.
+intersphinx_mapping = {}
+
+
+# -- Options for extensions ----------------------------------------------------
+
+# Enable this if you want TODOs to show up in the generated documentation.
+todo_include_todos = True

docs/index.rst

+.. _index:
+
+=======================
+libunwind LLVM Unwinder
+=======================
+
+Overview
+========
+
+libunwind is an implementation of the interface defined by the HP libunwind
+project. It was contributed by Apple as a way to enable clang++ to port to
+platforms that do not have a system unwinder. It is intended to be a small and
+fast implementation of the ABI, leaving off some features of HP's libunwind
+that never materialized (e.g. remote unwinding).
+
+The unwinder has two levels of API. The high level APIs are the `_Unwind_*`
+functions which implement functionality required by `__cxa_*` exception
+funcionts. The low level APIs are the `unw_*` functions which are an interface
+defined by the old HP libunwind project.
+
+Getting Started with libunwind
+------------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   BuildingLibunwind
+
+Current Status
+--------------
+
+libunwind is a production-quality unwinder, with platform support for DWARF
+unwind info, SjLj, and ARM EHABI.
+
+The low level libunwind API was designed to work either in-process (aka local)
+or to operate on another process (aka remote), but only the local path has been
+implemented. Remote unwinding remains as future work.
+
+Platform and Compiler Support
+-----------------------------
+
+libunwind is known to work on the following platforms:
+
+============ ==================== ============ ========================
+OS           Arch                 Compilers    Unwind Info
+============ ==================== ============ ========================
+Mac OS X     i386, x86_64         Clang, GCC   DWARF CFI
+iOS          ARM                  Clang        SjLj
+Linux        i386, x86_64         Clang, GCC   DWARF CFI
+Linux        ARM                  Clang, GCC   EHABI
+Bare Metal   ARM                  Clang, GCC   EHABI
+============ ==================== ============ ========================
+
+The following minimum compiler versions are strongly recommended.
+
+* Clang 3.5 and above
+* GCC 4.7 and above.
+
+Anything older *may* work.
+
+Notes and Known Issues
+----------------------
+
+* TODO
+
+Getting Involved
+================
+
+First please review our `Developer's Policy <http://llvm.org/docs/DeveloperPolicy.html>`__
+and `Getting started with LLVM <http://llvm.org/docs/GettingStarted.html>`__.
+
+**Bug Reports**
+
+If you think you've found a bug in libunwind, please report it using
+the `LLVM Bugzilla`_. If you're not sure, you
+can post a message to the `cfe-dev mailing list`_ or on IRC.
+Please include "libunwind" in your subject.
+
+**Patches**
+
+If you want to contribute a patch to libc++, the best place for that is
+`Phabricator <http://llvm.org/docs/Phabricator.html>`_. Please include [libunwind] in the subject and
+add `cfe-commits` as a subscriber. Also make sure you are subscribed to the
+`cfe-commits mailing list <http://lists.llvm.org/mailman/listinfo/cfe-commits>`_.
+
+**Discussion and Questions**
+
+Send discussions and questions to the
+`cfe-dev mailing list <http://lists.llvm.org/mailman/listinfo/cfe-dev>`_.
+Please include [libunwind] in the subject.
+
+
+Quick Links
+===========
+* `LLVM Homepage <http://llvm.org/>`_
+* `LLVM Bugzilla <https://bugs.llvm.org/>`_
+* `cfe-commits Mailing List`_
+* `cfe-dev Mailing List`_
+* `Browse libunwind -- SVN <http://llvm.org/svn/llvm-project/libunwind/trunk/>`_
+* `Browse libunwind -- ViewVC <http://llvm.org/viewvc/llvm-project/libunwind/trunk/>`_