Author: Jonas Devlieghere Date: 2019-11-18T09:15:00-08:00 New Revision: 0aed648649775bfe29b01f7ad9b072f92df7c448
URL: https://github.com/llvm/llvm-project/commit/0aed648649775bfe29b01f7ad9b072f92df7c448 DIFF: https://github.com/llvm/llvm-project/commit/0aed648649775bfe29b01f7ad9b072f92df7c448.diff LOG: [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 Added: lldb/docs/resources/caveats.rst Modified: lldb/docs/index.rst lldb/docs/resources/build.rst Removed: ################################################################################ diff --git a/lldb/docs/index.rst b/lldb/docs/index.rst index 1f7fe58a525e..9164a05bdefd 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 dabd224feff5..eecc32d708e2 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 000000000000..780fb349051b --- /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. _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits