Document debuginfo repr directive - #2947
Conversation
|
Thanks for the PR. If you have write access, feel free to merge this PR if it does not need reviews. You can request a review using |
rustbot
added
the
S-waiting-on-review
|
hmm, i think that's an bug with linkcheck? Those aren't link specifiers, they're github-style alerts. mdbook added support for them a few months ago. |
| a nightmare and lead to a [litany of issues](https://github.com/rust-lang/rust/issues/134682). | ||
| To help remedy this: | ||
|
|
||
| 1. [`tests/debuginfo` is now opt-in](https://github.com/rust-lang/rust/pull/159455) |
There was a problem hiding this comment.
Except for CDB, that is still implicit, AFAIK.
|
|
||
| When the commands are passed to the debugger, our test framework intercepts `repr` pseudo-commands | ||
| and runs special logic on them, testing against data stored in | ||
| `tests/debuginfo/<test_name></test_name>/input/<debugger>_input/<target_group>.json`. |
There was a problem hiding this comment.
| `tests/debuginfo/<test_name></test_name>/input/<debugger>_input/<target_group>.json`. | |
| `tests/debuginfo/<test_name>/input/<debugger>_input/<target_group>.json`. |
| target file (or creates a new file if necessary). | ||
|
|
||
| The schema of the input data is defined by the classes in | ||
| [`common.py`](https://github.com/rust-lang/rust/blob/main/src/etc/lldb_batchmode/common.py). |
There was a problem hiding this comment.
Could you use a permalink here, please? Thanks!
|
|
||
| Once imported, `common` automatically deserializes any existing input data and [stores it in the | ||
| global variable `INPUT_DATA`](https://github.com/rust-lang/rust/blob/bf9944f0b8006b152ef4d5f408ae75a0dde3d044/src/etc/lldb_batchmode/common.py#L523). This | ||
| data is what is tested against. |
There was a problem hiding this comment.
| data is what is tested against. | |
| data is what we test against. |
|
|
||
| ### Entry point and `--bless` | ||
|
|
||
| Upon encountering a `repr` pseudo-command, `lldb_batchmode.main` calls `dispatch_repr`, which calls |
There was a problem hiding this comment.
I don't think that we have to document these low-level details (e.g. calling a specific function), because they should be immediately visible in the code, and more importantly they can easily change and then the docs will be stale.
| to it, and print the exception ourselves. We can also inspect the synthetic provider class to make | ||
| sure it implements all the mandatory functions. | ||
|
|
||
| Errors *do not* fail fast. This is especially important now that a `--bless` option has been added. |
There was a problem hiding this comment.
I know what you meant here, but this sounds a bit misleading - if there is an error/mismatch found, then surely the test will fail, right? Maybe add something like "do not fail the test immediately"?
| > At time of writing (July 2026) this command is limited to LLDB, with an implementation coming soon | ||
| > for GDB. There are not firm plans to port the logic to CDB. | ||
|
|
||
| This command effectivly de-sugars into: |
There was a problem hiding this comment.
| This command effectivly de-sugars into: | |
| This command effectively desugars into: |
| The `repr $VAR_NAME` command is intercepted by special logic that uses the debuggers' API to inspect | ||
| data that isn't reflected in the variable's printed output. The variable in memory is compared | ||
| against input data stored in | ||
| `tests/debuginfo/<test_name></test_name>/input/<debugger>_input/<target_group>.json` and |
There was a problem hiding this comment.
| `tests/debuginfo/<test_name></test_name>/input/<debugger>_input/<target_group>.json` and | |
| `tests/debuginfo/<test_name>/input/<debugger>_input/<target_group>.json` and |
Maybe we can just link to the debuginfo section here, to avoid this duplication.
3 participants
Documents the directive added in rust-lang/rust#158298 as part of rust-lang/rust#148483 (I also a fixed a few things that have changed in the lead-up to adding the directive).
I'm planning on coming back and filling the testing section a bit more once the GDB implementation is finalized. I also want to fill out the section on writing GDB visualizers, but that's not as urgent.
@Kobzol @jieyouxu