lldb/bindings/python/python.swig

   1 /*
   2    lldb.swig
   3
   4    This is the input file for SWIG, to create the appropriate C++ wrappers and
   5    functions for various scripting languages, to enable them to call the
   6    liblldb Script Bridge functions.
   7 */
   8
   9 /* Define our module docstring. */
  10 %define DOCSTRING
  11 "The lldb module contains the public APIs for Python binding.
  12
  13 Some of the important classes are described here:
  14
  15 * :py:class:`SBTarget`: Represents the target program running under the debugger.
  16 * :py:class:`SBProcess`: Represents the process associated with the target program.
  17 * :py:class:`SBThread`: Represents a thread of execution. :py:class:`SBProcess` contains SBThreads.
  18 * :py:class:`SBFrame`: Represents one of the stack frames associated with a thread. :py:class:`SBThread`
  19   contains SBFrame(s).
  20 * :py:class:`SBSymbolContext`: A container that stores various debugger related info.
  21 * :py:class:`SBValue`: Represents the value of a variable, a register, or an expression.
  22 * :py:class:`SBModule`: Represents an executable image and its associated object and symbol
  23   files.  :py:class:`SBTarget` contains SBModule.
  24 * :py:class:`SBBreakpoint`: Represents a logical breakpoint and its associated settings.
  25   :py:class:`SBTarget` contains SBBreakpoints.
  26 * :py:class:`SBSymbol`: Represents the symbol possibly associated with a stack frame.
  27 * :py:class:`SBCompileUnit`: Represents a compilation unit, or compiled source file.
  28 * :py:class:`SBFunction`: Represents a generic function, which can be inlined or not.
  29 * :py:class:`SBBlock`: Represents a lexical block. :py:class:`SBFunction` contains SBBlocks.
  30 * :py:class:`SBLineEntry`: Specifies an association with a contiguous range of instructions
  31   and a source file location. :py:class:`SBCompileUnit` contains SBLineEntry.
  32
  33 The different enums in the `lldb` module are described in :doc:`python_api_enums`.
  34
  35 "
  36 %enddef
  37
  38 /*
  39 Since version 3.0.9, swig's logic for importing the native module has changed in
  40 a way that is incompatible with our usage of the python module as __init__.py
  41 (See swig bug #769).  Fortunately, since version 3.0.11, swig provides a way for
  42 us to override the module import logic to suit our needs. This does that.
  43
  44 Older swig versions will simply ignore this setting.
  45 */
  46 %define MODULEIMPORT
  47 "try:
  48     # Try an absolute import first.  If we're being loaded from lldb,
  49     # _lldb should be a built-in module.
  50     import $module
  51 except ImportError:
  52     # Relative import should work if we are being loaded by Python.
  53     from . import $module"
  54 %enddef
  55
  56 // The name of the module to be created.
  57 %module(docstring=DOCSTRING, moduleimport=MODULEIMPORT) lldb
  58
  59 // Parameter types will be used in the autodoc string.
  60 %feature("autodoc", "1");
  61
  62 %define ARRAYHELPER(type,name)
  63 %inline %{
  64 type *new_ ## name (int nitems) {
  65    return (type *) malloc(sizeof(type)*nitems);
  66 }
  67 void delete_ ## name(type *t) {
  68    free(t);
  69 }
  70 type name ## _get(type *t, int index) {
  71    return t[index];
  72 }
  73 void name ## _set(type *t, int index, type val) {
  74    t[index] = val;
  75 }
  76 %}
  77 %enddef
  78
  79 %pythoncode%{
  80 import uuid
  81 import re
  82 import os
  83 %}
  84
  85 // Include the version of swig that was used to generate this interface.
  86 %define EMBED_VERSION(VERSION)
  87 %pythoncode%{
  88 # SWIG_VERSION is written as a single hex number, but the components of it are
  89 # meant to be interpreted in decimal. So, 0x030012 is swig 3.0.12, and not
  90 # 3.0.18.
  91 def _to_int(hex):
  92     return hex // 0x10 % 0x10 * 10 + hex % 0x10
  93 swig_version = (_to_int(VERSION // 0x10000), _to_int(VERSION // 0x100), _to_int(VERSION))
  94 del _to_int
  95 %}
  96 %enddef
  97 EMBED_VERSION(SWIG_VERSION)
  98
  99 %pythoncode%{
 100 # ===================================
 101 # Iterator for lldb container objects
 102 # ===================================
 103 def lldb_iter(obj, getsize, getelem):
 104     """A generator adaptor to support iteration for lldb container objects."""
 105     size = getattr(obj, getsize)
 106     elem = getattr(obj, getelem)
 107     for i in range(size()):
 108         yield elem(i)
 109 %}
 110
 111 %include <std_string.i>
 112 %include "python-typemaps.swig"
 113 %include "macros.swig"
 114 %include "headers.swig"
 115
 116 %{
 117 #include "../source/Plugins/ScriptInterpreter/Python/PythonDataObjects.h"
 118 #include "../source/Plugins/ScriptInterpreter/Python/SWIGPythonBridge.h"
 119 #include "../bindings/python/python-swigsafecast.swig"
 120 using namespace lldb_private;
 121 using namespace lldb_private::python;
 122 using namespace lldb;
 123 %}
 124
 125 %include "interfaces.swig"
 126 %include "python-extensions.swig"
 127 %include "python-wrapper.swig"
 128
 129 %pythoncode%{
 130 debugger_unique_id = 0
 131 SBDebugger.Initialize()
 132 debugger = None
 133 target = None
 134 process = None
 135 thread = None
 136 frame = None
 137 %}