Index: docs/CMakeLists.txt =================================================================== --- docs/CMakeLists.txt +++ docs/CMakeLists.txt @@ -58,6 +58,11 @@ if (SPHINX_FOUND) if (${SPHINX_OUTPUT_HTML}) add_sphinx_target(html lldb) + # Sphinx does not reliably update the custom CSS files, so force + # a clean rebuild of the documentation every time. + add_custom_target(clean-lldb-html COMMAND "${CMAKE_COMMAND}" -E + remove_directory ${CMAKE_CURRENT_BINARY_DIR}/html) + add_dependencies(docs-lldb-html clean-lldb-html) endif() endif() endif() Index: docs/_static/lldb.css =================================================================== --- docs/_static/lldb.css +++ docs/_static/lldb.css @@ -1,3 +1,15 @@ +pre { + padding: 7px; +} + +div.document { + width: 90%; +} + +div.body { + max-width: 90%; +} + table.mapping { width: 100%; } @@ -9,14 +21,14 @@ table.mapping td.hed { background: #606060; - color: white; + color: #fefefe; text-align: left; - border-bottom: 2px #fff solid; + border-bottom: 2px #fefefe solid; font-weight: bold; } table.mapping td.header { - background: #eee; + background: #eeeeee; } table.mapping td.content { @@ -24,3 +36,51 @@ padding-bottom: 15px; } +div.sphinxsidebar .caption { + font-family: Helvetica, Verdana, sans-serif; + font-size: 10pt; + font-weight:bold; + color: #fefefe; + background: #606060; + margin-bottom: 0; + text-transform: uppercase; + padding: 7px; +} + +div.sphinxsidebar a, +div.sphinxsidebar a:hover { + border: none; +} + +div.sphinxsidebar li { + padding-left:5px; + padding-right:5px; + border-bottom:1px solid #fefefe; +} + +div.sphinxsidebar li:hover { + background: #eeeeee; +} + +div.sphinxsidebar ul { + background: #e9e9e9; + margin: 0px; + padding: 0px; +} + +div.sphinxsidebar ul a { + font-family: Helvetica, Verdana, sans-serif; + font-size: 8pt; + display: block; + padding: 5px 0; + line-height: 14pt; +} + +div.sphinxsidebar ul li.toctree-l1 > a { + font-size: 100%; +} + +div.sphinxsidebar h3 { + /* Hide Navigation. */ + display: none; +} Index: docs/conf.py =================================================================== --- docs/conf.py +++ docs/conf.py @@ -92,12 +92,14 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'haiku' +html_theme = 'alabaster' # 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 = {} +html_theme_options = { + 'font_size': '11pt' +} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] Index: docs/index.rst =================================================================== --- docs/index.rst +++ docs/index.rst @@ -16,24 +16,105 @@ `LLVM License `__, an open source "BSD-style" license. +Why a New Debugger? +------------------- -Goals & Status -============== +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 macOS 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: + +* macOS 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. .. toctree:: + :hidden: :maxdepth: 1 + :caption: Goals & Status - status/about status/goals status/features status/status status/projects -Use & Extension -=============== - .. toctree:: + :hidden: :maxdepth: 1 + :caption: Use & Extension use/tutorial use/map @@ -47,11 +128,10 @@ use/troubleshooting use/architecture -Resources -========= - .. toctree:: + :hidden: :maxdepth: 1 + :caption: Resources resources/download resources/source @@ -60,16 +140,20 @@ resources/bots resources/sbapi -API Documentation -================= +.. toctree:: + :hidden: + :maxdepth: 1 + :caption: API Documentation + + Public Python API Reference + Public C++ API Reference + Private C++ Reference + +.. toctree:: + :hidden: + :maxdepth: 1 + :caption: External Links -* `Public Python API Reference `_ -* `Public C++ API Reference `_ -* `Private C++ Reference `_ - -External Links -============== - -* `Source Code `_ -* `Code Reviews `_ -* `Bug Reports `_ + Source Code + Code Reviews + Bug Reports Index: docs/status/about.rst =================================================================== --- docs/status/about.rst +++ docs/status/about.rst @@ -1,90 +0,0 @@ -About -===== - -.. contents:: - :local: - -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 macOS 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: - -* macOS 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/use/formatting.rst =================================================================== --- docs/use/formatting.rst +++ docs/use/formatting.rst @@ -1,5 +1,5 @@ -Stack Frame and Thread Format -============================= +Frame and Thread Format +======================= .. contents:: :local: