lldb/docs/resources/caveats.rst

   1 Caveats
   2 =======
   3
   4 .. contents::
   5    :local:
   6
   7 .. _python_caveat:
   8
   9 Python
  10 ------
  11
  12 LLDB has a powerful scripting interface which is accessible through Python.
  13 Python is available either from within LLDB through a (interactive) script
  14 interpreter, or as a Python module which you can import from the Python
  15 interpreter.
  16
  17 To make this possible, LLDB links against the Python shared library. Linking
  18 against Python comes with some constraints to be aware of.
  19
  20 1.  It is not possible to build and link LLDB against a Python 3 library and
  21     use it from Python 2 and vice versa.
  22
  23 2.  It is not possible to build and link LLDB against one distribution on
  24     Python and use it through an interpreter coming from another distribution.
  25     For example, on macOS, if you build and link against Python from
  26     python.org, you cannot import the lldb module from the Python interpreter
  27     installed with Homebrew.
  28
  29 3.  To use third party Python packages from inside LLDB, you need to install
  30     them using a utility (such as ``pip``) from the same Python distribution as
  31     the one used to build and link LLDB.
  32
  33 The previous considerations are especially important during development, but
  34 apply to binary distributions of LLDB as well.
  35
  36 LLDB in Xcode on macOS
  37 ``````````````````````
  38
  39 Users of lldb in Xcode on macOS commonly run into these issues when they
  40 install Python, often unknowingly as a dependency pulled in by Homebrew or
  41 other package managers. The problem is the symlinks that get created in
  42 ``/usr/local/bin``, which comes before ``/usr/bin`` in your path. You can use
  43 ``which python3`` to check to what it resolves.
  44
  45 To be sure you use the Python that matches with the lldb in Xcode use ``xcrun``
  46 or use the absolute path to the shims in ``/usr/bin``.
  47
  48 ::
  49
  50    $ xcrun python3
  51    $ /usr/bin/python3
  52
  53 Similarly, to install packages and be able to use them from within lldb, you'll
  54 need to install them with the matching ``pip3``.
  55
  56 ::
  57
  58    $ xcrun pip3
  59    $ /usr/bin/pip3
  60
  61 The same is true for Python 2. Although Python 2 comes with the operating
  62 system rather than Xcode, you can still use ``xcrun`` to launch the system
  63 variant.
  64
  65 ::
  66
  67    $ xcrun python
  68    $ /usr/bin/python
  69
  70 Keep in mind that Python 2 is deprecated and no longer maintained. Future
  71 versions of macOS will not include Python 2.7.