[Lldb-commits] [lldb] [llvm] [lldb][Docs] Add examples section for variable formatting (PR #194916)
via lldb-commits
lldb-commits at lists.llvm.org
Thu Apr 30 09:26:20 PDT 2026
https://github.com/Nerixyz updated https://github.com/llvm/llvm-project/pull/194916
>From 3137364335b435ff0b2f49435501dccbd512fe94 Mon Sep 17 00:00:00 2001
From: Nerixyz <nerixdev at outlook.de>
Date: Mon, 27 Apr 2026 20:50:36 +0200
Subject: [PATCH 1/3] [lldb][Docs] Add examples section for variable formatting
---
lldb/docs/use/variable.rst | 104 +++++++++++++++++++++++++++++++
llvm/utils/lldbDataFormatters.py | 4 ++
2 files changed, 108 insertions(+)
diff --git a/lldb/docs/use/variable.rst b/lldb/docs/use/variable.rst
index 82bb3c7ba1e11..0cd3d2b65c4ac 100644
--- a/lldb/docs/use/variable.rst
+++ b/lldb/docs/use/variable.rst
@@ -1383,6 +1383,110 @@ displayed. The reason the debugger warns you is that enabling an empty category
might be a typo, and you effectively wanted to enable a similarly-named but
not-empty category.
+Examples
+--------
+
+These are a few examples of summaries and synthetic children providers for
+types you may want to format.
+
+You can find further examples here:
+
+- `LLVM Data Formatters <https://github.com/llvm/llvm-project/blob/main/llvm/utils/lldbDataFormatters.py>`_
+- `Coca (Objective-C) Formatters <https://github.com/llvm/llvm-project/tree/main/lldb/examples/summaries/cocoa>`_
+.. TODO: Add libc++ formatters here
+
+Type Summaries
+^^^^^^^^^^^^^^
+
+- **Strings**: Many string types contain a pair of a data pointer and a size.
+ This shows `llvm::StringRef <https://llvm.org/doxygen/classllvm_1_1StringRef.html>`_
+ which has a definition similar to the following:
+
+ .. code-block:: cpp
+
+ struct StringRef {
+ /// The start of the string, in an external buffer.
+ const char *Data;
+ /// The length of the string.
+ size_t Length;
+ };
+
+ We can use a ``char[N]`` array to create a summary for this string.
+ This will handle escaping of non-printable characters like tabs or newlines for us.
+
+ .. literalinclude:: ../../../llvm/utils/lldbDataFormatters.py
+ :start-after: [SNIP-StringRef-Summary]
+ :end-before: [/SNIP-StringRef-Summary]
+
+- **Containers**: For most containers, displaying the size in the summary is
+ enough. LLDB usually displays the size as ``size=42`` for C++ STL types.
+ If your container has a `Synthetic Children <synthetic-children_>`_ provider,
+ you can use `Summary Strings`_:
+ ::
+
+ type summary add -s "size=${svar%#}" MyContainer
+ # Of if the container is a template:
+ type summary add -s "size=${svar%#}" -x "^MyContainer<.+>$"
+
+Synthetic Children
+^^^^^^^^^^^^^^^^^^
+
+- **Spans**: This shows a synthetic children provider for
+ `llvm::ArrayRef <https://llvm.org/doxygen/classllvm_1_1ArrayRef.html>`_.
+ This is similar to a ``std::span``. It consists of a data pointer and a size:
+
+ .. code-block:: cpp
+
+ template <typename T>
+ struct ArrayRef {
+ /// The start of the array, in an external buffer.
+ const T *Data;
+ /// The number of elements.
+ size_t Length;
+ };
+
+ The two methods of interest here are ``get_child_at_index`` and ``update``.
+ We're using ``CreateChildAtOffset`` to create the children when requested.
+ Note that this takes an offset in bytes, so we need to multiply by the size
+ of ``T``.
+
+ .. literalinclude:: ../../../llvm/utils/lldbDataFormatters.py
+ :start-after: [SNIP-ArrayRef-Synth]
+ :end-before: [/SNIP-ArrayRef-Synth]
+
+- **Synthetic Values**: You might have some types that wrap primitive types.
+ For example, you might have a class that provides checked arithmetic to guard
+ against overflow:
+
+ .. code-block:: cpp
+
+ struct CheckedInt {
+ int Value;
+ // Defines operator+, operator-, etc.
+ };
+
+ We can use ``lldb.SBSyntheticValueProvider`` to show the type as if it was
+ the inner ``Value``:
+
+ .. code-block:: python
+
+ class CheckedIntSynthProvider(lldb.SBSyntheticValueProvider):
+
+ valobj: lldb.SBValue
+ value: Optional[lldb.SBValue]
+
+ def __init__(self, valobj: lldb.SBValue, internal_dict):
+ self.valobj = valobj
+ self.value = None
+
+ def update(self):
+ self.value = self.valobj.GetChildAtIndex(0)
+ return False
+
+ def get_value(self):
+ return self.value
+
+
Finding Formatters 101
----------------------
diff --git a/llvm/utils/lldbDataFormatters.py b/llvm/utils/lldbDataFormatters.py
index c986f6695f88f..a69894d239a2b 100644
--- a/llvm/utils/lldbDataFormatters.py
+++ b/llvm/utils/lldbDataFormatters.py
@@ -146,6 +146,7 @@ def update(self):
assert self.type_size != 0
+# [SNIP-ArrayRef-Synth]
class ArrayRefSynthProvider:
"""Provider for llvm::ArrayRef"""
@@ -183,6 +184,7 @@ def update(self):
self.data_type = self.data.GetType().GetPointeeType()
self.type_size = self.data_type.GetByteSize()
assert self.type_size != 0
+ # [/SNIP-ArrayRef-Synth]
def SmallStringSummaryProvider(valobj: lldb.SBValue, internal_dict) -> str:
@@ -198,6 +200,7 @@ def SmallStringSummaryProvider(valobj: lldb.SBValue, internal_dict) -> str:
return res
+# [SNIP-StringRef-Summary]
def StringRefSummaryProvider(valobj: lldb.SBValue, internal_dict) -> str:
data_pointer = valobj.GetChildMemberWithName("Data")
length = valobj.GetChildMemberWithName("Length").unsigned
@@ -217,6 +220,7 @@ def StringRefSummaryProvider(valobj: lldb.SBValue, internal_dict) -> str:
# Use the builtin summary for its support of max-string-summary-length and
# display of non-printable bytes.
return char_array.summary
+ # [/SNIP-StringRef-Summary]
def ConstStringSummaryProvider(valobj: lldb.SBValue, internal_dict) -> str:
>From bda6a0b7f4530214c154c7797106c796ef40d14d Mon Sep 17 00:00:00 2001
From: Nerixyz <nerixdev at outlook.de>
Date: Thu, 30 Apr 2026 18:25:58 +0200
Subject: [PATCH 2/3] fix: review
---
lldb/docs/use/variable.rst | 19 +++++++++++--------
1 file changed, 11 insertions(+), 8 deletions(-)
diff --git a/lldb/docs/use/variable.rst b/lldb/docs/use/variable.rst
index 0cd3d2b65c4ac..10ad727e13fcf 100644
--- a/lldb/docs/use/variable.rst
+++ b/lldb/docs/use/variable.rst
@@ -1398,9 +1398,10 @@ You can find further examples here:
Type Summaries
^^^^^^^^^^^^^^
-- **Strings**: Many string types contain a pair of a data pointer and a size.
- This shows `llvm::StringRef <https://llvm.org/doxygen/classllvm_1_1StringRef.html>`_
- which has a definition similar to the following:
+- **Strings**: Many libraries have a user-defined string type that is
+ implemented with a data pointer and a size. For example,
+ `llvm::StringRef <https://llvm.org/doxygen/classllvm_1_1StringRef.html>`_ is
+ implemented like:"
.. code-block:: cpp
@@ -1412,16 +1413,18 @@ Type Summaries
};
We can use a ``char[N]`` array to create a summary for this string.
- This will handle escaping of non-printable characters like tabs or newlines for us.
+ This technique handles escaping of non-printable characters like tabs or
+ newlines.
.. literalinclude:: ../../../llvm/utils/lldbDataFormatters.py
:start-after: [SNIP-StringRef-Summary]
:end-before: [/SNIP-StringRef-Summary]
-- **Containers**: For most containers, displaying the size in the summary is
- enough. LLDB usually displays the size as ``size=42`` for C++ STL types.
- If your container has a `Synthetic Children <synthetic-children_>`_ provider,
- you can use `Summary Strings`_:
+- **Containers**: For most containers, displaying the number of elements in the
+ summary is sufficient. LLDB usually displays the number as ``size=42`` for
+ C++ STL types. If your container has a
+ `synthetic children <synthetic-children_>`_ provider, you can use
+ `Summary Strings`_:
::
type summary add -s "size=${svar%#}" MyContainer
>From 234f116b8b60aea55355b5a39c2ee13aaf9a4fc8 Mon Sep 17 00:00:00 2001
From: Nerixyz <nerixdev at outlook.de>
Date: Thu, 30 Apr 2026 18:26:04 +0200
Subject: [PATCH 3/3] fix: sphinx warnings
---
lldb/docs/use/variable.rst | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/lldb/docs/use/variable.rst b/lldb/docs/use/variable.rst
index 10ad727e13fcf..2363c122f77ec 100644
--- a/lldb/docs/use/variable.rst
+++ b/lldb/docs/use/variable.rst
@@ -1393,10 +1393,11 @@ You can find further examples here:
- `LLVM Data Formatters <https://github.com/llvm/llvm-project/blob/main/llvm/utils/lldbDataFormatters.py>`_
- `Coca (Objective-C) Formatters <https://github.com/llvm/llvm-project/tree/main/lldb/examples/summaries/cocoa>`_
+
.. TODO: Add libc++ formatters here
Type Summaries
-^^^^^^^^^^^^^^
+++++++++++++++
- **Strings**: Many libraries have a user-defined string type that is
implemented with a data pointer and a size. For example,
@@ -1432,7 +1433,7 @@ Type Summaries
type summary add -s "size=${svar%#}" -x "^MyContainer<.+>$"
Synthetic Children
-^^^^^^^^^^^^^^^^^^
+++++++++++++++++++
- **Spans**: This shows a synthetic children provider for
`llvm::ArrayRef <https://llvm.org/doxygen/classllvm_1_1ArrayRef.html>`_.
More information about the lldb-commits
mailing list