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:
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:
_______________________________________________
lldb-commits mailing list
lldb-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
