Index: docs/CMakeLists.txt =================================================================== --- docs/CMakeLists.txt +++ docs/CMakeLists.txt @@ -1,4 +1,3 @@ - include(FindDoxygen) if(DOXYGEN_FOUND) @@ -39,3 +38,12 @@ COMMENT "Generating LLDB Python API reference with epydoc" VERBATIM ) endif(EPYDOC_EXECUTABLE) + +if (LLVM_ENABLE_SPHINX) + include(AddSphinxTarget) + if (SPHINX_FOUND) + if (${SPHINX_OUTPUT_HTML}) + add_sphinx_target(html lldb) + endif() + endif() +endif() Index: docs/conf.py =================================================================== --- /dev/null +++ docs/conf.py @@ -0,0 +1,240 @@ +# -*- coding: utf-8 -*- +# +# LLDB documentation build configuration file, created by +# sphinx-quickstart on Sun Dec 9 20:01:55 2012. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os +from datetime import date + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# 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'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'LLDB' +copyright = u'2007-%d, The LLDB Team' % date.today().year + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short version. +version = '8' +# The full version, including alpha/beta/rc tags. +release = '8' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build', 'analyzer'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'friendly' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'haiku' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'LLDBdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# 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'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (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'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' Index: docs/index.rst =================================================================== --- /dev/null +++ docs/index.rst @@ -0,0 +1,35 @@ +.. title:: Welcome to LLDB's documentation! + +Goals & Status +============== + +.. toctree:: + :maxdepth: 1 + + status/about + status/goals + status/features + status/status + status/projects + +Use & Extension +=============== + +.. toctree:: + :maxdepth: 1 + + use/tutorial + +Resources +========= + +.. toctree:: + :maxdepth: 1 + + resources/test + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` Index: docs/resources/test.rst =================================================================== --- /dev/null +++ docs/resources/test.rst @@ -0,0 +1,164 @@ +Testing LLDB +============ + +The LLDB test suite consists of Python scripts located under the test +directory. Each script contains a number of test cases and is usually +accompanied by a C (C++, ObjC, etc.) source file. Each test first compiles the +source file and then uses LLDB to debug the resulting executable. The tests +verify both the LLDB command line interface and the scripting API. + +.. contents:: + :local: + +Running the Full Test Suite +--------------------------- + +**Windows Note**: In the examples that follow, any invocations of python should +be replaced with python_d, the debug interpreter, when running the test suite +against a debug version of LLDB. + +The easiest way to run the LLDB test suite is to use the ``check-lldb`` build +target. By default, the ``check-lldb`` target builds the test programs with the +same compiler that was used to build LLDB. To build the tests with a different +compiler, you can set the ``LLDB_TEST_C_COMPILER`` or the ``LLDB_TEST_CXX_COMPILER`` +CMake variables. These variables are ignored unless the respective +``LLDB_TEST_USE_CUSTOM_C_COMPILER`` and ``LLDB_TEST_USE_CUSTOM_CXX_COMPILER`` are set +to ``ON``. + +It is possible to customize the architecture of the test binaries and compiler +used by appending ``-A`` and ``-C`` options respectively to the CMake variable +``LLDB_TEST_USER_ARGS``. For example, to test LLDB against 32-bit binaries +built with a custom version of clang, do: + +:: + + > cmake -DLLDB_TEST_USER_ARGS="-A i386 -C /path/to/custom/clang" -G Ninja + > ninja check-lldb + +Note that multiple ``-A`` and ``-C`` flags can be specified to +``LLDB_TEST_USER_ARGS``. + +Note that on NetBSD you must export ``LD_LIBRARY_PATH=$PWD/lib`` in your +environment. This is due to lack of the ``$ORIGIN`` linker feature. + +Running a Specific Test or Set of Tests +--------------------------------------- + +In addition to running all the LLDB test suites with the "check-lldb" CMake target above, it is possible to run individual LLDB tests. For example, to run the test cases defined in TestInferiorCrashing.py, run: + +:: + + > cd $lldb/test + > python dotest.py --executable -p TestInferiorCrashing.py ../packages/Python/lldbsuite/test + +If the test is not specified by name (e.g. if you leave the -p argument off), LLDB will run all tests in that directory: + +:: + + > python dotest.py --executable functionalities/data-formatter + +Many more options that are available. To see a list of all of them, run: + +:: + + > python dotest.py -h + +The ``dotest.py`` script runs tests in parallel by default. To disable the parallel +test running feature, use the ``--no-multiprocess`` flag. The number of concurrent +tests is controlled by the ``LLDB_TEST_THREADS`` environment variable or the +``--threads command`` line parameter. The default value is the number of CPU cores +on your system. + +The parallel test running feature will handle an additional ``--test-subdir +SUBDIR`` arg. When specified, ``SUBDIR`` is relative to the root test directory +and will limit all parallel test running to that subdirectory's tree of tests. + +The parallel test runner will run all tests within a given directory serially, +but will run multiple directories concurrently. Thus, as a test writer, we +provide serialized test run semantics within a directory. Note child +directories are considered entirely separate, so two child directories could be +running in parallel with a parent directory. + +Running the Test Suite Remotely +------------------------------- + +Running the test-suite remotely is similar to the process of running a local +test suite, but there are two things to have in mind: + +1. You must have the lldb-server running on the remote system, ready to accept + multiple connections. For more information on how to setup remote debugging + see the Remote debugging page. +2. You must tell the test-suite how to connect to the remote system. This is + achieved using the ``--platform-name``, ``--platform-url`` and + ``--platform-working-dir`` parameters to ``dotest.py``. These parameters + correspond to the platform select and platform connect LLDB commands. You + will usually also need to specify the compiler and architecture for the + remote system. + +Currently, running the remote test suite is supported only with ``dotest.py`` (or +dosep.py with a single thread), but we expect this issue to be addressed in the +near future. + +Debugging Test Failures +----------------------- + +On non-Windows platforms, you can use the ``-d`` option to ``dotest.py`` which +will cause the script to wait for a while until a debugger is attached. + +Debugging Test Failures on Windows +---------------------------------- + +On Windows, it is strongly recommended to use Python Tools for Visual Studio +for debugging test failures. It can seamlessly step between native and managed +code, which is very helpful when you need to step through the test itself, and +then into the LLDB code that backs the operations the test is performing. + +A quick guide to getting started with PTVS is as follows: + +#. Install PTVS +#. Create a Visual Studio Project for the Python code. + #. Go to File -> New -> Project -> Python -> From Existing Python Code. + #. Choose llvm/tools/lldb as the directory containing the Python code. + #. When asked where to save the .pyproj file, choose the folder ``llvm/tools/lldb/pyproj``. This is a special folder that is ignored by the ``.gitignore`` file, since it is not checked in. +#. Set test/dotest.py as the startup file +#. Make sure there is a Python Environment installed for your distribution. For example, if you installed Python to ``C:\Python35``, PTVS needs to know that this is the interpreter you want to use for running the test suite. + #. Go to Tools -> Options -> Python Tools -> Environment Options + #. Click Add Environment, and enter Python 3.5 Debug for the name. Fill out the values correctly. +#. Configure the project to use this debug interpreter. + #. Right click the Project node in Solution Explorer. + #. In the General tab, Make sure Python 3.5 Debug is the selected Interpreter. + #. In Debug/Search Paths, enter the path to your ninja/lib/site-packages directory. + #. In Debug/Environment Variables, enter ``VCINSTALLDIR=C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\``. + #. If you want to enabled mixed mode debugging, check Enable native code debugging (this slows down debugging, so enable it only on an as-needed basis.) +#. Set the command line for the test suite to run. + #. Right click the project in solution explorer and choose the Debug tab. + #. Enter the arguments to dotest.py. Note you must add --no-multiprocess + #. Example command options: + +:: + + # quiet mode + -q + --arch=i686 + # Path to debug lldb.exe + --executable D:/src/llvmbuild/ninja/bin/lldb.exe + # Directory to store log files + -s D:/src/llvmbuild/ninja/lldb-test-traces + -u CXXFLAGS -u CFLAGS + # If a test crashes, show JIT debugging dialog. + --enable-crash-dialog + # Path to release clang.exe + -C d:\src\llvmbuild\ninja_release\bin\clang.exe + # Path to the particular test you want to debug. + -p TestPaths.py + # Root of test tree + D:\src\llvm\tools\lldb\packages\Python\lldbsuite\test + # Required in order to be able to debug the test. + --no-multiprocess + +:: + + -q --arch=i686 --executable D:/src/llvmbuild/ninja/bin/lldb.exe -s D:/src/llvmbuild/ninja/lldb-test-traces -u CXXFLAGS -u CFLAGS --enable-crash-dialog -C d:\src\llvmbuild\ninja_release\bin\clang.exe -p TestPaths.py D:\src\llvm\tools\lldb\packages\Python\lldbsuite\test --no-multiprocess + + + Index: docs/status/about.rst =================================================================== --- /dev/null +++ docs/status/about.rst @@ -0,0 +1,98 @@ +About +===== + +LLDB is a next generation, high-performance debugger. It is built as a set of +reusable components which highly leverage existing libraries in the larger LLVM +Project, such as the Clang expression parser and LLVM disassembler. + +LLDB is the default debugger in Xcode on Mac OS X and supports debugging C, +Objective-C and C++ on the desktop and iOS devices and simulator. + +All of the code in the LLDB project is available under the standard `LLVM +License `__, an open source +"BSD-style" license. + +Why a New Debugger? +------------------- + +In order to achieve our goals we decided to start with a fresh architecture +that would support modern multi-threaded programs, handle debugging symbols in +an efficient manner, use compiler based code knowledge and have plug-in support +for functionality and extensions. Additionally we want the debugger +capabilities to be available to other analysis tools, be they scripts or +compiled programs, without requiring them to be GPL. + +Compiler Integration Benefits +----------------------------- + +LLDB currently converts debug information into clang types so that it can +leverage the clang compiler infrastructure. This allows LLDB to support the +latest C, C++, Objective-C and Objective-C++ language features and runtimes in +expressions without having to reimplement any of this functionality. It also +leverages the compiler to take care of all ABI details when making functions +calls for expressions, when disassembling instructions and extracting +instruction details, and much more. + +The major benefits include: + +- Up to date language support for C, C++, Objective-C +- Multi-line expressions that can declare local variables and types +- Utilize the JIT for expressions when supported +- Evaluate expression Intermediate Representation (IR) when JIT can't be used + +Reusability +----------- + +The LLDB debugger APIs are exposed as a C++ object oriented interface in a +shared library. The lldb command line tool links to, and uses this public API. +On Mac OS X the shared library is exposed as a framework named LLDB.framework, +and unix systems expose it as lldb.so. The entire API is also then exposed +through Python script bindings which allow the API to be used within the LLDB +embedded script interpreter, and also in any python script that loads the +lldb.py module in standard python script files. See the Python Reference page +for more details on how and where Python can be used with the LLDB API. + +Sharing the LLDB API allows LLDB to not only be used for debugging, but also +for symbolication, disassembly, object and symbol file introspection, and much +more. + +Platform Support +---------------- + +LLDB is known to work on the following platforms, but ports to new platforms +are welcome: + +* Mac OS X desktop user space debugging for i386 and x86-64 +* iOS simulator debugging on i386 +* iOS device debugging on ARM +* Linux local user-space debugging for i386, x86-64 and PPC64le +* FreeBSD local user-space debugging for i386 and x86-64 +* Windows local user-space debugging for i386 (*) + +(*) Support for Windows is under active development. Basic functionality is +expected to work, with functionality improving rapidly. + +Get Involved +------------ + +To check out the code, use: + +svn co http://llvm.org/svn/llvm-project/lldb/trunk lldb + +Note that LLDB generally builds from top-of-trunk + +* On macOS with Xcode +* On Linux and FreeBSD (with clang and libstdc++/libc++) +* On NetBSD (with GCC and clang and libstdc++/libc++) +* On Windows with VS 2012 or higher using CMake + +See the LLDB Build Page for platform-specific build instructions. + +Discussions about LLDB should go to the `lldb-dev +`__ mailing list. Commit +messages for the lldb SVN module are automatically sent to the `lldb-commits +`__ mailing list , and +this is also the preferred mailing list for patch submissions. + +See the Projects page if you are looking for some interesting areas to +contribute to lldb. Index: docs/status/features.rst =================================================================== --- /dev/null +++ docs/status/features.rst @@ -0,0 +1,18 @@ +Features +======== + +LLDB supports a broad variety of basic debugging features such as reading DWARF, supporting step, next, finish, backtraces, etc. Some more interested bits are: + +* Plug-in architecture for portability and extensibility: + + * Object file parsers for executable file formats. Support currently includes Mach-O (32 and 64-bit) & ELF (32-bit). + * Object container parsers to extract object files contained within a file. Support currently includes universal Mach-O files & BSD Archives. + * Debug symbol file parsers to incrementally extract debug information from object files. Support currently includes DWARF & Mach-O symbol tables. + * Symbol vendor plug-ins collect data from a variety of different sources for an executable object. + * Disassembly plug-ins for each architecture. Support currently includes an LLVM disassembler for i386, x86-64 , ARM/Thumb, and PPC64le + * Debugger plug-ins implement the host and target specific functions required to debug. + +* SWIG-generated script bridging allows Python to access and control the public API of the debugger library. +* A remote protocol server, debugserver, implements Mac OS X debugging on i386 and x86-64. +* A command line debugger - the lldb executable itself. +* A framework API to the library. Index: docs/status/goals.rst =================================================================== --- /dev/null +++ docs/status/goals.rst @@ -0,0 +1,33 @@ +Goals +===== + +The current state of the art in open source debuggers are that they work in the +common cases for C applications, but don't handle many "hard cases" properly. +For example, C++ expression parsing, handling overloading, templates, +multi-threading, and other non-trivial scenarios all work in some base cases, +but don't work reliably. + +The goal of LLDB is to provide an amazing debugging experience that "just +works". We aim to solve these long-standing problems where debuggers get +confused, so that you can think about debugging your problem, not about +deficiencies in the debugger. + +With a long view, there is no good reason for a debugger to reinvent its own +C/C++ parser, type system, know all the target calling convention details, +implement its own disassembler, etc. By using the existing libraries vended by +the LLVM project, we believe that many of these problems will be defined away, +and the debugger can focus on important issues like process control, efficient +symbol reading and indexing, thread management, and other debugger-specific +problems. + +Some more specific goals include: + +* Build libraries for inclusion in IDEs, command line tools, and other analysis + tools +* High performance and efficient memory use +* Extensible: Python scriptable and use a plug-in architecture +* Reuse existing compiler technology where it makes sense +* Excellent multi-threaded debugging support +* Great support for C, Objective-C and C++ +* Retargetable to support multiple platforms +* Provide a base for debugger research and other innovation Index: docs/status/projects.rst =================================================================== --- /dev/null +++ docs/status/projects.rst @@ -0,0 +1,396 @@ +Projects +======== + +The following is a mostly unordered set of the ideas for improvements to the +LLDB debugger. Some are fairly deep, some would require less effort. + +.. contents:: + :local: + +Speed up type realization in lldb +--------------------------------- + +The type of problem I'm addressing here is the situation where you are +debugging a large program (lldb built with debug clang/swift will do) and you +go to print a simple expression, and lldb goes away for 30 seconds. When you +sample it, it is always busily churning through all the CU's in the world +looking for something. The problem isn't that looking for something in +particular is slow, but rather that we somehow turned an bounded search (maybe +a subtype of "std::string" into an unbounded search (all things with the name +of that subtype.) Or didn't stop when we got a reasonable answer proximate to +the context of the search, but let the search leak out globally. And quite +likely there are other issues that I haven't guessed yet. But if you end up +churning though 3 or 4 Gig of debug info, that's going to be slow no matter how +well written your debug reader is... + +My guess is the work will be more in the general symbol lookup than in the +DWARF parser in particular, but it may be a combination of both. + +As a user debugging a largish program, this is the most obvious lameness of +lldb. + +Symbol name completion in the expression parser +----------------------------------------------- + +This is the other obvious lameness of lldb. You can do: + +:: + + (lldb) frame var foo.b + +and we will tell you it is "foo.bar". But you can't do that in the expression +parser. This will require collaboration with the clang/swift folks to get the +right extension points in the compiler. And whatever they are, lldb will need +use them to tell the compiler about what names are available. It will be +important to avoid the pitfalls of #1 where we wander into the entire DWARF +world. + +Make a high speed asynchronous communication channel +---------------------------------------------------- + +All lldb debugging nowadays is done by talking to a debug agent. We used the +gdb-remote protocol because that is universal, and good enough, and you have to +support it anyway since so many little devices & JTAG's and VM's etc support +it. But it is really old, not terribly high performance, and can't really +handle sending or receiving messages while the process is supposedly running. +It should have compression built in, remove the hand-built checksums and rely +on the robust communication protocols we always have nowadays, allow for +out-of-order requests/replies, allow for reconnecting to a temporarily +disconnected debug session, regularize all of the packet formatting into JSON +or BSON or whatever while including a way to do large binary transfers. It must +be possible to come up with something faster, and better tunable for the many +communications pathways we end up supporting. + +Fix local variable lookup in the lldb expression parser +------------------------------------------------------- + +The injection of local variables into the clang expression parser is +currently done incorrectly - it happens too late in the lookup. This results +in namespace variables & functions, same named types and ivars shadowing +locals when it should be the other way around. An attempt was made to fix +this by manually inserting all the visible local variables into wrapper +function in the expression text. This mostly gets the job done but that +method means you have to realize all the types and locations of all local +variables for even the simplest of expressions, and when run on large +programs (e.g. lldb) it would cause unacceptable delays. And it was very +fragile since an error in realizing any of the locals would cause all +expressions run in that context to fail. We need to fix this by adjusting +the points where name lookup calls out to lldb in clang. + +Support calling SB & commands everywhere and support non-stop debugging +----------------------------------------------------------------------- + +There is a fairly ad-hoc system to handle when it is safe to run SB API's and +command line commands. This is actually a bit of a tricky problem, since we +allow access to the command line and SB API from some funky places in lldb. The +Operating System plugins are the most obvious instance, since they get run +right after lldb is told by debugserver that the process has stopped, but +before it has finished collating the information from the stop for presentation +to the higher levels. But breakpoint callbacks have some of the same problems, +and other things like the scripted stepping operations and any fancier +extension points we want to add to the debugger are going to be hard to +implement robustly till we work on a finer-grained and more explicit control +over who gets to control the process state. + +We also won't have any chance of supporting non-stop debugging - which is a +useful mode for programs that have a lot of high-priority or real-time worker +threads - until we get this sorted out. + +Finish the language abstraction and remove all the unnecessary API's +-------------------------------------------------------------------- + +An important part of making lldb a more useful "debugger toolkit" as opposed to +a C/C++/ObjC/Swift debugger is to have a clean abstraction for language +support. We did most, but not all, of the physical separation. We need to +finish that. And then by force of necessity the API's really look like the +interface to a C++ type system with a few swift bits added on. How you would +go about adding a new language is unclear and much more trouble than it is +worth at present. But if we made this nice, we could add a lot of value to +other language projects. + +Add some syntax to generate data formatters from type definitions +----------------------------------------------------------------- + +Uses of the data formatters fall into two types. There are data formatters for +types where the structure elements pretty much tell you how to present the +data, you just need a little expression language to express how to turn them +into what the user expects to see. Then there are the ones (like pretty much +all our Foundation/AppKit/UIKit formatters) that use deep magic to figure out +how the type is actually laid out. The latter are pretty much always going to +have to be done by hand. + +But for the ones where the information is expressed in the fields, it would be +great to have a way to express the instructions to produce summaries and +children in some form you could embed next to the types and have the compiler +produce a byte code form of the instructions and then make that available to +lldb along with the library. This isn't as simple as having clang run over the +headers and produce something from the types directly. After all, clang has no +way of knowing that the interesting thing about a std::vector is the elements +that you get by calling size (for the summary) and [] for the elements. But it +shouldn't be hard to come up with a generic markup to express this. + +Allow the expression parser to access dynamic type/data formatter information +----------------------------------------------------------------------------- + +This seems like a smaller one. The symptom is your object is Foo child of +Bar, and in the Locals view you see all the fields of Foo, but because the +static type of the object is Bar, you can't see any of the fields of Foo. +But if you could get this working, you could hijack the mechanism to make +the results of the value object summaries/synthetic children available to +expressions. And if you can do that, you could add other properties to an +object externally (through Python or some other extension point) and then +have these also available in the expression parser. You could use this to +express invariants for data structures, or other more advanced uses of types +in the debugger. + +Another version of this is to allow access to synthetic children in the +expression parser. Otherwise you end up in situations like: + +:: + + (lldb) print return_a_foo() + (SomeVectorLikeType) $1 = { + [0] = 0 + [1] = 1 + [2] = 2 + [3] = 3 + [4] = 4 + } + +That's good but: + +:: + + (lldb) print return_a_foo()[2] + +fails because the expression parser doesn't know anything about the +array-like nature of SomeVectorLikeType that it gets from the synthetic +children. + +Recover thread information lazily +--------------------------------- + +LLDB stores all the user intentions for a thread in the ThreadPlans stored in +the Thread class. That allows us to reliably implement a very natural model for +users moving through a debug session. For example, if step-over stops at a +breakpoint in an function in a younger region of the stack, continue will +complete the step-over rather than having to manually step out. But that means +that it is important that the Thread objects live as long as the Threads they +represent. For programs with many threads, but only one that you are debugging, +that makes stepping less efficient, since now you have to fetch the thread list +on every step or stepping doesn't work correctly. This is especially an issue +when the threads are provided by an Operating System plugin, where it may take +non-trivial work to reconstruct the thread list. It would be better to fetch +threads lazily but keep "unseen" threads in a holding area, and only retire +them when we know we've fetched the whole thread list and ensured they are no +longer alive. + +Add an extension point in the breakpoint search machinery +--------------------------------------------------------- + +This would allow highly customizable, algorithmic breakpoint types, like "break +on every use of some particular instruction, or instruction pattern, etc." + +Make Python-backed commands first class citizens +------------------------------------------------ + +As it stands, Python commands have no way to advertise their options. They are +required to parse their arguments by hand. That leads to inconsistency, and +more importantly means they can't take advantage of auto-generated help and +command completion. This leaves python-backed commands feeling worse than +built-in ones. + +As part of this job, it would also be great to hook automatically hook the +"type" of an option value or argument (e.g. eArgTypeShlibName) to sensible +default completers. You need to be able to over-ride this in more complicated +scenarios (like in "break set" where the presence of a "-s" option limits the +search for completion of a "-n" option.) But in common cases it is unnecessary +busy-work to have to supply the completer AND the type. If this worked, then it +would be easier for Python commands to also get correct completers. + +Reimplement the command interpreter commands using the SB API +------------------------------------------------------------- + +Currently, all the CommandObject::DoExecute methods are implemented using the +lldb_private API's. That generally means that there's code that gets duplicated +between the CommandObject and the SB API that does roughly the same thing. We +would reduce this code duplication, present a single coherent face to the users +of lldb, and keep ourselves more honest about what we need in the SB API's if +we implemented the CommandObjects::DoExecute methods using the SB API's. + +BTW, it is only the way it was much easier to develop lldb if it had a +functioning command-line early on. So we did that first, and developed the SB +API's when lldb was more mature. There's no good technical reason to have the +commands use the lldb_private API's. + +Documentation and better examples +--------------------------------- + +We need to put the lldb syntax docs in the tutorial somewhere that is more +easily accessible. On suggestion is to add non-command based help to the help +system, and then have a "help lldb" or "help syntax" type command with this +info. Be nice if the non-command based help could be hierarchical so you could +make topics. + +There's a fair bit of docs about the SB API's, but it is spotty. Some classes +are well documented in the Python "help (lldb.SBWhatever)" and some are not. + +We need more conceptual docs. And we need more examples. And we could provide a +clean pluggable example for using LLDB standalone from Python. The +process_events.py is a start of this, but it just handles process events, and +it is really a quick sketch not a polished expandable proto-tool. + +Make a more accessible plugin architecture for lldb +--------------------------------------------------- + +Right now, you can only use the Python or SB API's to extend an extant lldb. +You can't implement any of the actual lldb Plugins as plugins. That means +anybody that wants to add new Object file/Process/Language etc support has to +build and distribute their own lldb. This is tricky because the API's the +plugins use are currently not stable (and recently have been changing quite a +lot.) We would have to define a subset of lldb_private that you could use, and +some way of telling whether the plugins were compatible with the lldb. But +long-term, making this sort of extension possible will make lldb more appealing +for research and 3rd party uses. + +Use instruction emulation to reduce the overhead for breakpoints +---------------------------------------------------------------- + +At present, breakpoints are implemented by inserting a trap instruction, then +when the trap is hit, replace the trap with the actual instruction and single +step. Then swap back and continue. This causes problems for read only text, and +also means that no-stop debugging ust either stop all threads briefly to handle +this two-step or risk missing some breakpoint hits. If you emulated the +instruction and wrote back the results, you wouldn't have these problems, and +it would also save a stop per breakpoint hit. Since we use breakpoints to +implement stepping, this savings could be significant on slow connections. + +Use the JIT to speed up conditional breakpoint evaluation +--------------------------------------------------------- + +We already JIT and cache the conditional expressions for breakpoints for the C +family of languages, so we aren't re-compiling every time you hit the +breakpoint. And if we couldn't IR interpret the expression, we leave the JIT'ed +code in place for reuse. But it would be even better if we could also insert +the "stop or not" decision into the code at the breakpoint, so you would only +actually stop the process when the condition was true. Greg's idea was that if +you had a conditional breakpoint set when you started the debug session, Xcode +could rebuild and insert enough no-ops that we could instrument the breakpoint +site and call the conditional expression, and only trap if the conditional was +true. + +Broaden the idea in "target stop-hook" to cover more events in the debugger +--------------------------------------------------------------------------- + +Shared library loads, command execution, User directed memory/register reads +and writes are all places where you would reasonably want to hook into the +debugger. + +Mock classes for testing +------------------------ + +We need "ProcessMock" and "ObjectFileMock" and the like. These would be real +plugin implementations for their underlying lldb classes, with the addition +that you can prime them from some sort of text based input files. For classes +that manage changes over time (like process) you would need to program the +state at StopPoint 0, StopPoint 1, etc. These could then be used for testing +reactions to complex threading problems & the like, and also for simulating +hard-to-test environments (like bare board debugging). + +A Bug-Trapper infrastructure +---------------------------- + +We very often have bugs that can't be reproduced locally. So having a +bug-report-trapper that can gather enough information from the surroundings of +a bug so that we can replay the session locally would be a big help tracking +down issues in this situation. This is tricky because you can't necessarily +require folks to leak information about their code in order to file bug +reports. So not only will you have to figure out what state to gather, you're +also going to have to anonymize it somehow. But we very often have bugs from +people that can't reduce the problem to a simple test case and can't give us +our code, and we often just can't help them as things stand now. Note that +adding the ProcessMock would be a good first stage towards this, since you +could make a ProcessMock creator/serializer from the current lldb state. + +Expression parser needs syntax for "{symbol,type} A in CU B.cpp" +---------------------------------------------------------------- + +Sometimes you need to specify non-visible or ambiguous types to the expression +parser. We were planning to do $b_dot_cpp$A or something like. You might want +to specify a static in a function, in a source file, or in a shared library. So +the syntax should support all these. + +Add a "testButDontAbort" style test to the UnitTest framework +------------------------------------------------------------- + +The way we use unittest now (maybe this is the only way it can work, I don't +know) you can't report a real failure and continue with the test. That is +appropriate in some cases: if I'm supposed to hit breakpoint A before I +evaluate an expression, and don't hit breakpoint A, the test should fail. But +it means that if I want to test five different expressions, I can either do it +in one test, which is good because it means I only have to fire up one process, +attach to it, and get it to a certain point. But it also means if the first +test fails, the other four don't even get run. So though at first we wrote a +bunch of test like this, as time went on we switched more to writing "one at a +time" tests because they were more robust against a single failure. That makes +the test suite run much more slowly. It would be great to add a +"test_but_dont_abort" variant of the tests, then we could gang tests that all +drive to the same place and do similar things. As an added benefit, it would +allow us to be more thorough in writing tests, since each test would have lower +costs. + +Convert the dotest style tests to use lldbutil.run_to_source_breakpoint +----------------------------------------------------------------------- + +run_to_source_breakpoint & run_to_name_breakpoint provide a compact API that +does in one line what the first 10 or 20 lines of most of the old tests now do +by hand. Using these functions makes tests much more readable, and by +centralizing common functionality will make maintaining the testsuites easier +in the future. This is more of a finger exercise, and perhaps best implemented +by a rule like: "If you touch a test case, and it isn't using +run_to_source_breakpoint, please make it do so". + +Unify Watchpoint's & Breakpoints +-------------------------------- + +Option handling isn't shared, and more importantly the PerformAction's have a +lot of duplicated common code, most of which works less well on the Watchpoint +side. + +Reverse debugging +----------------- + +This is kind of a holy grail, it's hard to support for complex apps (many +threads, shared memory, etc.) But it would be SO nice to have... + +Non-stop debugging +------------------ + +By this I mean allowing some threads in the target program to run while +stopping other threads. This is supported in name in lldb at present, but lldb +makes the assumption "If I get a stop, I won't get another stop unless I +actually run the program." in a bunch of places so getting it to work reliably +will be some a good bit of work. And figuring out how to present this in the UI +will also be tricky. + +Fix and continue +---------------- + +We did this in gdb without a real JIT. The implementation shouldn't be that +hard, especially if you can build the executable for fix and continue. The +tricky part is how to verify that the user can only do the kinds of fixes that +are safe to do. No changing object sizes is easy to detect, but there were many +more subtle changes (function you are fixing is on the stack...) that take more +work to prevent. And then you have to explain these conditions the user in some +helpful way. + +Unified IR interpreter +---------------------- + +Currently IRInterpreter implements a portion of the LLVM IR, but it doesn't +handle vector data types and there are plenty of instructions it also doesn't +support. Conversely, lli supports most of LLVM's IR but it doesn't handle +remote memory and its function calling support is very rudimentary. It would be +useful to unify these and make the IR interpreter -- both for LLVM and LLDB -- +better. An alternate strategy would be simply to JIT into the current process +but have callbacks for non-stack memory access. Index: docs/status/status.rst =================================================================== --- /dev/null +++ docs/status/status.rst @@ -0,0 +1,65 @@ +Status +====== + +macOS +----- + +LLDB has matured a lot in the last year and can be used for C, C++ and +Objective-C development for x86_64, i386 and ARM debugging. The entire public +API is exposed though a framework on Mac OS X which is used by Xcode, the lldb +command line tool, and can also be used by Python. The entire public API is +exposed through script bridging which allows LLDB to use an embedded Python +script interpreter, as well as having a Python module named "lldb" which can be +used from Python on the command line. This allows debug sessions to be +scripted. It also allows powerful debugging actions to be created and attached +to a variety of debugging workflows. + +Linux +----- + +LLDB is improving on Linux. While the debugserver has not been ported (to +enable remote debugging) Linux is nearing feature completeness with Darwin to +debug x86_64 programs, and is partially working with i386 programs. ARM +architectures on Linux are untested. For more details, see the Features by OS +section below. + +FreeBSD +------- + +LLDB on FreeBSD lags behind the Linux implementation but is improving rapidly. +For more details, see the Features by OS section below. + +Windows +------- + +LLDB on Windows is still under development, but already useful for i386 +programs (x86_64 untested) built with DWARF debug information, including +postmortem analysis of minidumps. For more details, see the Features by OS +section below. + +Features Matrix +--------------- ++--------------------------------+------------+-------------------------+--------------------------------------+----------------------+ +| Feature | FreeBSD | Linux | Mac OS X (i386/x86_64 and ARM/Thumb) | Windows (i386) | +| | (x86_64) | (x86_64 and PPC64le) | | | ++================================+============+=========================+======================================+======================+ +| Backtracing | OK | OK | OK | OK | ++--------------------------------+------------+-------------------------+--------------------------------------+----------------------+ +| Breakpoints | OK | OK | OK | OK | ++--------------------------------+------------+-------------------------+--------------------------------------+----------------------+ +| C++11: | OK | OK | OK | Unknown | ++--------------------------------+------------+-------------------------+--------------------------------------+----------------------+ +| Commandline lldb tool | OK | OK | OK | OK | ++--------------------------------+------------+-------------------------+--------------------------------------+----------------------+ +| Core file debugging | OK (ELF) | OK (ELF) | OK (MachO) | OK (Minidump) | ++--------------------------------+------------+-------------------------+--------------------------------------+----------------------+ +| Debugserver (remote debugging) | Not ported | Not ported | OK | Not ported | ++--------------------------------+------------+-------------------------+--------------------------------------+----------------------+ +| Disassembly | OK | OK | OK | OK | ++--------------------------------+------------+-------------------------+--------------------------------------+----------------------+ +| Expression evaluation | Unknown | Works with some bugs | OK | Works with some bugs | ++--------------------------------+------------+-------------------------+--------------------------------------+----------------------+ +| JIT debugging | Unknown | Symbolic debugging only | Untested | No | ++--------------------------------+------------+-------------------------+--------------------------------------+----------------------+ +| Objective-C 2.0: | Unknown | Not applicable | OK | Not applicable | ++--------------------------------+------------+-------------------------+--------------------------------------+----------------------+ Index: docs/use/tutorial.rst =================================================================== --- /dev/null +++ docs/use/tutorial.rst @@ -0,0 +1,673 @@ +Tutorial +======== + +Here's a short precis of how to run lldb if you are familiar with the gdb +command set. We will start with some details on lldb command structure and +syntax to help orient you. + +.. contents:: + :local: + +Command Structure +----------------- + +Unlike gdb's command set, which is rather free-form, we tried to make the lldb command syntax fairly structured. The commands are all of the form: + +:: + + [-options [option-value]] [argument [argument...]] + +The command line parsing is done before command execution, so it is uniform +across all the commands. The command syntax for basic commands is very simple, +arguments, options and option values are all white-space separated, and +double-quotes are used to protect white-spaces in an argument. If you need to +put a backslash or double-quote character in an argument you back-slash it in +the argument. That makes the command syntax more regular, but it also means you +may have to quote some arguments in lldb that you wouldn't in gdb. + + +Options can be placed anywhere on the command line, but if the arguments begin +with a "-" then you have to tell lldb that you're done with options for the +current command by adding an option termination: "--" So for instance if you +want to launch a process and give the "process launch" command the +"--stop-at-entry" option, yet you want the process you are about to launch to +be launched with the arguments "-program_arg value", you would type: + +:: + + (lldb) process launch --stop-at-entry -- -program_arg value + +We also tried to reduce the number of special purpose argument parsers, which +sometimes forces the user to be a little more explicit about stating their +intentions. The first instance you'll note of this is the breakpoint command. +In gdb, to set a breakpoint, you might enter + +:: + + (gdb) break foo.c:12 + +to break at line 12 of foo.c, and: + +:: + + (gdb) break foo + +to break at the function foo. As time went on, the parser that tells foo.c:12 +from foo from foo.c::foo (which means the function foo in the file foo.c) got +more and more complex and bizarre, and especially in C++ there are times where +there's really no way to specify the function you want to break on. The lldb +commands are more verbose but also more precise and allow for intelligent auto +completion. + +To set the same file and line breakpoint in LLDB you can enter either of: + +:: + + (lldb) breakpoint set --file foo.c --line 12 + (lldb) breakpoint set -f foo.c -l 12 + +To set a breakpoint on a function named foo in LLDB you can enter either of: + +:: + + (lldb) breakpoint set --name foo + (lldb) breakpoint set -n foo + +You can use the --name option multiple times to make a breakpoint on a set of +functions as well. This is convenient since it allows you to set common +conditions or commands without having to specify them multiple times: + +:: + + (lldb) breakpoint set --name foo --name bar + +Setting breakpoints by name is even more specialized in LLDB as you can specify +that you want to set a breakpoint at a function by method name. To set a +breakpoint on all C++ methods named foo you can enter either of: + +:: + + (lldb) breakpoint set --method foo + (lldb) breakpoint set -M foo + + +To set a breakpoint Objective-C selectors named alignLeftEdges: you can enter either of: + +:: + + (lldb) breakpoint set --selector alignLeftEdges: + (lldb) breakpoint set -S alignLeftEdges: + +You can limit any breakpoints to a specific executable image by using the +"--shlib " ("-s " for short): + +:: + + (lldb) breakpoint set --shlib foo.dylib --name foo + (lldb) breakpoint set -s foo.dylib -n foo + +The --shlib option can also be repeated to specify several shared libraries. + +Suggestions on more interesting primitives of this sort are also very welcome. + +Just like gdb, the lldb command interpreter does a shortest unique string match +on command names, so the following two commands will both execute the same +command: + +:: + + (lldb) breakpoint set -n "-[SKTGraphicView alignLeftEdges:]" + (lldb) br s -n "-[SKTGraphicView alignLeftEdges:]" + +lldb also supports command completion for source file names, symbol names, file +names, etc. Completion is initiated by a hitting a TAB. Individual options in a +command can have different completers, so for instance the "--file " +option in "breakpoint" completes to source files, the "--shlib " option +to currently loaded shared libraries, etc. We can even do things like if you +specify "--shlib ", and are completing on "--file ", we will only +list source files in the shared library specified by "--shlib ". + +The individual commands are pretty extensively documented. You can use the help +command to get an overview of which commands are available or to obtain details +about specific commands. There is also an apropos command that will search the +help text for all commands for a particular word and dump a summary help string +for each matching command. + +Finally, there is a mechanism to construct aliases for commonly used commands. +So for instance if you get annoyed typing: + +:: + + (lldb) breakpoint set --file foo.c --line 12 + +you can do: + +:: + + (lldb) command alias bfl breakpoint set -f %1 -l %2 + (lldb) bfl foo.c 12 + +We have added a few aliases for commonly used commands (e.g. "step", "next" and +"continue") but we haven't tried to be exhaustive because in our experience it +is more convenient to make the basic commands unique down to a letter or two, +and then learn these sequences than to fill the namespace with lots of aliases, +and then have to type them all the way out. + +However, users are free to customize lldb's command set however they like, and +since lldb reads the file ~/.lldbinit at startup, you can store all your +aliases there and they will be generally available to you. Your aliases are +also documented in the help command so you can remind yourself of what you've +set up. + +One alias of note that we do include by popular demand is a weak emulator of +gdb's "break" command. It doesn't try to do everything that gdb's break command +does (for instance, it doesn't handle foo.c::bar. But it mostly works, and +makes the transition easier. Also by popular demand, it is aliased to b. If you +actually want to learn the lldb command set natively, that means it will get in +the way of the rest of the breakpoint commands. Fortunately, if you don't like +one of our aliases, you an easily get rid of it by running (for example): + +:: + + (lldb) command unalias b + +I actually also do: + +:: + + (lldb) command alias b breakpoint + +so I can run the native lldb breakpoint command with just b + +The lldb command parser also supports "raw" commands, where, after command +options are stripped off, the rest of the command string is passed +uninterpreted to the command. This is convenient for commands whose arguments +might be some complex expression that would be painful to backslash protect. +For instance the "expression" command is a "raw" command for obvious reasons. +The "help" output for a command will tell you if it is "raw" or not, so you +know what to expect. The one thing you have to watch out for is that since raw +commands still can have options, if your command string has dashes in it, +you'll have to indicate these are not option markers by putting "--" after the +command name, but before your command string. + +lldb also has a built-in Python interpreter, which is accessible by the +"script" command. All the functionality of the debugger is available as classes +in the Python interpreter, so the more complex commands that in gdb you would +introduce with the "define" command can be done by writing Python functions +using the lldb-Python library, then loading the scripts into your running +session and accessing them with the "script" command. + +Having given an overview of lldb's command syntax, we proceed to lay out the +stages of a standard debug session. + + +Loading a Program into lldb +--------------------------- + +First we need to set the program to debug. As with gdb, you can start lldb and specify the file you wish to debug on the command line: + +:: + + $ lldb /Projects/Sketch/build/Debug/Sketch.app + Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64). + +or you can specify it after the fact with the "file" command: + +:: + + $ lldb + (lldb) file /Projects/Sketch/build/Debug/Sketch.app + Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64). + +Setting Breakpoints +------------------- + +We've discussed how to set breakpoints above. You can use help breakpoint set +to see all the options for breakpoint setting. For instance, we might do: + +:: + + (lldb) breakpoint set --selector alignLeftEdges: + Breakpoint created: 1: name = 'alignLeftEdges:', locations = 1, resolved = 1 + +You can find out about the breakpoints you've set with: + +:: + + (lldb) breakpoint list + Current breakpoints: + 1: name = 'alignLeftEdges:', locations = 1, resolved = 1 + 1.1: where = Sketch`-[SKTGraphicView alignLeftEdges:] + 33 at /Projects/Sketch/SKTGraphicView.m:1405, address = 0x0000000100010d5b, resolved, hit count = 0 + + +Note that setting a breakpoint creates a logical breakpoint, which could +resolve to one or more locations. For instance, break by selector would set a +breakpoint on all the methods that implement that selector in the classes in +your program. Similarly, a file and line breakpoint might result in multiple +locations if that file and line were inlined in different places in your code. + +The logical breakpoint has an integer id, and it's locations have an id within +their parent breakpoint (the two are joined by a ".", e.g. 1.1 in the example +above.) + +Also the logical breakpoints remain live so that if another shared library were +to be loaded that had another implementation of the "alignLeftEdges:" selector, +the new location would be added to breakpoint 1 (e.g. a "1.2" breakpoint would +be set on the newly loaded selector). + +The other piece of information in the breakpoint listing is whether the +breakpoint location was resolved or not. A location gets resolved when the file +address it corresponds to gets loaded into the program you are debugging. For +instance if you set a breakpoint in a shared library that then gets unloaded, +that breakpoint location will remain, but it will no longer be resolved. + + +One other thing to note for gdb users is that lldb acts like gdb with: + +:: + + (gdb) set breakpoint pending on + +That is, lldb will always make a breakpoint from your specification, even if it +couldn't find any locations that match the specification. You can tell whether +the expression was resolved or not by checking the locations field in +"breakpoint list", and we report the breakpoint as "pending" when you set it so +you can tell you've made a typo more easily, if that was indeed the reason no +locations were found: + + +:: + + (lldb) breakpoint set --file foo.c --line 12 + Breakpoint created: 2: file ='foo.c', line = 12, locations = 0 (pending) + WARNING: Unable to resolve breakpoint to any actual locations. + +You can delete, disable, set conditions and ignore counts either on all the +locations generated by your logical breakpoint, or on any one of the particular +locations your specification resolved to. For instance if we wanted to add a +command to print a backtrace when we hit this breakpoint we could do: + +:: + + (lldb) breakpoint command add 1.1 + Enter your debugger command(s). Type 'DONE' to end. + > bt + > DONE + +By default, the breakpoint command add command takes lldb command line +commands. You can also specify this explicitly by passing the "--command" +option. Use "--script" if you want to implement your breakpoint command using +the Python script instead. + +This is an convenient point to bring up another feature of the lldb command +help. Do: + +:: + + (lldb) help break command add + Add a set of commands to a breakpoint, to be executed whenever the breakpoint is hit. + + Syntax: breakpoint command add + etc... + +When you see arguments to commands specified in the Syntax in angle brackets +like , that indicates that that is some common argument type that +you can get further help on from the command system. So in this case you could +do: + +:: + + (lldb) help -- Breakpoint ID's consist major and + minor numbers; the major etc... + + +Breakpoint Names +---------------- + +Breakpoints carry two orthognal sets of information: one specifies where to set the breakpoint, and the other how to react when the breakpoint is hit. The latter set of information (e.g. commands, conditions, hit-count, auto-continue...) we call breakpoint options. + +It is fairly common to want to apply one set of options to a number of breakpoints. For instance, you might want to check that self == nil and if it is, print a backtrace and continue, on a number of methods. One convenient way to do that would be to make all the breakpoints, then configure the options with: + +:: + + (lldb) breakpoint modify -c "self == nil" -C bt --auto-continue 1 2 3 + +That's not too bad, but you have to repeat this for every new breakpoint you make, and if you wanted to change the options, you have to remember all the ones you are using this way. + +Breakpoint names provide a convenient solution to this problem. The simple solution would be to use the name to gather the breakpoints you want to affect this way into a group. So when you make the breakpoint you would do: + +:: + + (lldb) breakpoint set -N SelfNil + +Then when you've made all your breakpoints, you can set up or modify the options using the name to collect all the relevant breakpoints. + +:: + + (lldb) breakpoint modify -c "self == nil" -C bt --auto-continue SelfNil + +That is better, but suffers from the problem that when new breakpoints get +added, they don't pick up these modifications, and the options only exist in +the context of actual breakpoints, so they are hard to store & reuse. + +A even better solution is to make a fully configured breakpoint name: + +:: + + (lldb) breakpoint name configure -c "self == nil" -C bt --auto-continue SelfNil + +Then you can apply the name to your breakpoints, and they will all pick up +these options. The connection from name to breakpoints remains live, so when +you change the options configured on the name, all the breakpoints pick up +those changes. This makes it easy to use configured names to experiment with +your options. + +You can make breakpoint names in your .lldbinit file, so you can use them to +can behaviors that you have found useful and reapply them in future sessions. + +You can also make a breakpoint name from the options set on a breakpoint: + +:: + + (lldb) breakpoint name configure -B 1 SelfNil + +which makes it easy to copy behavior from one breakpoint to a set of others. + +Setting Watchpoints +------------------- + +In addition to breakpoints, you can use help watchpoint to see all the commands +for watchpoint manipulations. For instance, we might do the following to watch +a variable called 'global' for write operation, but only stop if the condition +'(global==5)' is true: + +:: + + (lldb) watch set var global + Watchpoint created: Watchpoint 1: addr = 0x100001018 size = 4 state = enabled type = w + declare @ '/Volumes/data/lldb/svn/ToT/test/functionalities/watchpoint/watchpoint_commands/condition/main.cpp:12' + (lldb) watch modify -c '(global==5)' + (lldb) watch list + Current watchpoints: + Watchpoint 1: addr = 0x100001018 size = 4 state = enabled type = w + declare @ '/Volumes/data/lldb/svn/ToT/test/functionalities/watchpoint/watchpoint_commands/condition/main.cpp:12' + condition = '(global==5)' + (lldb) c + Process 15562 resuming + (lldb) about to write to 'global'... + Process 15562 stopped and was programmatically restarted. + Process 15562 stopped and was programmatically restarted. + Process 15562 stopped and was programmatically restarted. + Process 15562 stopped and was programmatically restarted. + Process 15562 stopped + * thread #1: tid = 0x1c03, 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16, stop reason = watchpoint 1 + frame #0: 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16 + 13 + 14 static void modify(int32_t &var) { + 15 ++var; + -> 16 } + 17 + 18 int main(int argc, char** argv) { + 19 int local = 0; + (lldb) bt + * thread #1: tid = 0x1c03, 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16, stop reason = watchpoint 1 + frame #0: 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16 + frame #1: 0x0000000100000eac a.out`main + 108 at main.cpp:25 + frame #2: 0x00007fff8ac9c7e1 libdyld.dylib`start + 1 + (lldb) frame var global + (int32_t) global = 5 + (lldb) watch list -v + Current watchpoints: + Watchpoint 1: addr = 0x100001018 size = 4 state = enabled type = w + declare @ '/Volumes/data/lldb/svn/ToT/test/functionalities/watchpoint/watchpoint_commands/condition/main.cpp:12' + condition = '(global==5)' + hw_index = 0 hit_count = 5 ignore_count = 0 + (lldb) + +Starting or Attaching to Your Program +------------------------------------- + +To launch a program in lldb we use the "process launch" command or one of its built in aliases: + +:: + + (lldb) process launch + (lldb) run + (lldb) r + +You can also attach to a process by process ID or process name. When attaching +to a process by name, lldb also supports the "--waitfor" option which waits for +the next process that has that name to show up, and attaches to it + +:: + + (lldb) process attach --pid 123 + (lldb) process attach --name Sketch + (lldb) process attach --name Sketch --waitfor + +After you launch or attach to a process, your process might stop somewhere: + +:: + + (lldb) process attach -p 12345 + Process 46915 Attaching + Process 46915 Stopped + 1 of 3 threads stopped with reasons: + * thread #1: tid = 0x2c03, 0x00007fff85cac76a, where = libSystem.B.dylib`__getdirentries64 + 10, stop reason = signal = SIGSTOP, queue = com.apple.main-thread + +Note the line that says "1 of 3 threads stopped with reasons:" and the lines +that follow it. In a multi-threaded environment it is very common for more than +one thread to hit your breakpoint(s) before the kernel actually returns control +to the debugger. In that case, you will see all the threads that stopped for +some interesting reason listed in the stop message. + +Controlling Your Program +------------------------ + +After launching, we can continue until we hit our breakpoint. The primitive commands for process control all exist under the "thread" command: + +:: + + (lldb) thread continue + Resuming thread 0x2c03 in process 46915 + Resuming process 46915 + (lldb) + +At present you can only operate on one thread at a time, but the design will ultimately support saying "step over the function in Thread 1, and step into the function in Thread 2, and continue Thread 3" etc. When we eventually support keeping some threads running while others are stopped this will be particularly important. For convenience, however, all the stepping commands have easy aliases. So "thread continue" is just "c", etc. + +The other program stepping commands are pretty much the same as in gdb. You've got: + +:: + + (lldb) thread step-in // The same as gdb's "step" or "s" + (lldb) thread step-over // The same as gdb's "next" or "n" + (lldb) thread step-out // The same as gdb's "finish" or "f" + +By default, lldb does defined aliases to all common gdb process control commands ("s", "step", "n", "next", "finish"). If we have missed any, please add them to your ~/.lldbinit file using the "command alias" command. + +lldb also supported the step by instruction versions: + +:: + + + (lldb) thread step-inst // The same as gdb's "stepi" / "si" + (lldb) thread step-over-inst // The same as gdb's "nexti" / "ni" + +Finally, lldb has a run until line or frame exit stepping mode: + +:: + + (lldb) thread until 100 + +This command will run the thread in the current frame till it reaches line 100 +in this frame or stops if it leaves the current frame. This is a pretty close +equivalent to gdb's "until" command. + +A process, by default, will share the lldb terminal with the inferior process. +When in this mode, much like when debugging with gdb, when the process is +running anything you type will go to the STDIN of the inferior process. To +interrupt your inferior program, type CTRL+C. + +If you attach to a process, or launch a process with the "--no-stdin" option, +the command interpreter is always available to enter commands. This might be a +little disconcerting to gdb users when always have an (lldb) prompt. This +allows you to set a breakpoint, etc without having to explicitly interrupt the +program you are debugging: + +:: + + (lldb) process continue + (lldb) breakpoint set --name stop_here + +There are many commands that won't work while running, and the command +interpreter should do a good job of letting you know when this is the case. If +you find any instances where the command interpreter isn't doing its job, +please file a bug. This way of operation will set us up for a future debugging +mode called thread centric debugging. This mode will allow us to run all +threads and only stop the threads that are at breakpoints or have exceptions or +signals. + +The commands that currently work while running include interrupting the process +to halt execution ("process interrupt"), getting the process status ("process +status"), breakpoint setting and clearing (" breakpoint +[set|clear|enable|disable|list] ..."), and memory reading and writing (" memory +[read|write] ..."). + +The question of disabling stdio when running brings up a good opportunity to +show how to set debugger properties in general. If you always want to run in +the --no-stdin mode, you can set this as a generic process property using the +lldb "settings" command, which is equivalent to gdb's "set" command. For +instance, in this case you would say: + +:: + + (lldb) settings set target.process.disable-stdio true + +Over time, gdb's "set command became a wilderness of disordered options, so +that there were useful options that even experienced gdb users didn't know +about because they were too hard to find. We tried to organize the settings +hierarchically using the structure of the basic entities in the debugger. For +the most part anywhere you can specify a setting on a generic entity (threads, +for example) you can also apply the option to a particular instance, which can +also be convenient at times. You can view the available settings with "settings +list" and there is help on the settings command explaining how it works more +generally. + +Examining Thread State +---------------------- + +Once you've stopped, lldb will choose a current thread, usually the one that +stopped "for a reason", and a current frame in that thread (on stop this is +always the bottom-most frame). Many the commands for inspecting state work on +this current thread/frame. + +To inspect the current state of your process, you can start with the threads: + +:: + + (lldb) thread list + Process 46915 state is Stopped + * thread #1: tid = 0x2c03, 0x00007fff85cac76a, where = libSystem.B.dylib`__getdirentries64 + 10, stop reason = signal = SIGSTOP, queue = com.apple.main-thread + thread #2: tid = 0x2e03, 0x00007fff85cbb08a, where = libSystem.B.dylib`kevent + 10, queue = com.apple.libdispatch-manager + thread #3: tid = 0x2f03, 0x00007fff85cbbeaa, where = libSystem.B.dylib`__workq_kernreturn + 10 + +The ``*`` indicates that Thread 1 is the current thread. To get a backtrace for +that thread, do: + +:: + + (lldb) thread backtrace + thread #1: tid = 0x2c03, stop reason = breakpoint 1.1, queue = com.apple.main-thread + frame #0: 0x0000000100010d5b, where = Sketch`-[SKTGraphicView alignLeftEdges:] + 33 at /Projects/Sketch/SKTGraphicView.m:1405 + frame #1: 0x00007fff8602d152, where = AppKit`-[NSApplication sendAction:to:from:] + 95 + frame #2: 0x00007fff860516be, where = AppKit`-[NSMenuItem _corePerformAction] + 365 + frame #3: 0x00007fff86051428, where = AppKit`-[NSCarbonMenuImpl performActionWithHighlightingForItemAtIndex:] + 121 + frame #4: 0x00007fff860370c1, where = AppKit`-[NSMenu performKeyEquivalent:] + 272 + frame #5: 0x00007fff86035e69, where = AppKit`-[NSApplication _handleKeyEquivalent:] + 559 + frame #6: 0x00007fff85f06aa1, where = AppKit`-[NSApplication sendEvent:] + 3630 + frame #7: 0x00007fff85e9d922, where = AppKit`-[NSApplication run] + 474 + frame #8: 0x00007fff85e965f8, where = AppKit`NSApplicationMain + 364 + frame #9: 0x0000000100015ae3, where = Sketch`main + 33 at /Projects/Sketch/SKTMain.m:11 + frame #10: 0x0000000100000f20, where = Sketch`start + 52 + +You can also provide a list of threads to backtrace, or the keyword "all" to see all threads: + +:: + + (lldb) thread backtrace all + +You can select the current thread, which will be used by default in all the +commands in the next section, with the "thread select" command: + +:: + + (lldb) thread select 2 + +where the thread index is just the one shown in the "thread list" listing. + + +Examining Stack Frame State +--------------------------- + +The most convenient way to inspect a frame's arguments and local variables is +to use the "frame variable" command: + +:: + + (lldb) frame variable + self = (SKTGraphicView *) 0x0000000100208b40 + _cmd = (struct objc_selector *) 0x000000010001bae1 + sender = (id) 0x00000001001264e0 + selection = (NSArray *) 0x00000001001264e0 + i = (NSUInteger) 0x00000001001264e0 + c = (NSUInteger) 0x00000001001253b0 + +As you see above, if you don't specify any variable names, all arguments and +locals will be shown. If you call "frame variable" passing in the names of a +particular local(s), only those variables will be printed. For instance: + +:: + + (lldb) frame variable self + (SKTGraphicView *) self = 0x0000000100208b40 + +You can also pass in a path to some subelement of one of the available locals, +and that sub-element will be printed. For instance: + +:: + + (lldb) frame variable self.isa + (struct objc_class *) self.isa = 0x0000000100023730 + +The "frame variable" command is not a full expression parser but it does +support a few simple operations like ``&``, ``*``, ``->``, ``[]`` (no +overloaded operators). The array brackets can be used on pointers to treat +pointers as arrays: + +:: + + (lldb) frame variable *self + (SKTGraphicView *) self = 0x0000000100208b40 + (NSView) NSView = { + (NSResponder) NSResponder = { + ... + + (lldb) frame variable &self + (SKTGraphicView **) &self = 0x0000000100304ab + + (lldb) frame variable argv[0] + (char const *) argv[0] = 0x00007fff5fbffaf8 "/Projects/Sketch/build/Debug/Sketch.app/Contents/MacOS/Sketch" + +The frame variable command will also perform "object printing" operations on +variables (currently we only support ObjC printing, using the object's +"description" method. Turn this on by passing the -o flag to frame variable: + +:: + + (lldb) frame variable -o self (SKTGraphicView *) self = 0x0000000100208b40 + You can select another frame to view with the "frame select" command + + (lldb) frame select 9 + frame #9: 0x0000000100015ae3, where = Sketch`function1 + 33 at /Projects/Sketch/SKTFunctions.m:11 + +You can also move up and down the stack by passing the "--relative" ("-r") option. And we have built-in aliases "u" and "d" which behave like their gdb equivalents.