diff --git a/lldb/docs/conf.py b/lldb/docs/conf.py --- a/lldb/docs/conf.py +++ b/lldb/docs/conf.py @@ -29,12 +29,16 @@ sys.path.insert(0, os.path.abspath(".")) # Add the build directory that contains the `lldb` module. LLDB_SWIG_MODULE is # set by CMake. - sys.path.insert(0, os.getenv("LLDB_SWIG_MODULE")) + if os.getenv("LLDB_SWIG_MODULE") is not None: + sys.path.insert(0, os.getenv("LLDB_SWIG_MODULE")) # Put the generated Python API documentation in the 'python_api' folder. This # also defines the URL these files will have in the generated website. automodapi_toctreedirnm = 'python_api' +# Disable sphinx-tabs tab closing feature. +sphinx_tabs_disable_tab_closing = True + # -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. @@ -42,7 +46,7 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx'] +extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx', 'sphinx_tabs.tabs'] # Unless we only generate the basic manpage we need the plugin for generating # the Python API documentation. @@ -58,19 +62,19 @@ } try: - import recommonmark + import recommonmark except ImportError: - # manpages do not use any .md sources - if not building_man_page: - raise + # manpages do not use any .md sources + if not building_man_page: + raise else: - import sphinx - if sphinx.version_info >= (3, 0): - # This requires 0.5 or later. - extensions.append('recommonmark') - else: - source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'} - source_suffix['.md'] = 'markdown' + import sphinx + if sphinx.version_info >= (3, 0): + # This requires 0.5 or later. + extensions.append('recommonmark') + else: + source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'} + source_suffix['.md'] = 'markdown' # The encoding of source files. #source_encoding = 'utf-8-sig' @@ -173,11 +177,9 @@ # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] -html_context = { - 'css_files': [ - '_static/lldb.css' - ], - } +# Add any extra stylesheets and scripts here. +html_css_files = ['lldb.css'] +html_js_files = [] html_extra_path = ['.htaccess'] @@ -245,8 +247,8 @@ # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'LLDB.tex', u'LLDB Documentation', - u'The LLDB Team', 'manual'), + ('index', 'LLDB.tex', u'LLDB Documentation', + u'The LLDB Team', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -301,9 +303,9 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'LLDB', u'LLDB Documentation', - u'The LLDB Team', 'LLDB', 'One line description of project.', - 'Miscellaneous'), + ('index', 'LLDB', u'LLDB Documentation', + u'The LLDB Team', 'LLDB', 'One line description of project.', + 'Miscellaneous'), ] # Documents to append as an appendix to all manuals. diff --git a/lldb/docs/index.rst b/lldb/docs/index.rst --- a/lldb/docs/index.rst +++ b/lldb/docs/index.rst @@ -134,8 +134,7 @@ use/symbolication use/symbols use/python - use/python-reference - use/lua-reference + use/scripting-reference use/remote use/qemu-testing use/troubleshooting diff --git a/lldb/docs/use/python-reference.rst b/lldb/docs/use/scripting-reference.rst rename from lldb/docs/use/python-reference.rst rename to lldb/docs/use/scripting-reference.rst --- a/lldb/docs/use/python-reference.rst +++ b/lldb/docs/use/scripting-reference.rst @@ -1,23 +1,30 @@ -Python Reference -================ +Scripting Reference +=================== -The entire LLDB API is available as Python functions through a script bridging -interface. This means the LLDB API's can be used directly from python either -interactively or to build python apps that provide debugger features. - -Additionally, Python can be used as a programmatic interface within the lldb -command interpreter (we refer to this for brevity as the embedded interpreter). +Python can be used as a programmatic interface within the LLDB command +interpreter (we refer to this for brevity as the embedded interpreter). Of course, in this context it has full access to the LLDB API - with some additional conveniences we will call out in the FAQ. +Additionally, the entire LLDB API is available as Python functions through +a script bridging interface. This means the LLDB API's can be used directly +from Python either interactively or to build Python apps that provide debugger +features. + +At present, Lua is experimentally available as an embedded interpreter in LLDB. +Since some scripting features are still unavailable in Lua, there is no language +switch tab on code blocks of unsupported features. If you want to use Lua +interpreter, you should ensure that your LLDB is compiled with Lua support. +See :doc:`Building ` for instructions. + .. contents:: :local: -Documentation --------------- +Built-in Documentation +---------------------- -The LLDB API is contained in a python module named lldb. A useful resource when -writing Python extensions is the lldb Python classes reference guide. +The LLDB API is contained in a Python module named ``lldb``. A useful resource +when writing Python extensions is the `lldb` Python classes reference guide. The documentation is also accessible in an interactive debugger session with the following command: @@ -54,7 +61,8 @@ | ... -Or you can get help using any python object, here we use the lldb.process + +Or you can get help using any Python object, here we use the lldb.process object which is a global variable in the lldb module which represents the currently selected process: @@ -74,25 +82,53 @@ | ... -Embedded Python Interpreter +Embedded Script Interpreter --------------------------- -The embedded python interpreter can be accessed in a variety of ways from -within LLDB. The easiest way is to use the lldb command script with no -arguments at the lldb command prompt: +The embedded script interpreter can be accessed in a variety of ways from +within LLDB. The easiest way is to use the LLDB command ``script`` with no +arguments at the LLDB command prompt. + +By default, the embedded script interpreter is Python. To choose the language +you prefer, you can specify default language via ``--script-language`` options +when launching LLDB: + +:: + + $ lldb --script-language lua + +or pass a parameter to LLDB command ``script``. :: - (lldb) script - Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. - >>> 2+3 - 5 - >>> hex(12345) - '0x3039' - >>> + (lldb) script -l lua -- + +Language features are all available in the embedded script interpreter: + +.. tabs:: + .. code-tab:: python + + (lldb) script + Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. + >>> 2+3 + 5 + >>> hex(12345) + '0x3039' + >>> + + .. code-tab:: lua + :emphasize-lines: 1 + + (lldb) script -l lua -- + >>> t = { 1, 2, 3 } + >>> print(t[1]) + 1 + >>> print(t[1] + t[2]) + 3 + >>> -This drops you into the embedded python interpreter. When running under the -script command, lldb sets some convenience variables that give you quick access +This drops you into the embedded script interpreter. When running under the +script command, LLDB sets some convenience variables that give you quick access to the currently selected entities that characterize the program and debugger state. In each case, if there is no currently selected entity of the appropriate type, the variable's IsValid method will return false. These @@ -138,60 +174,84 @@ Moreover, they are only defined and meaningful while in the interactive Python interpreter. There is no guarantee on their value in any other situation, hence -you should not use them when defining Python formatters, breakpoint scripts and -commands (or any other Python extension point that LLDB provides). For the +you should not use them when defining custom formatters, breakpoint scripts and +commands (or any other script extension point that LLDB provides). For the latter you'll be passed an `SBDebugger`, `SBTarget`, `SBProcess`, `SBThread` or `SBframe` instance and you can use the functions from the "Equivalent" column to navigate between them. -As a rationale for such behavior, consider that lldb can run in a multithreaded +As a rationale for such behavior, consider that LLDB can run in a multithreaded environment, and another thread might call the "script" command, changing the value out from under you. To get started with these objects and LLDB scripting, please note that almost -all of the lldb Python objects are able to briefly describe themselves when you -pass them to the Python print function: - -:: - - (lldb) script - Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. - >>> print lldb.debugger - Debugger (instance: "debugger_1", id: 1) - >>> print lldb.target - a.out - >>> print lldb.process - SBProcess: pid = 59289, state = stopped, threads = 1, executable = a.out - >>> print lldb.thread - SBThread: tid = 0x1f03 - >>> print lldb.frame - frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16 - - -Running a python script when a breakpoint gets hit --------------------------------------------------- - -One very powerful use of the lldb Python API is to have a python script run -when a breakpoint gets hit. Adding python scripts to breakpoints provides a way -to create complex breakpoint conditions and also allows for smart logging and -data gathering. +all of the lldb objects are able to briefly describe themselves when you pass +them to ``print`` function: + +.. tabs:: + .. code-tab:: python + + (lldb) script + Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. + >>> print lldb.debugger + Debugger (instance: "debugger_1", id: 1) + >>> print lldb.target + a.out + >>> print lldb.process + SBProcess: pid = 59289, state = stopped, threads = 1, executable = a.out + >>> print lldb.thread + SBThread: tid = 0x1f03 + >>> print lldb.frame + frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16 + + .. code-tab:: lua + + (lldb) script -l lua -- + >>> print(lldb.debugger) + Debugger (instance: "debugger_1", id: 1) + >>> print(lldb.target) + a.out + >>> print(lldb.process) + SBProcess: pid = 3385871, state = stopped, threads = 1, executable = a.out + >>> print(lldb.thread) + thread #1: tid = 3385871, name = 'a.out', stop reason = breakpoint 1.1 + >>> print(lldb.frame) + frame #0: 0x000055555555514f a.out main at test.c:5:3 + +Running a script when a breakpoint gets hit +------------------------------------------- + +One very powerful use of the LLDB API is to have a script run when a breakpoint +gets hit. Adding python scripts to breakpoints provides a way to create complex +breakpoint conditions and also allows for smart logging and data gathering. When your process hits a breakpoint to which you have attached some python code, the code is executed as the body of a function which takes three arguments: -:: +.. tabs:: + .. code-tab:: python - def breakpoint_function_wrapper(frame, bp_loc, internal_dict): - # Your code goes here + def breakpoint_function_wrapper(frame, bp_loc, internal_dict): + # Your code goes here + + .. code-tab:: lua + + function breakpoint_function_wrapper(frame, bp_loc) + -- Your code goes here or: -:: +.. tabs:: + .. code-tab:: python + + def breakpoint_function_wrapper(frame, bp_loc, extra_args, internal_dict): + # Your code goes here - def breakpoint_function_wrapper(frame, bp_loc, extra_args, internal_dict): - # Your code goes here + .. code-tab:: lua + function breakpoint_function_wrapper(frame, bp_loc, ...) + -- Your code goes here +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ | Argument | Type | Description | @@ -209,7 +269,7 @@ | | | you could take the function name from a field in the `extra_args`, making the callback more general. The `-k` and `-v` options | | | | to `breakpoint command add` will be passed as a Dictionary in the `extra_args` parameter, or you can provide it with the SB API's. | +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| `internal_dict` | `dict` | The python session dictionary as a standard python dictionary object. | +| `internal_dict` | `dict` | The Python session dictionary as a standard python dictionary object. | +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ Optionally, a Python breakpoint command can return a value. Returning False @@ -242,38 +302,60 @@ Here is the code: -:: - - (lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib - Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223 - (lldb) script counter = 0 - (lldb) breakpoint command add --script-type python 1 - Enter your Python command(s). Type 'DONE' to end. - > # Increment our counter. Since we are in a function, this must be a global python variable - > global counter - > counter += 1 - > # Get the name of the function - > name = frame.GetFunctionName() - > # Print the order and the function name - > print '[%i] %s' % (counter, name) - > # Disable the current breakpoint location so it doesn't get hit again - > bp_loc.SetEnabled(False) - > # No need to stop here - > return False - > DONE - -The breakpoint command add command above attaches a python script to breakpoint 1. To remove the breakpoint command: +.. tabs:: + .. code-tab:: python + + (lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib + Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223 + (lldb) script counter = 0 + (lldb) breakpoint command add --script-type python 1 + Enter your Python command(s). Type 'DONE' to end. + > # Increment our counter. Since we are in a function, this must be a global python variable + > global counter + > counter += 1 + > # Get the name of the function + > name = frame.GetFunctionName() + > # Print the order and the function name + > print '[%i] %s' % (counter, name) + > # Disable the current breakpoint location so it doesn't get hit again + > bp_loc.SetEnabled(False) + > # No need to stop here + > return False + > DONE + + .. code-tab:: lua + + (lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib + Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223 + (lldb) script -l lua -- counter = 0 + (lldb) breakpoint command add -s lua 1 + Enter your Lua command(s). Type 'quit' to end. + The commands are compiled as the body of the following Lua function + function (frame, bp_loc, ...) end + ..> -- Increment our counter + ..> counter = counter + 1 + ..> -- Get the name of the function + ..> name = frame:GetFunctionName() + ..> -- Print the order and the function name + ..> print(string.format('[%i] %s', counter, name)) + ..> -- Disable the current breakpoint location so it doesn't get hit again + ..> bp_loc:SetEnabled(false) + ..> -- No need to stop here + ..> return false + ..> quit + +The breakpoint command add command above attaches a python script to +breakpoint 1. To remove the breakpoint command: :: (lldb) breakpoint command delete 1 -Using the python api's to create custom breakpoints ---------------------------------------------------- - +Create custom breakpoints +------------------------- -Another use of the Python API's in lldb is to create a custom breakpoint +Another use of the scripting API's in lldb is to create a custom breakpoint resolver. This facility was added in r342259. It allows you to provide the algorithm which will be used in the breakpoint's @@ -423,8 +505,8 @@ you pass in empty lists, the breakpoint will use the default "search everywhere,accept everything" filter. -Using the python API' to create custom stepping logic ------------------------------------------------------ +Create custom stepping logic +---------------------------- A slightly esoteric use of the Python API's is to construct custom stepping types. LLDB's stepping is driven by a stack of "thread plans" and a fairly @@ -486,8 +568,8 @@ while performing the step-over. -Create a new lldb command using a Python function -------------------------------------------------- +Create a new lldb command +------------------------- Python functions can be used to create new LLDB command interpreter commands, which will work like all the natively defined lldb commands. This provides a @@ -527,7 +609,7 @@ +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ | `debugger` | `lldb.SBDebugger` | The current debugger object. | +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ -| `command` | `python string` | A python string containing all arguments for your command. If you need to chop up the arguments | +| `command` | `string` | A python string containing all arguments for your command. If you need to chop up the arguments | | | | try using the `shlex` module's shlex.split(command) to properly extract the | | | | arguments. | +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+