Currently, the type `T`'s summary formatter will be matched for `T`,
`T*`, `T**` and so on. This is unexpected in many data formatters. Such
unhandled cases could cause the data formatter to crash. An example
would be the lldb's built-in data formatter for `std::optional`:
```
$ cat main.cpp
#include <optional>
int main() {
std::optional<int> o_null;
auto po_null = &o_null;
auto ppo_null = &po_null;
auto pppo_null = &ppo_null;
return 0;
}
$ clang++ -g main.cpp && lldb -o "b 8" -o "r" -o "v pppo_null"
[lldb crash]
```
This change adds an options `--pointer-match-depth` to `type summary
add` command to allow users to specify how many layer of pointers can be
dereferenced at most when matching a summary formatter of type `T`, as
Jim suggested
[here](https://github.com/llvm/llvm-project/pull/124048/#issuecomment-2611164133).
By default, this option has value 1 which means summary formatter for
`T` could also be used for `T*` but not `T**` nor beyond. This option is
no-op when `--skip-pointers` is set as well.
I didn't add such option for `type synthetic add`, `type format add`,
`type filter add`, because it useful for those command. Instead, they
all have the pointer match depth of 1. When printing a type `T*`, lldb
never print the children of `T` even if there is a synthetic formatter
registered for `T`.
This is still leftover from the days when the libc++ and libstdc++
formatters were both written in python and in separate categories. Since
then we group libstdc++ and libc++ formatters into the same cateogry.
This patch removes references to the obsolete `gnu-libstdc++` category
from the docs (and a test).
See [this
thread](https://github.com/llvm/llvm-project/pull/140761#discussion_r2102386080)
for more context
Adds support for applying LLVM formatting to variables.
The reason for this is to support cases such as the following.
Let's say you have two separate bytes that you want to print as a
combined hex value. Consider the following summary string:
```
${var.byte1%x}${var.byte2%x}
```
The output of this will be: `0x120x34`. That is, a `0x` prefix is
unconditionally applied to each byte. This is unlike printf formatting
where you must include the `0x` yourself.
Currently, there's no way to do this with summary strings, instead
you'll need a summary provider in python or c++.
This change introduces formatting support using LLVM's formatter system.
This allows users to achieve the desired custom formatting using:
```
${var.byte1:x-}${var.byte2:x-}
```
Here, each variable is suffixed with `:x-`. This is passed to the LLVM
formatter as `{0:x-}`. For integer values, `x` declares the output as
hex, and `-` declares that no `0x` prefix is to be used. Further, one
could write:
```
${var.byte1:x-2}${var.byte2:x-2}
```
Where the added `2` results in these bytes being written with a minimum
of 2 digits.
An alternative considered was to add a new format specifier that would
print hex values without the `0x` prefix. The reason that approach was
not taken is because in addition to forcing a `0x` prefix, hex values
are also forced to use leading zeros. This approach lets the user have
full control over formatting.
In the LDDB documentation you have the following sentence:
"The --format (which you can shorten to -f) option accepts a format name."
The link points to the wrong place.
I pointed it to the table that precedes the Type summary section.
Reviewed By: DavidSpickett
Differential Revision: https://reviews.llvm.org/D151668
This patch brings a fresh coat of paint to the LLDB website.
This uses the `furo` theme from the suggested theme list, adds some
changes to the css to make it use the full browser window width and
removes the table of contents since the theme generates it automatically.
This patch also rewrites the tables for "GDB to LLDB command map" to
convert them from raw HTML to native inlined code blocks.
To generate the website, make sure you install the theme first with
`pip install furo`, enable sphinx in the cmake invocation` then run
`ninja docs-lldb-html`
Discourse: https://discourse.llvm.org/t/rfc-revamping-lldbs-website
Differential Revision: https://reviews.llvm.org/D158323
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This patch reverts the lldb website revamp (eea8874) since the `furo` theme
that we use is not installed on the publisher bot. The prevents other
website from getting there documentation updated.
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This patch brings a fresh coat of paint to the LLDB website.
This uses the `furo` theme from the suggested theme list, adds some
changes to the css to make it use the full browser window width and
removes the table of contents since the theme generates it automatically.
This patch also rewrites the tables for "GDB to LLDB command map" to
convert them from raw HTML to native inlined code blocks.
To generate the website, make sure you install the theme first with
`pip install furo`, enable sphinx in the cmake invocation` then run
`ninja docs-lldb-html`
Discourse: https://discourse.llvm.org/t/rfc-revamping-lldbs-website
Differential Revision: https://reviews.llvm.org/D158323
Signed-off-by: Med Ismail Bennani <ismail@bennani.ma>
This change adds a `--recognizer-function` (`-R`) to `type summary add`
and `type synth add` that allows users to specify that the names in
the command are not type names but python function names.
It also adds an example to lldb/examples, and a section in the data
formatters documentation on how to use recognizer functions.
Differential Revision: https://reviews.llvm.org/D137000
Tested by building the docs-lldb-html target and
confirming the code-block renders properly with
the fix.
Patch by Michael Buch!
Differential Revision: https://reviews.llvm.org/D127437
When looking up user specified formatters qualifiers are removed from types before matching,
I have added a clarifying example to the document and added an example to a relevant test to demonstrate this behavior.
Differential Revision: https://reviews.llvm.org/D99827
sphinx processes text in backticks depending on what 'role' it has (e.g.,
`:code:\`blub\`` -> role is `code`). If no role is provided, the default role is
taken which is right now using the default value of `content`. `content` only
really makes the text cursive which isn't really useful for anything right now.
Sphinx recommends using the `any` role by default [1] as that turns text in
backticks without an explicit roles into some kind of smart reference. If we did
this in LLDB, then we could just reference SB API classes by doing `\`SBValue\``
instead of typing out the rather verbose `:py:class:`/`:py:func:`/... role
before each reference. This would be especially nice when writing the SB API
docs itself as we constantly have to reference other classes.
[1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-any
Reviewed By: JDevlieghere
Differential Revision: https://reviews.llvm.org/D94899
Changed two references to developers as "he" or "him" to the more neutral "they".
Reviewed By: JDevlieghere, sylvestre.ledru
Differential Revision: https://reviews.llvm.org/D78807
Summary:
The ValueObject code checks for a special `$$dereference$$` synthetic
child to allow formatter providers to implement a natural
dereferencing behavior in `frame variable` for objects like smart
pointers.
This support was broken when used directly throught the Python API and
not trhough `frame variable`. The reason is that
SBFrame.FindVariable() will return by default the synthetic variable
if it exists, while `frame variable` will not do this eagerly. The
code in `ValueObject::Dereference()` accounted for the latter but not
for the former. The fix is trivial. The test change includes
additional covergage for the already-working bahevior as it wasn't
covered by the testsuite before.
This commit also adds a short piece of documentatione explaining that
it is possible (even advisable) to provide this synthetic child
outstide of the range of the normal children.
Reviewers: jingham
Subscribers: lldb-commits
Tags: #lldb
Differential Revision: https://reviews.llvm.org/D73053
While the in-place hints on valid formats are up to date (e.g. when
choosing an invalid format expr -f nonExisting -- 42), the corresponding
online docs table is not. The formats "address", "hex float",
"instruction" and "void" are missing, and "decimal" refers to an
outdated abbreviation 'i' instead of 'd'.
Patch by: Lukas Böger
Differential revision: https://reviews.llvm.org/D63813
llvm-svn: 366364
The current LLDB website is written in HTML which is hard to maintain.
We have quite a bit of HTML code checked in which can make it hard to
differentiate between documentation written by us and documentation
generated by a tool.
In line with the other LLVM projects, I propose generating the
documentation with Sphix. I think text/rst files provide a lower barrier
for new or casual contributors to fix or update.
This patch adds a copy of the LLDB website and documentation in
reStructuredText. It also adds a new ninja target `docs-lldb-html` when
-DLLVM_ENABLE_SPHINX:BOOL is enabled.
This is the first step in having the website and documentation being
generated from the repository, rather than having the output checked-in
under the www folder. During the hopefully short transition period,
please also update the reStructuredText files when modifying the
website.
Differential revision: https://reviews.llvm.org/D55376
llvm-svn: 352644
