Author: Jonas Devlieghere Date: 2023-08-18T11:20:20-07:00 New Revision: 3e3880e370c8aed629750fe94a9f98f4cb6160cc
URL: https://github.com/llvm/llvm-project/commit/3e3880e370c8aed629750fe94a9f98f4cb6160cc DIFF: https://github.com/llvm/llvm-project/commit/3e3880e370c8aed629750fe94a9f98f4cb6160cc.diff LOG: [lldb] Simplify the LLDB website structure Feedback I hear regularly is that the LLDB website is hard to navigate. This patch is an attempt to simplify things by breaking the website up in 3 major areas: "Using LLDB", "Scripting LLDB" and "Developing LLDB". - The majority of the "project" pages were eliminated. The projects page was moved under "Developing LLDB". The releases page was replaced with a link under "External links". The other pages (goals, features and status) were pretty outdated and while they probably made sense in the past, they don't feel all that relevant anymore now that LLDB is an established debugger. - "USE & EXTENSION" was renamed to "Using LLDB". Besides that, this section remained mostly unchanged. The exception are the Python pages which were moved under "Scripting LLDB". - "Development" was renamed to "Developing LLDB" and now houses all the resources for LLDB developers. The old "Design" section (which only contained two pages) was moved back under here too. Differential revision: https://reviews.llvm.org/D158023 Added: lldb/docs/resources/extensions.rst lldb/docs/resources/overview.rst lldb/docs/resources/projects.rst lldb/docs/resources/sbapi.rst Modified: lldb/docs/.htaccess lldb/docs/index.rst lldb/docs/resources/fuzzing.rst Removed: lldb/docs/design/overview.rst lldb/docs/design/sbapi.rst lldb/docs/status/features.rst lldb/docs/status/goals.rst lldb/docs/status/projects.rst lldb/docs/status/releases.rst lldb/docs/status/status.rst lldb/docs/use/extensions.rst ################################################################################ diff --git a/lldb/docs/.htaccess b/lldb/docs/.htaccess index 91b25fb504f106..194c9ddc288828 100644 --- a/lldb/docs/.htaccess +++ b/lldb/docs/.htaccess @@ -15,9 +15,10 @@ Redirect 301 /varformats.html https://lldb.llvm.org/use/variable.html Redirect 301 /resources/source.html https://lldb.llvm.org/resources/contributing.html Redirect 301 /resources/download.html https://lldb.llvm.org/status/releases.html Redirect 301 /use/architecture.html https://lldb.llvm.org/resources/architecture.html -Redirect 301 /resources/architecture.html https://lldb.llvm.org/design/overview.html -Redirect 301 /resources/reproducers.html https://lldb.llvm.org/design/reproducers.html -Redirect 301 /resources/sbapi.html https://lldb.llvm.org/design/sbapi.html +Redirect 301 /resources/architecture.html https://lldb.llvm.org/resources/overview.html +Redirect 301 /design/sbapi.html https://lldb.llvm.org/resources/sbapi.html +Redirect 301 /design/overview.html https://lldb.llvm.org/resources/overview.html +Redirect 301 /use/extensions.html https://lldb.llvm.org/resources/extensions.html # Redirect old Python API to new Python API. Redirect 301 /python_reference/lldb-module.html https://lldb.llvm.org/python_api.html diff --git a/lldb/docs/index.rst b/lldb/docs/index.rst index ad09129ee32b37..8d6f68f13e27c5 100644 --- a/lldb/docs/index.rst +++ b/lldb/docs/index.rst @@ -107,24 +107,13 @@ messages are automatically sent to the `lldb-commits <http://lists.llvm.org/mailman/listinfo/lldb-commits>`__ mailing list, and this is also the preferred mailing list for patch submissions. -See the :doc:`Projects page <status/projects>` if you are looking for some +See the :doc:`Projects page <resources/projects>` if you are looking for some interesting areas to contribute to lldb. .. toctree:: :hidden: :maxdepth: 1 - :caption: Project - - status/goals - status/features - status/status - status/projects - status/releases - -.. toctree:: - :hidden: - :maxdepth: 1 - :caption: Use & Extension + :caption: Using LLDB use/tutorial use/map @@ -132,46 +121,41 @@ interesting areas to contribute to lldb. use/variable use/symbolication use/symbols - use/extensions - use/python - use/python-reference use/remote use/qemu-testing use/intel_pt use/ondemand use/troubleshooting use/links + Man Page <man/lldb> .. toctree:: :hidden: :maxdepth: 1 - :caption: Development - - resources/contributing - resources/build - resources/test - resources/fuzzing - resources/bots - resources/caveats - + :caption: Scripting LLDB -.. toctree:: - :hidden: - :maxdepth: 1 - :caption: Design + use/python + use/python-reference + Python API <python_api> - design/overview - design/sbapi .. toctree:: :hidden: :maxdepth: 1 - :caption: Reference + :caption: Developing LLDB - Public Python API <python_api> + resources/overview + resources/contributing + resources/build + resources/test + resources/fuzzing + resources/bots + resources/sbapi + resources/extensions + resources/caveats + resources/projects Public C++ API <https://lldb.llvm.org/cpp_reference/namespacelldb.html> Private C++ API <https://lldb.llvm.org/cpp_reference/index.html> - Man Page <man/lldb> .. toctree:: :hidden: @@ -179,5 +163,6 @@ interesting areas to contribute to lldb. :caption: External Links Source Code <https://github.com/llvm/llvm-project> + Releases <https://github.com/llvm/llvm-project/releases> Code Reviews <https://reviews.llvm.org> Bug Reports <https://github.com/llvm/llvm-project/issues/labels/lldb/> diff --git a/lldb/docs/use/extensions.rst b/lldb/docs/resources/extensions.rst similarity index 100% rename from lldb/docs/use/extensions.rst rename to lldb/docs/resources/extensions.rst diff --git a/lldb/docs/resources/fuzzing.rst b/lldb/docs/resources/fuzzing.rst index b827b32e74d50f..b236f08ae1c8e8 100644 --- a/lldb/docs/resources/fuzzing.rst +++ b/lldb/docs/resources/fuzzing.rst @@ -1,5 +1,5 @@ -Fuzzing LLDB -============ +Fuzzing +======= Overview -------- diff --git a/lldb/docs/design/overview.rst b/lldb/docs/resources/overview.rst similarity index 100% rename from lldb/docs/design/overview.rst rename to lldb/docs/resources/overview.rst diff --git a/lldb/docs/status/projects.rst b/lldb/docs/resources/projects.rst similarity index 100% rename from lldb/docs/status/projects.rst rename to lldb/docs/resources/projects.rst diff --git a/lldb/docs/design/sbapi.rst b/lldb/docs/resources/sbapi.rst similarity index 100% rename from lldb/docs/design/sbapi.rst rename to lldb/docs/resources/sbapi.rst diff --git a/lldb/docs/status/features.rst b/lldb/docs/status/features.rst deleted file mode 100644 index 2ce581f3f282f4..00000000000000 --- a/lldb/docs/status/features.rst +++ /dev/null @@ -1,18 +0,0 @@ -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 diff erent 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 macOS debugging on i386 and x86-64. -* A command line debugger - the lldb executable itself. -* A framework API to the library. diff --git a/lldb/docs/status/goals.rst b/lldb/docs/status/goals.rst deleted file mode 100644 index c5c236c5a46071..00000000000000 --- a/lldb/docs/status/goals.rst +++ /dev/null @@ -1,44 +0,0 @@ -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 - -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. - diff --git a/lldb/docs/status/releases.rst b/lldb/docs/status/releases.rst deleted file mode 100644 index 250d656c0b83d2..00000000000000 --- a/lldb/docs/status/releases.rst +++ /dev/null @@ -1,14 +0,0 @@ -Releases -======== - -Nightly Builds --------------- - -Nightly builds of LLDB are packaged and tested from trunk: - -Debian and Ubuntu: https://apt.llvm.org - -Releases --------- - -LLDB is packaged in most of the Debian & Ubuntu releases and in pkgsrc (NetBSD). diff --git a/lldb/docs/status/status.rst b/lldb/docs/status/status.rst deleted file mode 100644 index a046c0cf8cae62..00000000000000 --- a/lldb/docs/status/status.rst +++ /dev/null @@ -1,68 +0,0 @@ -Status -====== - -FreeBSD -------- - -LLDB on FreeBSD lags behind the Linux implementation but is improving rapidly. -For more details, see the Features by OS section below. - -Linux ------ - -LLDB is improving on Linux. Linux is nearing feature completeness with Darwin -to debug x86_64, i386, ARM, AArch64, IBM POWER (ppc64), and IBM Z (s390x) -programs. For more details, see the Features by OS section below. - -macOS ------ - -LLDB is the system debugger on macOS, iOS, tvOS, and watchOS and -can be used for C, C++, Objective-C and Swift development for x86_64, -i386, ARM, and AArch64 debugging. The entire public API is exposed -through a macOS framework which is used by Xcode and the `lldb` -command line tool. It can also be imported from 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. - -NetBSD ------- - -LLDB is improving on NetBSD and reaching feature completeness with Linux. - -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 | macOS | NetBSD | Windows | -+=======================+====================+=========================+===================+====================+======================+ -| Backtracing | YES | YES | YES | YES | YES | -+-----------------------+--------------------+-------------------------+-------------------+--------------------+----------------------+ -| Breakpoints | YES | YES | YES | YES | YES | -+-----------------------+--------------------+-------------------------+-------------------+--------------------+----------------------+ -| C++11: | YES | YES | YES | YES | Unknown | -+-----------------------+--------------------+-------------------------+-------------------+--------------------+----------------------+ -| Commandline tool | YES | YES | YES | YES | YES | -+-----------------------+--------------------+-------------------------+-------------------+--------------------+----------------------+ -| Core file debugging | YES (ELF) | YES (ELF) | YES (MachO) | YES (ELF) | YES (Minidump) | -+-----------------------+--------------------+-------------------------+-------------------+--------------------+----------------------+ -| Remote debugging | YES (lldb-server) | YES (lldb-server) | YES (debugserver) | YES (lldb-server) | NO | -+-----------------------+--------------------+-------------------------+-------------------+--------------------+----------------------+ -| Disassembly | YES | YES | YES | YES | YES | -+-----------------------+--------------------+-------------------------+-------------------+--------------------+----------------------+ -| Expression evaluation | YES (known issues) | YES (known issues) | YES | YES (known issues) | YES (known issues) | -+-----------------------+--------------------+-------------------------+-------------------+--------------------+----------------------+ -| JIT debugging | Unknown | Symbolic debugging only | Untested | Work In Progress | NO | -+-----------------------+--------------------+-------------------------+-------------------+--------------------+----------------------+ -| Objective-C 2.0: | Unknown | N/A | YES | Unknown | N/A | -+-----------------------+--------------------+-------------------------+-------------------+--------------------+----------------------+ _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits