opencode.siil.arti.ee/llvm-tms34010
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[lldb][docs] Convert simple RST pages to Markdown (NFC) (#201256)

Browse Source 
Convert nine short, low-risk RST docs to MyST Markdown as the first
batch of an incremental RST -> Markdown migration. Subsequent batches
will cover the rest.

Verified by building the docs on origin/main and on this branch with
identical sphinx flags and diffing the rendered HTML. Seven of nine
pages are byte-identical.

contributing.html differs in 42 lines, all attributable to `{doc}` xrefs
replacing RST hyperlinks to sibling pages (`reference external` ->
`reference internal`) and CommonMark collapsing two-spaces-after- period
to one.

ondemand.html differs in 26 lines because two bulleted lists that
followed a paragraph with no blank-line separator originally rendered as
literal `- ...` text in both RST and Markdown. The conversion tool
preserved that by emitting `\-`; this patch instead inserts a blank line
so they render as proper `<ul>` lists, fixing a latent doc bug.

Context:
https://discourse.llvm.org/t/rfc-make-myst-markdown-the-llvm-docs-format-rip-rest/

Assisted-by: Claude
This commit is contained in:
Jonas Devlieghere authored and GitHub committed 2026-06-03 11:08:56 -07:00
1 parent 09020f9d68
commit e43adaea1f
14 files changed
+439 -484
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

lldb/docs/python_api.md
+15
View File
@@ -0,0 +1,15 @@
# LLDB Python API
% The long list of "skip" filters out several global functions that are
% generated by SWIG (but which are not useful as they are only the
% backend for their respective static functions in the classes).
```{eval-rst}
.. automodapi:: lldb
:no-inheritance-diagram:
:skip: command
:skip: declaration
:skip: in_range
:skip: is_numeric_type
:skip: lldb_iter
```
lldb/docs/python_api.rst
-14
View File
@@ -1,14 +0,0 @@
LLDB Python API
================================
..
The long list of "skip" filters out several global functions that are
generated by SWIG (but which are not useful as they are only the
backend for their respective static functions in the classes).
.. automodapi:: lldb
:no-inheritance-diagram:
:skip: command
:skip: declaration
:skip: in_range
:skip: is_numeric_type
:skip: lldb_iter
lldb/docs/python_extensions.rst → lldb/docs/python_extensions.md
+16 -13
View File
@@ -1,47 +1,50 @@
Python Extensions
=================
# Python Extensions
LLDB provides scriptable extensions to augment the debugger's capabilities.
This gives users the ability to tailor their debugging experience to their own needs.
This page describes some of these scripting extensions:
Operating System Thread Plugins
-------------------------------
## Operating System Thread Plugins
```{eval-rst}
.. automodapi:: lldb.plugins.operating_system
:no-heading:
:skip: ScriptedThread
:no-inheritance-diagram:
```
Scripted Frame Provider Plugins
-------------------------------
## Scripted Frame Provider Plugins
```{eval-rst}
.. automodapi:: lldb.plugins.scripted_frame_provider
:no-heading:
:skip: ABCMeta
:no-inheritance-diagram:
```
Scripted Process Plugins
-------------------------------
## Scripted Process Plugins
```{eval-rst}
.. automodapi:: lldb.plugins.scripted_process
:no-heading:
:skip: ABCMeta
:no-inheritance-diagram:
```
Scripted Platform Plugins
-------------------------------
## Scripted Platform Plugins
```{eval-rst}
.. automodapi:: lldb.plugins.scripted_platform
:no-heading:
:skip: ABCMeta
:no-inheritance-diagram:
```
Scripted Thread Plan Plugins
-------------------------------
## Scripted Thread Plan Plugins
```{eval-rst}
.. automodapi:: lldb.plugins.scripted_thread_plan
:no-heading:
:no-inheritance-diagram:
```
lldb/docs/resources/caveats.md
+63
View File
@@ -0,0 +1,63 @@
# Caveats
(python_caveat)=
## Python
LLDB has a powerful scripting interface which is accessible through Python.
Python is available either from within LLDB through a (interactive) script
interpreter, or as a Python module which you can import from the Python
interpreter.
To make this possible, LLDB links against the Python shared library. Linking
against Python comes with some constraints to be aware of.
1. It is not possible to build and link LLDB against a Python 3 library and
use it from Python 2 and vice versa.
2. It is not possible to build and link LLDB against one distribution on
Python and use it through an interpreter coming from another distribution.
For example, on macOS, if you build and link against Python from
python.org, you cannot import the lldb module from the Python interpreter
installed with Homebrew.
3. To use third party Python packages from inside LLDB, you need to install
them using a utility (such as `pip`) from the same Python distribution as
the one used to build and link LLDB.
The previous considerations are especially important during development, but
apply to binary distributions of LLDB as well.
### LLDB in Xcode on macOS
Users of lldb in Xcode on macOS commonly run into these issues when they
install Python, often unknowingly as a dependency pulled in by Homebrew or
other package managers. The problem is the symlinks that get created in
`/usr/local/bin`, which comes before `/usr/bin` in your path. You can use
`which python3` to check to what it resolves.
To be sure you use the Python that matches with the lldb in Xcode use `xcrun`
or use the absolute path to the shims in `/usr/bin`.
```
$ xcrun python3
$ /usr/bin/python3
```
Similarly, to install packages and be able to use them from within lldb, you'll
need to install them with the matching `pip3`.
```
$ xcrun pip3
$ /usr/bin/pip3
```
The same is true for Python 2. Although Python 2 comes with the operating
system rather than Xcode, you can still use `xcrun` to launch the system
variant.
```
$ xcrun python
$ /usr/bin/python
```
Keep in mind that Python 2 is deprecated and no longer maintained. Future
versions of macOS will not include Python 2.7.
lldb/docs/resources/caveats.rst
-68
View File
@@ -1,68 +0,0 @@
Caveats
=======
.. _python_caveat:
Python
------
LLDB has a powerful scripting interface which is accessible through Python.
Python is available either from within LLDB through a (interactive) script
interpreter, or as a Python module which you can import from the Python
interpreter.
To make this possible, LLDB links against the Python shared library. Linking
against Python comes with some constraints to be aware of.
1. It is not possible to build and link LLDB against a Python 3 library and
use it from Python 2 and vice versa.
2. It is not possible to build and link LLDB against one distribution on
Python and use it through an interpreter coming from another distribution.
For example, on macOS, if you build and link against Python from
python.org, you cannot import the lldb module from the Python interpreter
installed with Homebrew.
3. To use third party Python packages from inside LLDB, you need to install
them using a utility (such as ``pip``) from the same Python distribution as
the one used to build and link LLDB.
The previous considerations are especially important during development, but
apply to binary distributions of LLDB as well.
LLDB in Xcode on macOS
``````````````````````
Users of lldb in Xcode on macOS commonly run into these issues when they
install Python, often unknowingly as a dependency pulled in by Homebrew or
other package managers. The problem is the symlinks that get created in
``/usr/local/bin``, which comes before ``/usr/bin`` in your path. You can use
``which python3`` to check to what it resolves.
To be sure you use the Python that matches with the lldb in Xcode use ``xcrun``
or use the absolute path to the shims in ``/usr/bin``.
::
$ xcrun python3
$ /usr/bin/python3
Similarly, to install packages and be able to use them from within lldb, you'll
need to install them with the matching ``pip3``.
::
$ xcrun pip3
$ /usr/bin/pip3
The same is true for Python 2. Although Python 2 comes with the operating
system rather than Xcode, you can still use ``xcrun`` to launch the system
variant.
::
$ xcrun python
$ /usr/bin/python
Keep in mind that Python 2 is deprecated and no longer maintained. Future
versions of macOS will not include Python 2.7.
lldb/docs/resources/contributing.rst → lldb/docs/resources/contributing.md
+47 -64
View File
@@ -1,64 +1,53 @@
Contributing
============
# Contributing
Getting Started
---------------
## Getting Started
Please refer to the `LLVM Getting Started Guide
<https://llvm.org/docs/GettingStarted.html>`_ for general information on how to
Please refer to the [LLVM Getting Started Guide](https://llvm.org/docs/GettingStarted.html) for general information on how to
get started on the LLVM project. A detailed explanation on how to build and
test LLDB can be found in the `build instructions <build.html>`_ and `test
instructions <test.html>`_ respectively.
test LLDB can be found in the {doc}`build instructions <build>` and
{doc}`test instructions <test>` respectively.
Contributing to LLDB
--------------------
## Contributing to LLDB
Please refer to the `LLVM Developer Policy
<https://llvm.org/docs/DeveloperPolicy.html>`_ for information about
Please refer to the [LLVM Developer Policy](https://llvm.org/docs/DeveloperPolicy.html) for information about
authoring and uploading a patch. LLDB differs from the LLVM Developer
Policy in the following respects.
For anything not explicitly listed here, assume that LLDB follows the LLVM
policy.
Coding Style
++++++++++++
### Coding Style
LLDB's code style differs from `LLVM's coding style <https://llvm.org/docs/CodingStandards.html>`_
LLDB's code style differs from [LLVM's coding style](https://llvm.org/docs/CodingStandards.html)
in a few ways. The 2 main ones are:
* `Variable and function naming <https://llvm.org/docs/CodingStandards.html#name-types-functions-variables-and-enumerators-properly>`_:
- [Variable and function naming](https://llvm.org/docs/CodingStandards.html#name-types-functions-variables-and-enumerators-properly):
* Variables are ``snake_case``.
* Functions and methods are ``UpperCamelCase``.
* Static, global and member variables have ``s_``, ``g_`` and ``m_``
- Variables are `snake_case`.
- Functions and methods are `UpperCamelCase`.
- Static, global and member variables have `s_`, `g_` and `m_`
prefixes respectively.
* `Use of asserts <https://llvm.org/docs/CodingStandards.html#assert-liberally>`_:
See the :ref:`section below<Error Handling>`.
- [Use of asserts](https://llvm.org/docs/CodingStandards.html#assert-liberally):
See the {ref}`section below<error-handling>`.
For any other contradictions, consider the
`golden rule <https://llvm.org/docs/CodingStandards.html#introduction>`_
[golden rule](https://llvm.org/docs/CodingStandards.html#introduction)
before choosing to update the style of existing code.
All new code in LLDB should be formatted with clang-format. Existing code may
not conform and should be updated prior to being modified. Bulk reformatting
is discouraged.
Test Infrastructure
+++++++++++++++++++
### Test Infrastructure
Like LLVM it is important to submit tests with your patches, but note that a
Like LLVM it is important to submit tests with your patches, but note that a
subset of LLDB tests (the API tests) use a different system. Refer to the
`test documentation <test.html>`_ for more details and the
`lldb/test <https://github.com/llvm/llvm-project/tree/main/lldb/test>`_ folder
{doc}`test documentation <test>` for more details and the
[lldb/test](https://github.com/llvm/llvm-project/tree/main/lldb/test) folder
for examples.
LLDB plugins and their dependencies
-----------------------------------
## LLDB plugins and their dependencies
LLDB has a concept of *plugins*, which are used to provide abstraction
boundaries over functionality that is specific to a certain architecture,
@@ -89,27 +78,25 @@ In cases such as these, direct dependencies are acceptable. However, to keep the
dependency graph manageable, we still have some rules to govern these
relationships:
* All dependencies between plugins of the same kind must flow in the same
direction (if plugin ``A1`` depends on plugin ``B1``, then ``B2`` must not depend on
``A2``)
* Dependency graph of plugin kinds must not contain loops (dependencies like
``A1->B1``, ``B2->C2`` and ``C3->A3`` are forbidden because they induce a cycle in
- All dependencies between plugins of the same kind must flow in the same
direction (if plugin `A1` depends on plugin `B1`, then `B2` must not depend on
`A2`)
- Dependency graph of plugin kinds must not contain loops (dependencies like
`A1->B1`, `B2->C2` and `C3->A3` are forbidden because they induce a cycle in
the plugin kind graph even though the plugins themselves are acyclical)
The first of these rules is checked via CMake scripts (using the
``LLDB_ACCEPTABLE_PLUGIN_DEPENDENCIES`` property). Dependencies in this category
`LLDB_ACCEPTABLE_PLUGIN_DEPENDENCIES` property). Dependencies in this category
are expected and permitted (subject to other constraints such as that dependency
making sense for the particular pair of plugins). Unfortunately, due to historic
reasons, not all plugin dependencies follow this rule, which is why we have
another category called ``LLDB_TOLERATED_PLUGIN_DEPENDENCIES``. New dependencies
another category called `LLDB_TOLERATED_PLUGIN_DEPENDENCIES`. New dependencies
are forbidden (even though they are accepted by CMake) and existing ones should
be removed wherever possible.
.. _Error handling:
(error-handling)=
Error handling and use of assertions in LLDB
--------------------------------------------
## Error handling and use of assertions in LLDB
Contrary to Clang, which is typically a short-lived process, LLDB
debuggers stay up and running for a long time, often serving multiple
@@ -117,45 +104,41 @@ debug sessions initiated by an IDE. For this reason LLDB code needs to
be extra thoughtful about how to handle errors. Below are a couple
rules of thumb:
* Invalid input. To deal with invalid input, such as malformed DWARF,
- Invalid input. To deal with invalid input, such as malformed DWARF,
missing object files, or otherwise inconsistent debug info,
error handling types such as `llvm::Expected<T>
<https://llvm.org/doxygen/classllvm_1_1Expected.html>`_ or
``std::optional<T>`` should be used. Functions that may fail
error handling types such as [llvm::Expected\<T>](https://llvm.org/doxygen/classllvm_1_1Expected.html) or
`std::optional<T>` should be used. Functions that may fail
should return their result using these wrapper types instead of
using a bool to indicate success. Returning a default value when an
error occurred is also discouraged.
* Assertions. Assertions (from ``assert.h``) should be used liberally
to assert internal consistency. Assertions shall **never** be
used to detect invalid user input, such as malformed DWARF. An
- Assertions. Assertions (from `assert.h`) should be used liberally
to assert internal consistency. Assertions shall **never** be
used to detect invalid user input, such as malformed DWARF. An
assertion should be placed to assert invariants that the developer
is convinced will always hold, regardless what an end-user does with
LLDB. Because assertions are not present in release builds, the
checks in an assertion may be more expensive than otherwise
permissible. In combination with the LLDB test suite, assertions are
what allows us to refactor and evolve the LLDB code base.
* Logging. LLDB provides a very rich logging API. When recoverable
- Logging. LLDB provides a very rich logging API. When recoverable
errors cannot reasonably be surfaced to the end user, the error may
be written to a topical log channel.
* Soft assertions. LLDB provides ``lldbassert()`` as a soft
- Soft assertions. LLDB provides `lldbassert()` as a soft
alternative to cover the middle ground of situations that indicate a
recoverable bug in LLDB. When asserts are enabled ``lldbassert()``
behaves like ``assert()``. When asserts are disabled, it will print a
recoverable bug in LLDB. When asserts are enabled `lldbassert()`
behaves like `assert()`. When asserts are disabled, it will print a
warning and encourage the user to file a bug report, similar to
LLVM's crash handler, and then return execution. Use these sparingly
and only if error handling is not otherwise feasible.
.. note::
:::{note}
New code should not be using `lldbassert()` and existing uses should
be replaced by other means of error handling.
:::
New code should not be using ``lldbassert()`` and existing uses should
be replaced by other means of error handling.
* Fatal errors. Aborting LLDB's process using
``llvm::report_fatal_error()`` or ``abort()`` should be avoided at all
costs. It's acceptable to use ``llvm_unreachable()`` for actually
- Fatal errors. Aborting LLDB's process using
`llvm::report_fatal_error()` or `abort()` should be avoided at all
costs. It's acceptable to use `llvm_unreachable()` for actually
unreachable code such as the default in an otherwise exhaustive
switch statement.
lldb/docs/resources/fuzzing.md
+67
View File
@@ -0,0 +1,67 @@
# Fuzzing
## Overview
LLDB has fuzzers that provide automated [fuzz testing](https://en.wikipedia.org/wiki/Fuzzing) for different components of LLDB. The fuzzers are built with [libFuzzer](https://llvm.org/docs/LibFuzzer.html) . Currently, there are fuzzers for target creation, LLDB's command interpreter and LLDB's expression evaluator.
## Building the fuzzers
Building the LLDB fuzzers requires a build configuration that has the address sanitizer and sanitizer coverage enabled. In addition to your regular CMake arguments, you will need these arguments to build the fuzzers:
```
-DLLVM_USE_SANITIZER='Address' \
-DLLVM_USE_SANITIZE_COVERAGE=On \
-DCLANG_ENABLE_PROTO_FUZZER=ON
```
More information on libFuzzer's sanitizer coverage is available here: [https://llvm.org/docs/LibFuzzer.html#fuzzer-usage](https://llvm.org/docs/LibFuzzer.html#fuzzer-usage)
If you want to debug LLDB itself when you find a bug using the fuzzers, use the CMake option `-DCMAKE_BUILD_TYPE='RelWithDebInfo'`
To build a fuzzer, run the desired ninja command for the fuzzer(s) you want to build:
```
$ ninja lldb-target-fuzzer
$ ninja lldb-commandinterpreter-fuzzer
$ ninja lldb-expression-fuzzer
```
Once built, the binaries for the fuzzers will exist in the `bin` directory of your build folder.
## Continuous integration
Currently, there are plans to integrate the LLDB fuzzers into the [OSS Fuzz](https://github.com/google/oss-fuzz) project for continuous integration.
## Running the fuzzers
If you want to run the fuzzers locally, you can run the binaries that were generated with ninja from the build directory:
```
$ ./bin/lldb-target-fuzzer
$ ./bin/lldb-commandinterpreter-fuzzer
$ ./bin/lldb-expression-fuzzer
```
This will run the fuzzer binaries directly, and you can use the [libFuzzer options](https://llvm.org/docs/LibFuzzer.html#options) to customize how the fuzzers are run.
Another way to run the fuzzers is to use a ninja target that will both build the fuzzers and then run them immediately after. These custom targets run each fuzzer with command-line arguments that provide better fuzzing for the components being tested. Running the fuzzers this way will also create directories that will store any inputs that caused LLDB to crash, timeout or run out of memory. The directories are created for each fuzzer.
To run the custom ninja targets, run the command for your desired fuzzer:
```
$ ninja fuzz-lldb-target
$ ninja fuzz-lldb-commandinterpreter
$ ninja fuzz-lldb-expression
```
## Investigating and reproducing bugs
When the fuzzers find an input that causes LLDB to crash, timeout or run out of memory, the input is saved to a file in the build directory. When running the fuzzer binaries directly this input is stored in a file named `<crash/timeout/oom>-<hash>`.
When running the fuzzers using the custom ninja targets shown above, the inputs will be stored in `fuzzer-artifacts/<fuzzer name>-artifacts`, which is created in your build directory. The input files will have the name `<fuzzer name>-<crash/timeout/oom>-<hash>`.
If you want to reproduce the issue found by a fuzzer once you have gotten the input, you can pass the individual input to the fuzzer binary as a command-line argument:
```
$ ./<fuzzer binary> <input you are investigating>
```
lldb/docs/resources/fuzzing.rst
-73
View File
@@ -1,73 +0,0 @@
Fuzzing
=======
Overview
--------
LLDB has fuzzers that provide automated `fuzz testing <https://en.wikipedia.org/wiki/Fuzzing>`_ for different components of LLDB. The fuzzers are built with `libFuzzer <https://llvm.org/docs/LibFuzzer.html>`_ . Currently, there are fuzzers for target creation, LLDB's command interpreter and LLDB's expression evaluator.
Building the fuzzers
--------------------
Building the LLDB fuzzers requires a build configuration that has the address sanitizer and sanitizer coverage enabled. In addition to your regular CMake arguments, you will need these arguments to build the fuzzers:
::
-DLLVM_USE_SANITIZER='Address' \
-DLLVM_USE_SANITIZE_COVERAGE=On \
-DCLANG_ENABLE_PROTO_FUZZER=ON
More information on libFuzzer's sanitizer coverage is available here: `<https://llvm.org/docs/LibFuzzer.html#fuzzer-usage>`_
If you want to debug LLDB itself when you find a bug using the fuzzers, use the CMake option ``-DCMAKE_BUILD_TYPE='RelWithDebInfo'``
To build a fuzzer, run the desired ninja command for the fuzzer(s) you want to build:
::
$ ninja lldb-target-fuzzer
$ ninja lldb-commandinterpreter-fuzzer
$ ninja lldb-expression-fuzzer
Once built, the binaries for the fuzzers will exist in the ``bin`` directory of your build folder.
Continuous integration
----------------------
Currently, there are plans to integrate the LLDB fuzzers into the `OSS Fuzz <https://github.com/google/oss-fuzz>`_ project for continuous integration.
Running the fuzzers
-------------------
If you want to run the fuzzers locally, you can run the binaries that were generated with ninja from the build directory:
::
$ ./bin/lldb-target-fuzzer
$ ./bin/lldb-commandinterpreter-fuzzer
$ ./bin/lldb-expression-fuzzer
This will run the fuzzer binaries directly, and you can use the `libFuzzer options <https://llvm.org/docs/LibFuzzer.html#options>`_ to customize how the fuzzers are run.
Another way to run the fuzzers is to use a ninja target that will both build the fuzzers and then run them immediately after. These custom targets run each fuzzer with command-line arguments that provide better fuzzing for the components being tested. Running the fuzzers this way will also create directories that will store any inputs that caused LLDB to crash, timeout or run out of memory. The directories are created for each fuzzer.
To run the custom ninja targets, run the command for your desired fuzzer:
::
$ ninja fuzz-lldb-target
$ ninja fuzz-lldb-commandinterpreter
$ ninja fuzz-lldb-expression
Investigating and reproducing bugs
----------------------------------
When the fuzzers find an input that causes LLDB to crash, timeout or run out of memory, the input is saved to a file in the build directory. When running the fuzzer binaries directly this input is stored in a file named ``<crash/timeout/oom>-<hash>``.
When running the fuzzers using the custom ninja targets shown above, the inputs will be stored in ``fuzzer-artifacts/<fuzzer name>-artifacts``, which is created in your build directory. The input files will have the name ``<fuzzer name>-<crash/timeout/oom>-<hash>``.
If you want to reproduce the issue found by a fuzzer once you have gotten the input, you can pass the individual input to the fuzzer binary as a command-line argument:
::
$ ./<fuzzer binary> <input you are investigating>
lldb/docs/use/links.md
+60
View File
@@ -0,0 +1,60 @@
# Links
This page contains links to external resources on how to use LLDB. Being
listed on this page is not an endorsement.
## Blog Posts
- [Dancing in the Debugger — A Waltz with LLDB (2014)](https://www.objc.io/issues/19-debugging/lldb-debugging/)
## Videos
### WWDC
- [Run, Break, Inspect: Explore effective debugging in LLDB (2024)](https://developer.apple.com/videos/play/wwdc2024/10198)
- [LLDB: Beyond “po” (2019)](https://developer.apple.com/videos/play/wwdc2019/429/)
- [Advanced Debugging with Xcode and LLDB (2018)](https://developer.apple.com/videos/play/wwdc2018/412/)
### LLVM Developers' Meeting Talks
- [2025 EuroLLVM - What is LLDB-DAP?](https://www.youtube.com/watch?v=sfJkf7U2FUg)
- [2025 US LLVM Developers' Meeting: LLDB MCP](https://www.youtube.com/watch?v=OJas4nknp0o)
- [2025 EuroLLVM - LLDB Statusline](https://www.youtube.com/watch?v=BQFwcsN1dJU)
- [2025 EuroLLVM - LLDB support for Propeller optimized code](https://www.youtube.com/watch?v=osE0UDJULoM)
- [2025 AsiaLLVM - The Data Inspection Language: Fast & Simple Expression Evaluation in LLDB](https://www.youtube.com/watch?v=tgsDbrQga_w)
- [2024 EuroLLVM - From C++ ranges to shorter template names: A C++ Debugging journey](https://www.youtube.com/watch?v=VT6-fL2hiN8)
- [2024 EuroLLVM - Simplifying, Consolidating & Documenting LLDB's Scripting Functionalities](https://www.youtube.com/watch?v=hNvFmZ1iB78)
- [2024 EuroLLVM - LLDB: What's in a Register?](https://www.youtube.com/watch?v=Hb7DbdIr3Rk)
- [2024 EuroLLVM - Mojo debugging: extending MLIR and LLDB](https://www.youtube.com/watch?v=9jfukpjCPIg)
- [2024 EuroLLVM - Debug information for macros](https://www.youtube.com/watch?v=WOkoAHTbsbM)
- [2024 LLVM Dev Mtg - MD5 Checksums in LLDB](https://www.youtube.com/watch?v=JIBhafjL_oo)
- [2024 LLVM Dev Mtg - "Hey, do you want a RISC-V debugger?" - Enabling RISC-V support in LLDB](https://www.youtube.com/watch?v=YSdeFLdL5DM)
- [2023 LLVM Dev Mtg - Seamless debugging of emulated applications with LLDB](https://www.youtube.com/watch?v=tW3jCrCBDRc)
- [2022 LLVM Dev Mtg: Interactive Crashlogs in LLDB](https://www.youtube.com/watch?v=iM2EH5EmoSY)
- [2021 LLVM Dev Mtg "lldb-eval fuzzer: Finding bugs in an LLDB-based expression evaluator"](https://www.youtube.com/watch?v=dJ9k7-pmwvM)
- [2021 LLVM Dev Mtg "Building a faster expression evaluator for LLDB"](https://www.youtube.com/watch?v=9aThSRGjYdA)
- [2020 LLVM Developers' Meeting: "Extending LLDB to More Scripting Languages"](https://www.youtube.com/watch?v=UgfzdAr9AFg)
- [2019 LLVM Developers' Meeting: R. Isemann "Better C++ debugging using Clang Modules in LLDB"](https://www.youtube.com/watch?v=vuNZLlHhy0k)
- [2019 EuroLLVM Developers' Meeting: J. Devlieghere "LLDB Reproducers"](https://www.youtube.com/watch?v=ygdzXnfyvbg)
- [2019 LLVM Developers' Meeting: S. Cook "A Unified Debug Server For Deeply Embedded Systems and LLDB"](https://www.youtube.com/watch?v=IMq3a_SSzFw)
- [2019 LLVM Developers' Meeting: S. Cook "State of LLDB and Deeply Embedded RISC-V"](https://www.youtube.com/watch?v=37ce7gVpgIE)
- [2016 EuroLLVM Developers' Meeting: L. Drummond & E. Crawford "Bringing RenderScript to LLDB"](https://www.youtube.com/watch?v=BBC61L0QKCM)
- [2016 EuroLLVM Developers' Meeting: D. Panickal & A. Warzynski "LLDB Tutorial: Adding debugger ..."](https://www.youtube.com/watch?v=9hhDZeV0fYU)
- [2013 LLVM Developers' Meeting: "Adapting LLDB for your hardware: Remote Debugging the Hexagon DSP"](https://www.youtube.com/watch?v=281sEoJYm8E)
### FOSDEM Talks
- [WebAssembly Debugging with LLDB](https://fosdem.org/2026/schedule/event/87ZLQV-wasm-debugging-lldb/)
- [Enhanced debuggability support in LLVM for various Fortran language features](https://archive.fosdem.org/2022/schedule/event/llvm_fortran_debug/)
- [Debugging with LLVM](https://archive.fosdem.org/2020/schedule/event/debugging_with_llvm/)
- [LLVM, Rust, and Debugging](https://archive.fosdem.org/2018/schedule/event/rustdebug/)
- [Porting LLDB to a new Target](https://archive.fosdem.org/2015/schedule/event/llvm_lldb_port/)
## Books
- [Advanced Apple Debugging & Reverse Engineering (2018)](https://www.raywenderlich.com/books/advanced-apple-debugging-reverse-engineering/)
## Extensions
- [facebook/chisel](https://github.com/facebook/chisel)
- [DerekSelander/LLDB](https://github.com/DerekSelander/LLDB)
lldb/docs/use/links.rst
-68
View File
@@ -1,68 +0,0 @@
Links
=====
This page contains links to external resources on how to use LLDB. Being
listed on this page is not an endorsement.
Blog Posts
----------
* `Dancing in the Debugger — A Waltz with LLDB (2014) <https://www.objc.io/issues/19-debugging/lldb-debugging/>`__
Videos
------
WWDC
~~~~
* `Run, Break, Inspect: Explore effective debugging in LLDB (2024) <https://developer.apple.com/videos/play/wwdc2024/10198>`__
* `LLDB: Beyond “po” (2019) <https://developer.apple.com/videos/play/wwdc2019/429/>`__
* `Advanced Debugging with Xcode and LLDB (2018) <https://developer.apple.com/videos/play/wwdc2018/412/>`__
LLVM Developers' Meeting Talks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* `2025 EuroLLVM - What is LLDB-DAP? <https://www.youtube.com/watch?v=sfJkf7U2FUg>`__
* `2025 US LLVM Developers' Meeting: LLDB MCP <https://www.youtube.com/watch?v=OJas4nknp0o>`__
* `2025 EuroLLVM - LLDB Statusline <https://www.youtube.com/watch?v=BQFwcsN1dJU>`__
* `2025 EuroLLVM - LLDB support for Propeller optimized code <https://www.youtube.com/watch?v=osE0UDJULoM>`__
* `2025 AsiaLLVM - The Data Inspection Language: Fast & Simple Expression Evaluation in LLDB <https://www.youtube.com/watch?v=tgsDbrQga_w>`__
* `2024 EuroLLVM - From C++ ranges to shorter template names: A C++ Debugging journey <https://www.youtube.com/watch?v=VT6-fL2hiN8>`__
* `2024 EuroLLVM - Simplifying, Consolidating & Documenting LLDB's Scripting Functionalities <https://www.youtube.com/watch?v=hNvFmZ1iB78>`__
* `2024 EuroLLVM - LLDB: What's in a Register? <https://www.youtube.com/watch?v=Hb7DbdIr3Rk>`__
* `2024 EuroLLVM - Mojo debugging: extending MLIR and LLDB <https://www.youtube.com/watch?v=9jfukpjCPIg>`__
* `2024 EuroLLVM - Debug information for macros <https://www.youtube.com/watch?v=WOkoAHTbsbM>`__
* `2024 LLVM Dev Mtg - MD5 Checksums in LLDB <https://www.youtube.com/watch?v=JIBhafjL_oo>`__
* `2024 LLVM Dev Mtg - "Hey, do you want a RISC-V debugger?" - Enabling RISC-V support in LLDB <https://www.youtube.com/watch?v=YSdeFLdL5DM>`__
* `2023 LLVM Dev Mtg - Seamless debugging of emulated applications with LLDB <https://www.youtube.com/watch?v=tW3jCrCBDRc>`__
* `2022 LLVM Dev Mtg: Interactive Crashlogs in LLDB <https://www.youtube.com/watch?v=iM2EH5EmoSY>`__
* `2021 LLVM Dev Mtg "lldb-eval fuzzer: Finding bugs in an LLDB-based expression evaluator" <https://www.youtube.com/watch?v=dJ9k7-pmwvM>`__
* `2021 LLVM Dev Mtg "Building a faster expression evaluator for LLDB" <https://www.youtube.com/watch?v=9aThSRGjYdA>`__
* `2020 LLVM Developers' Meeting: "Extending LLDB to More Scripting Languages" <https://www.youtube.com/watch?v=UgfzdAr9AFg>`__
* `2019 LLVM Developers' Meeting: R. Isemann "Better C++ debugging using Clang Modules in LLDB" <https://www.youtube.com/watch?v=vuNZLlHhy0k>`__
* `2019 EuroLLVM Developers' Meeting: J. Devlieghere "LLDB Reproducers" <https://www.youtube.com/watch?v=ygdzXnfyvbg>`__
* `2019 LLVM Developers' Meeting: S. Cook "A Unified Debug Server For Deeply Embedded Systems and LLDB" <https://www.youtube.com/watch?v=IMq3a_SSzFw>`__
* `2019 LLVM Developers' Meeting: S. Cook "State of LLDB and Deeply Embedded RISC-V" <https://www.youtube.com/watch?v=37ce7gVpgIE>`__
* `2016 EuroLLVM Developers' Meeting: L. Drummond & E. Crawford "Bringing RenderScript to LLDB" <https://www.youtube.com/watch?v=BBC61L0QKCM>`__
* `2016 EuroLLVM Developers' Meeting: D. Panickal & A. Warzynski "LLDB Tutorial: Adding debugger ..." <https://www.youtube.com/watch?v=9hhDZeV0fYU>`__
* `2013 LLVM Developers' Meeting: "Adapting LLDB for your hardware: Remote Debugging the Hexagon DSP" <https://www.youtube.com/watch?v=281sEoJYm8E>`__
FOSDEM Talks
~~~~~~~~~~~~
* `WebAssembly Debugging with LLDB <https://fosdem.org/2026/schedule/event/87ZLQV-wasm-debugging-lldb/>`__
* `Enhanced debuggability support in LLVM for various Fortran language features <https://archive.fosdem.org/2022/schedule/event/llvm_fortran_debug/>`__
* `Debugging with LLVM <https://archive.fosdem.org/2020/schedule/event/debugging_with_llvm/>`__
* `LLVM, Rust, and Debugging <https://archive.fosdem.org/2018/schedule/event/rustdebug/>`__
* `Porting LLDB to a new Target <https://archive.fosdem.org/2015/schedule/event/llvm_lldb_port/>`__
Books
-----
* `Advanced Apple Debugging & Reverse Engineering (2018) <https://www.raywenderlich.com/books/advanced-apple-debugging-reverse-engineering/>`__
Extensions
----------
* `facebook/chisel <https://github.com/facebook/chisel>`__
* `DerekSelander/LLDB <https://github.com/DerekSelander/LLDB>`__
lldb/docs/use/ondemand.rst → lldb/docs/use/ondemand.md
+14 -19
View File
@@ -1,5 +1,4 @@
On Demand Symbols
=================
# On Demand Symbols
On demand symbols can be enabled in LLDB for projects that generate debug info
for more than what is required by a normal debug session. Some build systems
@@ -11,8 +10,7 @@ be slow when types from all of the binaries have full debug info as each module
is queried for very common types, or global name lookups fail due to a mistyped
expression.
When should I consider enabling this feature?
---------------------------------------------
## When should I consider enabling this feature?
Anyone that has a build system that produces debug information for many
binaries that are not all required when you want to focus on debugging a few of
@@ -22,21 +20,18 @@ easy to modify to produce debug info for only a small subset of the files being
linked. If your debug session startup times are slow because of too much debug
info, this feature might help you be more productive during daily use.
How do I enable on demand symbols?
----------------------------------
## How do I enable on demand symbols?
This feature is enabled using a LLDB setting:
::
(lldb) settings set symbols.load-on-demand true
```
(lldb) settings set symbols.load-on-demand true
```
Users can also put this command into their ~/.lldbinit file so it is always
enabled.
How does this feature work?
---------------------------
## How does this feature work?
This feature works by selectively enabling debug information for modules that
the user focuses on. It is designed to be enabled and work without the user
@@ -47,6 +42,7 @@ lookups. The debug information for line tables are always left enabled to allow
users to reliably set breakpoints by file and line. As the user debugs their
target, some simple things can cause module to get its debug information
enabled (called hydration):
- Setting a file and line breakpoint
- Any PC from any stack frame that maps to a module
- Setting a breakpoint by function name
@@ -97,12 +93,12 @@ symbol tables with this features as static variables and other non exported
globals will not appear in the symbol table and can lead to matches not being
found.
What other things might fail?
-----------------------------
## What other things might fail?
The on demand symbol loading feature tries to limit expensive name lookups
within debug information. As such, some lookups by name might fail when they
wouldn't when this feature is not enabled:
- Setting breakpoints by function name for inlined functions
- Type lookups when the expression parser requests types by name
- Global variable lookups by name when the name of the variable is stripped
@@ -135,8 +131,7 @@ parser should have no problem finding your variables. Most global variables
that are exported will still be in your symbol table if it is stripped, but
static variables and non exported globals will not be.
Can I troubleshoot issues when I believe this feature is impeding my debugging?
-------------------------------------------------------------------------------
## Can I troubleshoot issues when I believe this feature is impeding my debugging?
Logging has been added that can be enabled to help notify our engineers when
something is not producing results when this feature is enabled. This logging
@@ -144,9 +139,9 @@ can be enabled during a debug session and can be sent to the LLDB engineers
to help troubleshoot these situation. To enable logging, type the following
command:
::
(lldb) log enable -f /tmp/ondemand.txt lldb on-demand
```
(lldb) log enable -f /tmp/ondemand.txt lldb on-demand
```
When the logging is enabled, we get full visibility into each query that would
have produced results if this feature were not enabled and will allow us to
lldb/docs/use/python-reference.rst → lldb/docs/use/python-reference.md
+15 -16
View File
@@ -1,5 +1,4 @@
Python Reference
================
# Python Reference
The entire LLDB API is available as Python functions through a script bridging
interface. This means the LLDB API's can be used directly from python either
@@ -10,21 +9,21 @@ command interpreter (we refer to this for brevity as the embedded interpreter).
Of course, in this context it has full access to the LLDB API - with some
additional conveniences we will call out in the FAQ.
Python Tutorials
-----------------
## Python Tutorials
The following tutorials and documentation demonstrate various Python capabilities within LLDB:
.. toctree::
:maxdepth: 1
```{toctree}
:maxdepth: 1
tutorials/accessing-documentation
tutorials/python-embedded-interpreter
tutorials/script-driven-debugging
tutorials/breakpoint-triggered-scripts
tutorials/creating-custom-breakpoints
tutorials/automating-stepping-logic
tutorials/writing-custom-commands
tutorials/implementing-standalone-scripts
tutorials/custom-frame-recognizers
tutorials/extending-target-stop-hooks
tutorials/accessing-documentation
tutorials/python-embedded-interpreter
tutorials/script-driven-debugging
tutorials/breakpoint-triggered-scripts
tutorials/creating-custom-breakpoints
tutorials/automating-stepping-logic
tutorials/writing-custom-commands
tutorials/implementing-standalone-scripts
tutorials/custom-frame-recognizers
tutorials/extending-target-stop-hooks
```
lldb/docs/use/repeat-commands.md
+142
View File
@@ -0,0 +1,142 @@
# Repeat Commands
In LLDB's command line interface, pressing Enter (an empty command) repeats the
previous command. By default, the exact same command is re-executed. However,
several commands customize this behavior to implement paging or progressive
expansion, making it easy to explore data incrementally by pressing Enter
repeatedly. Repeat commands can be learned and discovered by pressing enter and
observing the result.
In some instances, commands disable repeat commands, to prevent
accidentally triggering a destructive operation (e.g. `process launch`).
This page documents the commands with custom repeat behavior.
## `thread backtrace` (`bt`)
When `thread backtrace` is invoked with the `--count` (`-c`) option, the
repeat command pages through the backtrace by advancing the `--start` (`-s`)
option by the count each time.
For example:
```
(lldb) bt 5
* thread #1, stop reason = breakpoint 1.1
* frame #0: handle_request at server.cpp:50
frame #1: parse_headers at http.cpp:12
frame #2: read_socket at socket.cpp:30
frame #3: accept_connection at listener.cpp:8
frame #4: event_loop at reactor.cpp:100
(lldb)
# repeats as: thread backtrace -c 5 -s 5
* thread #1, stop reason = breakpoint 1.1
frame #5: start_server at main.cpp:42
frame #6: load_config at config.cpp:7
...
(lldb)
# repeats as: thread backtrace -c 5 -s 10
```
Each press of Enter shows the next 5 frames. If `--count` is not specified,
the full backtrace is displayed and there is no repeat command.
## `source list` (`list`)
When `source list` is repeated, it shows the next block of source lines,
continuing from where the previous listing ended. This mimics paging behavior.
If the `--reverse` (`-r`) option was given, the repeat command continues
listing in reverse (showing earlier source lines).
```
(lldb) list # shows source around the current location
(lldb) # shows the next block of source lines
(lldb) # shows the next block after that
(lldb) list -r # shows source in reverse
(lldb) # continues listing in reverse
```
## `memory read`
When `memory read` is repeated, it continues reading from where the previous
read ended. The repeat command drops the address arguments and re-uses the same
format, size, and count options from the previous invocation.
```
(lldb) memory read 0x1000 -c 32
0x1000: 48 8b 05 a9 3b 00 00 48 ...
(lldb) # continues reading the next 32 bytes from 0x1020
(lldb) # continues reading from 0x1040
```
## `memory region`
When `memory region` is given an address, it displays the memory region
containing that address. Pressing Enter then shows the next memory region, and
so on, allowing you to walk through the process's entire memory map.
```
(lldb) memory region 0x1000
[0x0000-0x2000) rw-
(lldb) # shows the next region starting at 0x2000
(lldb) # shows the next region after that
```
## `frame variable` (`v`)
When `frame variable` is repeated, it re-runs the command with an incremented
`--depth` (`-D`) value. This progressively reveals deeper levels of nested
data structures with each press of Enter.
If no `--depth` option was specified in the original command, the next repeat
starts at one level beyond the `target.max-children-depth` default setting. If
`--depth` was specified, it increments the given value by 1 each time.
Consider a deeply nested configuration structure:
```
(lldb) v config
(Config) config = {
server = {
network = {
tls = {
certificate = {
issuer = {...}
}
}
}
}
}
(lldb) # repeats as: frame variable --depth 6 config
(Config) config = {
server = {
network = {
tls = {
certificate = {
issuer = {
name = {...}
}
}
}
}
}
}
(lldb) # repeats as: frame variable --depth 7 config
```
The default `target.max-children-depth` causes the first output to truncate at
`issuer`. Each press of Enter reveals one more level without having to
manually specify `--depth`.
## `thread trace dump instructions`
When repeated, this command adds the `--continue` flag, which continues
dumping traced instructions from where the previous instruction dump left off.
```
(lldb) thread trace dump instructions
... first batch of instructions ...
(lldb) # continues dumping the next 20 instructions
```
lldb/docs/use/repeat-commands.rst
-149
View File
@@ -1,149 +0,0 @@
Repeat Commands
===============
In LLDB's command line interface, pressing Enter (an empty command) repeats the
previous command. By default, the exact same command is re-executed. However,
several commands customize this behavior to implement paging or progressive
expansion, making it easy to explore data incrementally by pressing Enter
repeatedly. Repeat commands can be learned and discovered by pressing enter and
observing the result.
In some instances, commands disable repeat commands, to prevent
accidentally triggering a destructive operation (e.g. ``process launch``).
This page documents the commands with custom repeat behavior.
``thread backtrace`` (``bt``)
-----------------------------
When ``thread backtrace`` is invoked with the ``--count`` (``-c``) option, the
repeat command pages through the backtrace by advancing the ``--start`` (``-s``)
option by the count each time.
For example:
::
(lldb) bt 5
* thread #1, stop reason = breakpoint 1.1
* frame #0: handle_request at server.cpp:50
frame #1: parse_headers at http.cpp:12
frame #2: read_socket at socket.cpp:30
frame #3: accept_connection at listener.cpp:8
frame #4: event_loop at reactor.cpp:100
(lldb)
# repeats as: thread backtrace -c 5 -s 5
* thread #1, stop reason = breakpoint 1.1
frame #5: start_server at main.cpp:42
frame #6: load_config at config.cpp:7
...
(lldb)
# repeats as: thread backtrace -c 5 -s 10
Each press of Enter shows the next 5 frames. If ``--count`` is not specified,
the full backtrace is displayed and there is no repeat command.
``source list`` (``list``)
--------------------------
When ``source list`` is repeated, it shows the next block of source lines,
continuing from where the previous listing ended. This mimics paging behavior.
If the ``--reverse`` (``-r``) option was given, the repeat command continues
listing in reverse (showing earlier source lines).
::
(lldb) list # shows source around the current location
(lldb) # shows the next block of source lines
(lldb) # shows the next block after that
(lldb) list -r # shows source in reverse
(lldb) # continues listing in reverse
``memory read``
---------------
When ``memory read`` is repeated, it continues reading from where the previous
read ended. The repeat command drops the address arguments and re-uses the same
format, size, and count options from the previous invocation.
::
(lldb) memory read 0x1000 -c 32
0x1000: 48 8b 05 a9 3b 00 00 48 ...
(lldb) # continues reading the next 32 bytes from 0x1020
(lldb) # continues reading from 0x1040
``memory region``
-----------------
When ``memory region`` is given an address, it displays the memory region
containing that address. Pressing Enter then shows the next memory region, and
so on, allowing you to walk through the process's entire memory map.
::
(lldb) memory region 0x1000
[0x0000-0x2000) rw-
(lldb) # shows the next region starting at 0x2000
(lldb) # shows the next region after that
``frame variable`` (``v``)
--------------------------
When ``frame variable`` is repeated, it re-runs the command with an incremented
``--depth`` (``-D``) value. This progressively reveals deeper levels of nested
data structures with each press of Enter.
If no ``--depth`` option was specified in the original command, the next repeat
starts at one level beyond the ``target.max-children-depth`` default setting. If
``--depth`` was specified, it increments the given value by 1 each time.
Consider a deeply nested configuration structure:
::
(lldb) v config
(Config) config = {
server = {
network = {
tls = {
certificate = {
issuer = {...}
}
}
}
}
}
(lldb) # repeats as: frame variable --depth 6 config
(Config) config = {
server = {
network = {
tls = {
certificate = {
issuer = {
name = {...}
}
}
}
}
}
}
(lldb) # repeats as: frame variable --depth 7 config
The default ``target.max-children-depth`` causes the first output to truncate at
``issuer``. Each press of Enter reveals one more level without having to
manually specify ``--depth``.
``thread trace dump instructions``
----------------------------------
When repeated, this command adds the ``--continue`` flag, which continues
dumping traced instructions from where the previous instruction dump left off.
::
(lldb) thread trace dump instructions
... first batch of instructions ...
(lldb) # continues dumping the next 20 instructions