[Docs] Add Python caveats under the development section

This adds a page named Caveats with a section on some of the things to
be aware of related to Python. It's a question we've seen more than once
pop up and I think it's good to have it documentation on the website.
Even though some of it might be useful to users, I still put it under
"development" because it requires some understanding of how LLDB is
built.

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

3 files changed, 43 insertions, 0 deletions

diff --git a/lldb/docs/index.rst b/lldb/docs/index.rst
index 1f7fe58a525..9164a05bdef 100644
--- a/lldb/docs/index.rst
+++ b/lldb/docs/index.rst
@@ -144,6 +144,7 @@ interesting areas to contribute to lldb.
    resources/test
    resources/bots
    resources/sbapi
+   resources/caveats
 
 .. toctree::
    :hidden:
diff --git a/lldb/docs/resources/build.rst b/lldb/docs/resources/build.rst
index dabd224feff..eecc32d708e 100644
--- a/lldb/docs/resources/build.rst
+++ b/lldb/docs/resources/build.rst
@@ -533,6 +533,11 @@ built correctly and is available to the default Python interpreter, run:
 
   > python -c 'import lldb'
 
+
+Make sure you're using the Python interpreter that matches the Python library
+you linked against. For more details please refer to the :ref:`caveats
+<python_caveat>`.
+
 .. _CodeSigning:
 
 Code Signing on macOS
diff --git a/lldb/docs/resources/caveats.rst b/lldb/docs/resources/caveats.rst
new file mode 100644
index 00000000000..780fb349051
--- /dev/null
+++ b/lldb/docs/resources/caveats.rst
@@ -0,0 +1,37 @@
+Caveats
+=======
+
+.. contents::
+   :local:
+
+.. _python_caveat:
+
+Python
+------
+
+LLDB has a powerful scripting interface which is accessible through Python.
+Python is available either from withing LLDB through a (interactive) script
+interpreter, or as a Python module which you can import from the Python
+interpreter.
+
+To make this possible, LLDB links against the Python shared library. Linking
+against Python comes with some constraints to be aware of.
+
+1.  It is not possible to build and link LLDB against a Python 3 library and
+    use it from Python 2 and vice versa.
+
+2.  It is not possible to build and link LLDB against one distribution on
+    Python and use it through a interpreter coming from another distribution.
+    For example, on macOS, if you build and link against Python from
+    python.org, you cannot import the lldb module from the Python interpreter
+    installed with Homebrew.
+
+3.  To use third party Python packages from inside LLDB, you need to install
+    them using a utility (such as ``pip``) from the same Python distribution as
+    the one used to build and link LLDB.
+
+The previous considerations are especially important during development, but
+apply to binary distributions of LLDB as well. For example, the LLDB that comes
+with Xcode links against the Python 3 that's part of Xcode. Therefore you
+should always use the Python in Xcode (through ``xcrun python3`` or
+``/usr/bin/python3``) to import the lldb module or install packages.