Add LLDB website and documentation in reStructuredText for Sphinx

The current LLDB website is written in HTML which is hard to maintain.
We have quite a bit of HTML code checked in which can make it hard to
differentiate between documentation written by us and documentation
generated by a tool.

In line with the other LLVM projects, I propose generating the
documentation with Sphix. I think text/rst files provide a lower barrier
for new or casual contributors to fix or update.

This patch adds a copy of the LLDB website and documentation in
reStructuredText. It also adds a new ninja target `docs-lldb-html` when
-DLLVM_ENABLE_SPHINX:BOOL is enabled.

This is the first step in having the website and documentation being
generated from the repository, rather than having the output checked-in
under the www folder. During the hopefully short transition period,
please also update the reStructuredText files when modifying the
website.

Differential revision: https://reviews.llvm.org/D55376

llvm-svn: 352644

5 files changed, 788 insertions, 0 deletions

diff --git a/lldb/docs/resources/build.rst b/lldb/docs/resources/build.rst
new file mode 100644
index 00000000000..5628a32abe5
--- /dev/null
+++ b/lldb/docs/resources/build.rst
@@ -0,0 +1,516 @@
+Build
+=====
+
+.. contents::
+   :local:
+
+Building LLDB on Windows
+------------------------
+
+**Required Dependencies**
+
+* Visual Studio 2015 or greater
+* Windows SDK 8.0 or higher. In general it is best to use the latest available version.
+* `Python 3.5 or higher <https://www.python.org/downloads/windows/>`_ or
+  higher. Earlier versions of Python can be made to work by compiling your own
+  distribution from source, but this workflow is unsupported and you are own
+  your own.
+* `Ninja build tool <https://ninja-build.org/>`_ (strongly recommended)
+* `GnuWin32 <http://gnuwin32.sourceforge.net/>`_
+* `SWIG for Windows <http://www.swig.org/download.html>`_ (version 3+)
+
+
+**Optional Dependencies**
+
+* `Python Tools for Visual Studio
+  <https://github.com/Microsoft/PTVS/releases>`_. If you plan to debug test
+  failures or even write new tests at all, PTVS is an indispensable debugging
+  extension to VS that enables full editing and debugging support for Python
+  (including mixed native/managed debugging)
+
+**Preliminaries**
+
+This section describes how to set up your system and install the required
+dependencies such that they can be found when needed during the build process.
+The steps outlined here only need to be performed once.
+
+#. Install Visual Studio and the Windows SDK.
+#. Install GnuWin32, making sure ``<GnuWin32 install dir>\bin`` is added to
+   your PATH environment variable.
+#. Install SWIG for Windows, making sure ``<SWIG install dir>`` is added to
+   your PATH environment variable.
+
+**Building LLDB**
+
+Any command prompt from which you build LLDB should have a valid Visual Studio
+environment setup. This means you should run ``vcvarsall.bat`` or open an
+appropriate Visual Studio Command Prompt corresponding to the version you wish
+to use.
+
+
+Finally, when you are ready to build LLDB, generate CMake with the following
+command line:
+
+::
+
+  cmake -G Ninja <cmake variables> <path to root of llvm src tree>
+
+
+and run ``ninja`` to build LLDB. Information about running the LLDB test suite
+can be found on the test page.
+
+
+Following is a description of some of the most important CMake variables which
+you are likely to encounter. A variable FOO is set by adding ``-DFOO=value`` to
+the CMake command line.
+
+* ``LLDB_TEST_DEBUG_TEST_CRASHES`` (Default=0): If set to 1, will cause Windows
+  to generate a crash dialog whenever lldb.exe or the python extension module
+  crashes while running the test suite. If set to 0, LLDB will silently crash.
+  Setting to 1 allows a developer to attach a JIT debugger at the time of a
+  crash, rather than having to reproduce a failure or use a crash dump.
+* ``PYTHON_HOME`` (Required): Path to the folder where the Python distribution
+  is installed. For example, ``C:\Python35``.
+* ``LLDB_RELOCATABLE_PYTHON`` (Default=0): When this is 0, LLDB will bind
+  statically to the location specified in the ``PYTHON_HOME`` CMake variable,
+  ignoring any value of ``PYTHONHOME`` set in the environment. This is most
+  useful for developers who simply want to run LLDB after they build it. If you
+  wish to move a build of LLDB to a different machine where Python will be in a
+  different location, setting ``LLDB_RELOCATABLE_PYTHON`` to 1 will cause
+  Python to use its default mechanism for finding the python installation at
+  runtime (looking for installed Pythons, or using the ``PYTHONHOME``
+  environment variable if it is specified).
+* ``LLDB_TEST_C_COMPILER`` or ``LLDB_TEST_CXX_COMPILER``: The test suite needs
+  to be able to find a copy of clang.exe that it can use to compile inferior
+  programs. Note that MSVC is not supported here, it must be a path to a clang
+  executable. Note that using a release clang.exe is strongly recommended here,
+  as it will make the test suite run much faster. This can be a path to any
+  recent clang.exe, including one you built yourself. These variables are
+  ignored unless the respective ``LLDB_TEST_USE_CUSTOM_C_COMPILER`` and
+  ``LLDB_TEST_USE_CUSTOM_CXX_COMPILER`` are set to ON.
+
+Sample command line:
+
+::
+
+  cmake -G Ninja -DLLDB_TEST_DEBUG_TEST_CRASHES=1 -DPYTHON_HOME=C:\Python35 -DLLDB_TEST_USE_CUSTOM_C_COMPILER=ON -DLLDB_TEST_C_COMPILER=d:\src\llvmbuild\ninja_release\bin\clang.exe ..\..\llvm
+
+
+**Working with both Ninja and MSVC**
+
+Compiling with ninja is both faster and simpler than compiling with MSVC, but
+chances are you still want to debug LLDB with MSVC (at least until we can debug
+LLDB on Windows with LLDB!). One solution to this is to run cmake twice and
+generate the output into two different folders. One for compiling (the ninja
+folder), and one for editing / browsing / debugging (the MSVC folder).
+
+To do this, simply run ``cmake -G Ninja <arguments>`` from one folder, and
+``cmake -G "Visual Studio 14 2015" <arguments>`` in another folder. Then you
+can open the .sln file in Visual Studio, set lldb as the startup project, and
+use F5 to run it. You need only edit the project settings to set the executable
+and the working directory to point to binaries inside of the ninja tree.
+
+Building LLDB on macOS
+----------------------
+
+There are two ways to build LLDB on Mac OS X: Using Xcode and using CMake
+
+**Preliminaries**
+
+* Xcode 4.3 or newer requires the "Command Line Tools" component (XCode->Preferences->Downloads->Components).
+* Mac OS X Lion or newer requires installing `Swig <http://swig.org/>`_.
+
+**Building LLDB with Xcode**
+
+Building on Mac OS X with Xcode is as easy as downloading the code and building
+the Xcode project or workspace:
+
+* Download the lldb sources.
+* Follow the code signing instructions in ``lldb/docs/code-signing.txt``.
+* In Xcode 3.x: ``lldb/lldb.xcodeproj``, select the lldb-tool target, and build.
+* In Xcode 4.x: ``lldb/lldb.xcworkspace``, select the lldb-tool scheme, and build.
+
+**Building LLDB with CMake**
+
+First download the LLVM, Clang, libc++ and LLDB sources. Refer to this page for
+precise instructions on this step.
+
+Refer to the code signing instructions in ``lldb/docs/code-signing.txt`` for
+info on codesigning debugserver during the build.
+
+Using CMake is documented on the `Building LLVM with CMake
+<http://llvm.org/docs/CMake.html>`_ page. Ninja is the recommended generator to
+use when building LLDB with CMake.
+
+::
+
+  > cmake $PATH_TO_LLVM -G Ninja
+  > ninja lldb
+
+As noted in the "Building LLVM with CMake" page mentioned above, you can pass
+variables to cmake to change build behavior. If LLDB is built as a part of
+LLVM, then you can pass LLVM-specific CMake variables to cmake when building
+LLDB.
+
+
+Here are some commonly used LLDB-specific CMake variables:
+
+* ``LLDB_EXPORT_ALL_SYMBOLS:BOOL`` : Exports all symbols. Useful in conjunction
+  with CMAKE_BUILD_TYPE=Debug.
+* ``LLDB_BUILD_FRAMEWORK:BOOL`` : Builds LLDB.framework as Xcode would
+* ``LLDB_CODESIGN_IDENTITY:STRING`` : Determines the codesign identity to use.
+  An empty string means skip building debugserver to avoid codesigning.
+
+Building LLDB on Linux, FreeBSD and NetBSD
+------------------------------------------
+
+This document describes the steps needed to compile LLDB on most Linux systems,
+FreeBSD and NetBSD.
+
+**Preliminaries**
+
+LLDB relies on many of the technologies developed by the larger LLVM project.
+In particular, it requires both Clang and LLVM itself in order to build. Due to
+this tight integration the Getting Started guides for both of these projects
+come as prerequisite reading:
+
+* `LLVM <http://llvm.org/docs/GettingStarted.html>`_
+* `Clang <http://clang.llvm.org/get_started.html>`_
+
+Supported compilers for building LLDB on Linux include:
+
+* Clang 3.2
+* GCC 4.6.2 (later versions should work as well)
+
+It is recommended to use libstdc++ 4.6 (or higher) to build LLDB on Linux, but
+using libc++ is also known to work.
+
+On FreeBSD the base system Clang and libc++ may be used to build LLDB, or the
+GCC port or package.
+
+On NetBSD the base system GCC and libstdc++ are used to build LLDB, Clang/LLVM
+and libc++ should also work.
+
+In addition to any dependencies required by LLVM and Clang, LLDB needs a few
+development packages that may also need to be installed depending on your
+system. The current list of dependencies are:
+
+* `Swig <http://swig.org/>`_
+* `libedit (Linux only) <http://www.thrysoee.dk/editline>`_
+* `Python <http://www.python.org/>`_
+
+
+So for example, on a Fedora system one might run:
+
+::
+
+  > yum install libedit-devel libxml2-devel ncurses-devel python-devel swig
+
+On a Debian or Ubuntu system one might run:
+
+::
+
+  > sudo apt-get install build-essential subversion swig python2.7-dev libedit-dev libncurses5-dev
+
+or
+
+::
+
+  > sudo apt-get build-dep lldb-3.3 # or lldb-3.4
+
+
+On FreeBSD one might run:
+
+::
+
+  > pkg install swig python
+
+On NetBSD one might run:
+
+::
+
+  > pkgin install swig python27 cmake ninja-build
+
+
+If you wish to build the optional reference documentation, additional dependencies are required:
+
+* Graphviz (for the 'dot' tool).
+* doxygen (only if you wish to build the C++ API reference)
+* epydoc (only if you wish to build the Python API reference)
+
+
+To install the prerequisites for building the documentation (on Debian/Ubuntu) do:
+
+::
+
+  > sudo apt-get install doxygen graphviz
+  > sudo pip install epydoc # or install package python-epydoc
+
+
+**Building LLDB**
+
+We first need to checkout the source trees into the appropriate locations. Both
+Clang and LLDB build as subprojects of LLVM. This means we will be checking out
+the source for both Clang and LLDB into the tools subdirectory of LLVM. We will
+be setting up a directory hierarchy looking something like this:
+
+::
+
+                  llvm
+                  |
+                  `-- tools
+                      |
+                      +-- clang
+                      |
+                      `-- lldb
+
+For reference, we will call the root of the LLVM project tree $llvm, and the
+roots of the Clang and LLDB source trees $clang and $lldb respectively.
+
+Change to the directory where you want to do development work and checkout
+LLVM:
+
+::
+
+  > svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm
+
+
+Now switch to LLVM’s tools subdirectory and checkout both Clang and LLDB:
+
+::
+
+  > cd $llvm/tools
+  > svn co http://llvm.org/svn/llvm-project/cfe/trunk clang
+  > svn co http://llvm.org/svn/llvm-project/lldb/trunk lldb
+
+In general, building the LLDB trunk revision requires trunk revisions of both
+LLVM and Clang.
+
+It is highly recommended that you build the system out of tree. Create a second
+build directory and configure the LLVM project tree to your specifications as
+outlined in LLVM’s Getting Started Guide. A typical build procedure might be:
+
+::
+
+  > cd $llvm/..
+  > mkdir build
+  > cd build
+
+**To build with CMake**
+
+
+Using CMake is documented on the `Building LLVM with CMake
+<http://llvm.org/docs/CMake.html>`_ page. Building LLDB is possible using one
+of the following generators:
+
+* Ninja
+* Unix Makefiles
+
+**Using CMake + Ninja**
+
+Ninja is the fastest way to build LLDB! In order to use ninja, you need to have
+recent versions of CMake and ninja on your system. To build using ninja:
+
+::
+
+  > cmake ../llvm -G Ninja
+  > ninja lldb
+  > ninja check-lldb
+
+
+If you want to debug the lldb that you're building -- that is, build it with
+debug info enabled -- pass two additional arguments to cmake before running
+ninja:
+
+::
+
+  > cmake ../llvm -G Ninja -DLLDB_EXPORT_ALL_SYMBOLS=1 -DCMAKE_BUILD_TYPE=Debug
+
+
+**Using CMake + Unix Makefiles**
+
+If you do not have Ninja, you can still use CMake to generate Unix Makefiles that build LLDB:
+
+::
+
+  > cmake ..
+  > make
+  > make check-lldb
+
+
+**Building API reference documentation**
+
+LLDB exposes a C++ as well as a Python API. To build the reference
+documentation for these two APIs, ensure you have the required dependencies
+installed, and build the ``lldb-python-doc`` and ``lldb-cpp-doc`` CMake
+targets.
+
+The output HTML reference documentation can be found in
+``<build-dir>/tools/lldb/docs/``.
+
+**Additional Notes**
+
+LLDB has a Python scripting capability and supplies its own Python module named
+lldb. If a script is run inside the command line lldb application, the Python
+module is made available automatically. However, if a script is to be run by a
+Python interpreter outside the command line application, the ``PYTHONPATH``
+environment variable can be used to let the Python interpreter find the lldb
+module.
+
+Current stable NetBSD release doesn't ship with libpanel(3), therefore it's
+required to disable curses(3) support with the
+``-DLLDB_DISABLE_CURSES:BOOL=TRUE`` option. To make sure check if
+``/usr/include/panel.h`` exists in your system.
+
+The correct path can be obtained by invoking the command line lldb tool with
+the -P flag:
+
+::
+
+  > export PYTHONPATH=`$llvm/build/Debug+Asserts/bin/lldb -P`
+
+If you used a different build directory or made a release build, you may need
+to adjust the above to suit your needs. To test that the lldb Python module is
+built correctly and is available to the default Python interpreter, run:
+
+::
+
+  > python -c 'import lldb'
+
+**Cross-compiling LLDB**
+
+
+In order to debug remote targets running different architectures than your
+host, you will need to compile LLDB (or at least the server component) for the
+target. While the easiest solution is to just compile it locally on the target,
+this is often not feasible, and in these cases you will need to cross-compile
+LLDB on your host.
+
+Cross-compilation is often a daunting task and has a lot of quirks which depend
+on the exact host and target architectures, so it is not possible to give a
+universal guide which will work on all platforms. However, here we try to
+provide an overview of the cross-compilation process along with the main things
+you should look out for.
+
+First, you will need a working toolchain which is capable of producing binaries
+for the target architecture. Since you already have a checkout of clang and
+lldb, you can compile a host version of clang in a separate folder and use
+that. Alternatively you can use system clang or even cross-gcc if your
+distribution provides such packages (e.g., ``g++-aarch64-linux-gnu`` on
+Ubuntu).
+
+Next, you will need a copy of the required target headers and libraries on your
+host. The libraries can be usually obtained by copying from the target machine,
+however the headers are often not found there, especially in case of embedded
+platforms. In this case, you will need to obtain them from another source,
+either a cross-package if one is available, or cross-compiling the respective
+library from source. Fortunately the list of LLDB dependencies is not big and
+if you are only interested in the server component, you can reduce this even
+further by passing the appropriate cmake options, such as:
+
+::
+
+  -DLLDB_DISABLE_LIBEDIT=1
+  -DLLDB_DISABLE_CURSES=1
+  -DLLDB_DISABLE_PYTHON=1
+  -DLLVM_ENABLE_TERMINFO=0
+
+In this case you, will often not need anything other than the standard C and
+C++ libraries.
+
+Once all of the dependencies are in place, it's just a matter of configuring
+the build system with the locations and arguments of all the necessary tools.
+The most important cmake options here are:
+
+* ``CMAKE_CROSSCOMPILING`` : Set to 1 to enable cross-compilation.
+* ``CMAKE_LIBRARY_ARCHITECTURE`` : Affects the cmake search path when looking
+  for libraries. You may need to set this to your architecture triple if you do
+  not specify all your include and library paths explicitly.
+* ``CMAKE_C_COMPILER``, ``CMAKE_CXX_COMPILER`` : C and C++ compilers for the
+  target architecture
+* ``CMAKE_C_FLAGS``, ``CMAKE_CXX_FLAGS`` : The flags for the C and C++ target
+  compilers. You may need to specify the exact target cpu and abi besides the
+  include paths for the target headers.
+* ``CMAKE_EXE_LINKER_FLAGS`` : The flags to be passed to the linker. Usually
+  just a list of library search paths referencing the target libraries.
+* ``LLVM_TABLEGEN``, ``CLANG_TABLEGEN`` : Paths to llvm-tblgen and clang-tblgen
+  for the host architecture. If you already have built clang for the host, you
+  can point these variables to the executables in your build directory. If not,
+  you will need to build the llvm-tblgen and clang-tblgen host targets at
+  least.
+* ``LLVM_HOST_TRIPLE`` : The triple of the system that lldb (or lldb-server)
+  will run on. Not setting this (or setting it incorrectly) can cause a lot of
+  issues with remote debugging as a lot of the choices lldb makes depend on the
+  triple reported by the remote platform.
+
+You can of course also specify the usual cmake options like
+``CMAKE_BUILD_TYPE``, etc.
+
+**Example 1: Cross-compiling for linux arm64 on Ubuntu host**
+
+Ubuntu already provides the packages necessary to cross-compile LLDB for arm64.
+It is sufficient to install packages ``gcc-aarch64-linux-gnu``,
+``g++-aarch64-linux-gnu``, ``binutils-aarch64-linux-gnu``. Then it is possible
+to prepare the cmake build with the following parameters:
+
+::
+
+  -DCMAKE_CROSSCOMPILING=1 \
+  -DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \
+  -DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++ \
+  -DLLVM_HOST_TRIPLE=aarch64-unknown-linux-gnu \
+  -DLLVM_TABLEGEN=<path-to-host>/bin/llvm-tblgen \
+  -DCLANG_TABLEGEN=<path-to-host>/bin/clang-tblgen \
+  -DLLDB_DISABLE_PYTHON=1 \
+  -DLLDB_DISABLE_LIBEDIT=1 \
+  -DLLDB_DISABLE_CURSES=1
+
+An alternative (and recommended) way to compile LLDB is with clang.
+Unfortunately, clang is not able to find all the include paths necessary for a
+successful cross-compile, so we need to help it with a couple of CFLAGS
+options. In my case it was sufficient to add the following arguments to
+``CMAKE_C_FLAGS`` and ``CMAKE_CXX_FLAGS`` (in addition to changing
+``CMAKE_C(XX)_COMPILER`` to point to clang compilers):
+
+::
+
+  -target aarch64-linux-gnu \
+  -I /usr/aarch64-linux-gnu/include/c++/4.8.2/aarch64-linux-gnu \
+  -I /usr/aarch64-linux-gnu/include
+
+If you wanted to build a full version of LLDB and avoid passing
+``-DLLDB_DISABLE_PYTHON`` and other options, you would need to obtain the
+target versions of the respective libraries. The easiest way to achieve this is
+to use the qemu-debootstrap utility, which can prepare a system image using
+qemu and chroot to simulate the target environment. Then you can install the
+necessary packages in this environment (python-dev, libedit-dev, etc.) and
+point your compiler to use them using the correct -I and -L arguments.
+
+**Example 2: Cross-compiling for Android on Linux**
+
+In the case of Android, the toolchain and all required headers and libraries
+are available in the Android NDK.
+
+The NDK also contains a cmake toolchain file, which makes configuring the build
+much simpler. The compiler, include and library paths will be configured by the
+toolchain file and all you need to do is to select the architecture
+(ANDROID_ABI) and platform level (``ANDROID_PLATFORM``, should be at least 21).
+You will also need to set ``ANDROID_ALLOW_UNDEFINED_SYMBOLS=On``, as the
+toolchain file defaults to "no undefined symbols in shared libraries", which is
+not compatible with some llvm libraries. The first version of NDK which
+supports this approach is r14.
+
+For example, the following arguments are sufficient to configure an android
+arm64 build:
+
+::
+
+  -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \
+  -DANDROID_ABI=arm64-v8a \
+  -DANDROID_PLATFORM=android-21 \
+  -DANDROID_ALLOW_UNDEFINED_SYMBOLS=On \
+  -DLLVM_HOST_TRIPLE=aarch64-unknown-linux-android \
+  -DCROSS_TOOLCHAIN_FLAGS_NATIVE='-DCMAKE_C_COMPILER=cc;-DCMAKE_CXX_COMPILER=c++'
+
+Note that currently only lldb-server is functional on android. The lldb client
+is not supported and unlikely to work.
diff --git a/lldb/docs/resources/download.rst b/lldb/docs/resources/download.rst
new file mode 100644
index 00000000000..37fcb35f06f
--- /dev/null
+++ b/lldb/docs/resources/download.rst
@@ -0,0 +1,34 @@
+Download
+========
+
+Nightly Builds
+--------------
+
+Nightly builds of LLDB are packaged and tested from trunk:
+
+Debian and Ubuntu: llvm.org/apt
+
+The pkgsrc framework offers a package with recent LLDB in the wip repository:
+
+::
+
+  cd pkgsrc/wip/lldb-git
+  make install clean
+
+Releases
+--------
+
+Debian packages are available for LLDB 3.5 and later.
+
+* `Jessie - LLDB 3.5 <https://packages.debian.org/jessie/lldb>`_
+* `Stretch - LLDB 3.8 <https://packages.debian.org/stretch/lldb>`_
+* `Buster - LLDB 6.0 <https://packages.debian.org/buster/lldb>`_
+* `Sid - LLDB 6.0 <https://packages.debian.org/sid/lldb>`_
+
+Ubuntu packages are available for LLDB 3.8 and later.
+
+* `Ubuntu 16.04LTS - LLDB 3.8 <https://packages.ubuntu.com/xenial/lldb>`_
+* `Ubuntu 18.04LTS - LLDB 6.0 <https://packages.ubuntu.com/bionic/lldb>`_
+
+Arch Linux packages the latest `LLDB 6.0
+<https://www.archlinux.org/packages/extra/x86_64/lldb/>`_.
diff --git a/lldb/docs/resources/external.rst b/lldb/docs/resources/external.rst
new file mode 100644
index 00000000000..ab7e54c6d73
--- /dev/null
+++ b/lldb/docs/resources/external.rst
@@ -0,0 +1,19 @@
+External Resources
+==================
+
+Documentation
+-------------
+
+* `Python API Documentation <https://lldb.llvm.org/python_reference/index.html>`_
+* `C++ API Documentation <https://lldb.llvm.org/cpp_reference/html/index.html>`_
+
+Bugs
+----
+
+* `Bug Reports <https://bugs.llvm.org/>`_
+
+Source
+------
+
+* `Browse SVN <http://llvm.org/viewvc/llvm-project/lldb/trunk/>`_
+* `Browse ViewVNC <http://llvm.org/viewvc/llvm-project/lldb/trunk/>`_
diff --git a/lldb/docs/resources/sbapi.rst b/lldb/docs/resources/sbapi.rst
new file mode 100644
index 00000000000..20c332990c1
--- /dev/null
+++ b/lldb/docs/resources/sbapi.rst
@@ -0,0 +1,55 @@
+The SB API Coding Rules
+=======================
+
+The SB APIs constitute the stable C++ API that lldb presents to external
+clients, and which get processed by SWIG to produce the Python bindings to
+lldb. As such it is important that they not suffer from the binary
+incompatibilities that C++ is so susceptible to. We've established a few rules
+to ensure that this happens.
+
+The classes in the SB API's are all called SB<SomeName>, where SomeName is in
+CamelCase starting with an upper case letter. The method names are all
+CamelCase with initial capital letter as well.
+
+All the SB API classes are non-virtual, single inheritance classes. They should
+only include SBDefines.h or other SB headers as needed. There should be no
+inlined method implementations in the header files, they should all be in the
+implementation files. And there should be no direct ivar access.
+
+You also need to choose the ivars for the class with care, since you can't add
+or remove ivars without breaking binary compatibility. In some cases, the SB
+class is a thin wrapper around an internal lldb_private object. In that case,
+the class can have a single ivar, which is either a pointer, shared_ptr or
+unique_ptr to the object in the lldb_private API. All the lldb_private classes
+that get used this way are declared as opaque classes in lldb_forward.h, which
+is included in SBDefines.h. So if you need an SB class to wrap an lldb_private
+class that isn't in lldb_forward.h, add it there rather than making a direct
+opaque declaration in the SB classes .h file.
+
+If the SB Class needs some state of its own, as well as the backing object,
+don't include that as a direct ivar in the SB Class. Instead, make an Impl
+class in the SB's .cpp file, and then make the SB object hold a shared or
+unique pointer to the Impl object. The theory behind this is that if you need
+more state in the SB object, those needs are likely to change over time, and
+this way the Impl class can pick up members without changing the size of the
+object. An example of this is the SBValue class. Please note that you should
+not put this Impl class in the lldb namespace. Failure to do so leads to
+leakage of weak-linked symbols in the SBAPI.
+
+In order to fit into the Python API's, we need to be able to default construct
+all the SB objects. Since the ivars of the classes are all pointers of one sort
+or other, this can easily be done, but it means all the methods must be
+prepared to handle their opaque implementation pointer being empty, and doing
+something reasonable. We also always have an "IsValid" method on all the SB
+classes to report whether the object is empty or not.
+
+Another piece of the SB API infrastructure is the Python (or other script
+interpreter) customization. SWIG allows you to add property access, iterators
+and documentation to classes, but to do that you have to use a Swig interface
+file in place of the .h file. Those files have a different format than a
+straight C++ header file. These files are called SB<ClassName>.i, and live in
+"scripts/interface". They are constructed by starting with the associated .h
+file, and adding documentation and the Python decorations, etc. We do this in a
+decidedly low-tech way, by maintaining the two files in parallel. That
+simplifies the build process, but it does mean that if you add a method to the
+C++ API's for an SB class, you have to copy the interface to the .i file.
diff --git a/lldb/docs/resources/test.rst b/lldb/docs/resources/test.rst
new file mode 100644
index 00000000000..67cebd71759
--- /dev/null
+++ b/lldb/docs/resources/test.rst
@@ -0,0 +1,164 @@
+Testing LLDB
+============
+
+The LLDB test suite consists of Python scripts located under the test
+directory. Each script contains a number of test cases and is usually
+accompanied by a C (C++, ObjC, etc.) source file. Each test first compiles the
+source file and then uses LLDB to debug the resulting executable. The tests
+verify both the LLDB command line interface and the scripting API.
+
+.. contents::
+   :local:
+
+Running the Full Test Suite
+---------------------------
+
+**Windows Note**: In the examples that follow, any invocations of python should
+be replaced with python_d, the debug interpreter, when running the test suite
+against a debug version of LLDB.
+
+The easiest way to run the LLDB test suite is to use the ``check-lldb`` build
+target. By default, the ``check-lldb`` target builds the test programs with the
+same compiler that was used to build LLDB. To build the tests with a different
+compiler, you can set the ``LLDB_TEST_C_COMPILER`` or the ``LLDB_TEST_CXX_COMPILER``
+CMake variables. These variables are ignored unless the respective
+``LLDB_TEST_USE_CUSTOM_C_COMPILER`` and ``LLDB_TEST_USE_CUSTOM_CXX_COMPILER`` are set
+to ``ON``.
+
+It is possible to customize the architecture of the test binaries and compiler
+used by appending ``-A`` and ``-C`` options respectively to the CMake variable
+``LLDB_TEST_USER_ARGS``. For example, to test LLDB against 32-bit binaries
+built with a custom version of clang, do:
+
+::
+
+   > cmake -DLLDB_TEST_USER_ARGS="-A i386 -C /path/to/custom/clang" -G Ninja
+   > ninja check-lldb
+
+Note that multiple ``-A`` and ``-C`` flags can be specified to
+``LLDB_TEST_USER_ARGS``.
+
+Note that on NetBSD you must export ``LD_LIBRARY_PATH=$PWD/lib`` in your
+environment. This is due to lack of the ``$ORIGIN`` linker feature.
+
+Running a Specific Test or Set of Tests
+---------------------------------------
+
+In addition to running all the LLDB test suites with the "check-lldb" CMake target above, it is possible to run individual LLDB tests. For example, to run the test cases defined in TestInferiorCrashing.py, run:
+
+::
+
+   > cd $lldb/test
+   > python dotest.py --executable <path-to-lldb> -p TestInferiorCrashing.py ../packages/Python/lldbsuite/test
+
+If the test is not specified by name (e.g. if you leave the -p argument off), LLDB will run all tests in that directory:
+
+::
+
+   > python dotest.py --executable <path-to-lldb> functionalities/data-formatter
+
+Many more options that are available. To see a list of all of them, run:
+
+::
+
+   > python dotest.py -h
+
+The ``dotest.py`` script runs tests in parallel by default. To disable the parallel
+test running feature, use the ``--no-multiprocess`` flag. The number of concurrent
+tests is controlled by the ``LLDB_TEST_THREADS`` environment variable or the
+``--threads command`` line parameter. The default value is the number of CPU cores
+on your system.
+
+The parallel test running feature will handle an additional ``--test-subdir
+SUBDIR`` arg. When specified, ``SUBDIR`` is relative to the root test directory
+and will limit all parallel test running to that subdirectory's tree of tests.
+
+The parallel test runner will run all tests within a given directory serially,
+but will run multiple directories concurrently. Thus, as a test writer, we
+provide serialized test run semantics within a directory. Note child
+directories are considered entirely separate, so two child directories could be
+running in parallel with a parent directory.
+
+Running the Test Suite Remotely
+-------------------------------
+
+Running the test-suite remotely is similar to the process of running a local
+test suite, but there are two things to have in mind:
+
+1. You must have the lldb-server running on the remote system, ready to accept
+   multiple connections. For more information on how to setup remote debugging
+   see the Remote debugging page.
+2. You must tell the test-suite how to connect to the remote system. This is
+   achieved using the ``--platform-name``, ``--platform-url`` and
+   ``--platform-working-dir`` parameters to ``dotest.py``. These parameters
+   correspond to the platform select and platform connect LLDB commands. You
+   will usually also need to specify the compiler and architecture for the
+   remote system.
+
+Currently, running the remote test suite is supported only with ``dotest.py`` (or
+dosep.py with a single thread), but we expect this issue to be addressed in the
+near future.
+
+Debugging Test Failures
+-----------------------
+
+On non-Windows platforms, you can use the ``-d`` option to ``dotest.py`` which
+will cause the script to wait for a while until a debugger is attached.
+
+Debugging Test Failures on Windows
+----------------------------------
+
+On Windows, it is strongly recommended to use Python Tools for Visual Studio
+for debugging test failures. It can seamlessly step between native and managed
+code, which is very helpful when you need to step through the test itself, and
+then into the LLDB code that backs the operations the test is performing.
+
+A quick guide to getting started with PTVS is as follows:
+
+#. Install PTVS
+#. Create a Visual Studio Project for the Python code.
+    #. Go to File -> New -> Project -> Python -> From Existing Python Code.
+    #. Choose llvm/tools/lldb as the directory containing the Python code.
+    #. When asked where to save the .pyproj file, choose the folder ``llvm/tools/lldb/pyproj``. This is a special folder that is ignored by the ``.gitignore`` file, since it is not checked in.
+#. Set test/dotest.py as the startup file
+#. Make sure there is a Python Environment installed for your distribution. For example, if you installed Python to ``C:\Python35``, PTVS needs to know that this is the interpreter you want to use for running the test suite.
+    #. Go to Tools -> Options -> Python Tools -> Environment Options
+    #. Click Add Environment, and enter Python 3.5 Debug for the name. Fill out the values correctly.
+#. Configure the project to use this debug interpreter.
+    #. Right click the Project node in Solution Explorer.
+    #. In the General tab, Make sure Python 3.5 Debug is the selected Interpreter.
+    #. In Debug/Search Paths, enter the path to your ninja/lib/site-packages directory.
+    #. In Debug/Environment Variables, enter ``VCINSTALLDIR=C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\``.
+    #. If you want to enabled mixed mode debugging, check Enable native code debugging (this slows down debugging, so enable it only on an as-needed basis.)
+#. Set the command line for the test suite to run.
+    #. Right click the project in solution explorer and choose the Debug tab.
+    #. Enter the arguments to dotest.py. Note you must add --no-multiprocess
+    #. Example command options:
+
+::
+
+   # quiet mode
+   -q
+   --arch=i686
+   # Path to debug lldb.exe
+   --executable D:/src/llvmbuild/ninja/bin/lldb.exe
+   # Directory to store log files
+   -s D:/src/llvmbuild/ninja/lldb-test-traces
+   -u CXXFLAGS -u CFLAGS
+   # If a test crashes, show JIT debugging dialog.
+   --enable-crash-dialog
+   # Path to release clang.exe
+   -C d:\src\llvmbuild\ninja_release\bin\clang.exe
+   # Path to the particular test you want to debug.
+   -p TestPaths.py
+   # Root of test tree
+   D:\src\llvm\tools\lldb\packages\Python\lldbsuite\test
+   # Required in order to be able to debug the test.
+   --no-multiprocess
+
+::
+
+   -q --arch=i686 --executable D:/src/llvmbuild/ninja/bin/lldb.exe -s D:/src/llvmbuild/ninja/lldb-test-traces -u CXXFLAGS -u CFLAGS --enable-crash-dialog -C d:\src\llvmbuild\ninja_release\bin\clang.exe -p TestPaths.py D:\src\llvm\tools\lldb\packages\Python\lldbsuite\test --no-multiprocess
+
+
+