[Lldb-commits] [PATCH] D70252: [Docs] Add Python caveats under the development section

[Jonas Devlieghere via Phabricator via lldb-commits]

JDevlieghere created this revision.
JDevlieghere added reviewers: labath, aadsm, davide.
JDevlieghere added a project: LLDB.
Herald added subscribers: abidh, arphaman.

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.


Repository:
  rLLDB LLDB

https://reviews.llvm.org/D70252

Files:
  lldb/docs/index.rst
  lldb/docs/resources/caveats.rst


Index: lldb/docs/resources/caveats.rst
===================================================================
--- /dev/null
+++ lldb/docs/resources/caveats.rst
@@ -0,0 +1,34 @@
+Caveats
+=======
+
+.. contents::
+   :local:
+
+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 that's part of Xcode. You should always use
+the system's Python interpreter to import the lldb module or install packages.
Index: lldb/docs/index.rst
===================================================================
--- lldb/docs/index.rst
+++ lldb/docs/index.rst
@@ -144,6 +144,7 @@
    resources/test
    resources/bots
    resources/sbapi
+   resources/caveats
 
 .. toctree::
    :hidden:


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D70252.229339.patch
Type: text/x-patch
Size: 1876 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/lldb-commits/attachments/20191114/8070f932/attachment.bin>