Somewhat recently, we made the change to hide the behavior to save LLDB
session history to the transcript buffer behind the flag
`interpreter.save-transcript`. By default, `interpreter.save-transcript`
is false. See #90703 for context.
I'm making a small update here to our `session save` messaging and some
help docs to clarify for users that aren't aware of this change. Maybe
`interpreter.save-transcript` could be true by default as well. Any
feedback welcome.
# Tests
```
bin/lldb-dotest -p TestSessionSave
```
---------
Co-authored-by: Tom Yang <toyang@fb.com>
1. Use dashes (-) instead of colons (:) as time separator in a session log
file name since Windows doesn't support saving files with names containing
colons.
2. Temporary file creation code is changed in the test:
On Windows, the temporary file should be closed before 'session save'
writes session log to it. NamedTemporaryFile() can preserve the file
after closing it with delete_on_close=False option.
However, this option is only available since Python 3.12. Thus
mkstemp() is used for temporary file creation as the more compatible
option.
# Motivation
Currently, the user can already get the "transcript" (for "what is the
transcript", see `CommandInterpreter::SaveTranscript`). However, the
only way to obtain the transcript data as a user is to first destroy the
debugger, then read the save directory. Note that destroy-callbacks
cannot be used, because 1\ transcript data is private to the command
interpreter (see `CommandInterpreter.h`), and 2\ the writing of the
transcript is *after* the invocation of destory-callbacks (see
`Debugger::Destroy`).
So basically, there is no way to obtain the transcript:
* during the lifetime of a debugger (including the destroy-callbacks,
which often performs logging tasks, where the transcript can be useful)
* without relying on external storage
In theory, there are other ways for user to obtain transcript data
during a debugger's life cycle:
* Use Python API and intercept commands and results.
* Use CLI and record console input/output.
However, such ways rely on the client's setup and are not supported
natively by LLDB.
# Proposal
Add a new Python API `SBCommandInterpreter::GetTranscript()`.
Goals:
* It can be called at any time during the debugger's life cycle,
including in destroy-callbacks.
* It returns data in-memory.
Structured data:
* To make data processing easier, the return type is `SBStructuredData`.
See comments in code for how the data is organized.
* In the future, `SaveTranscript` can be updated to write different
formats using such data (e.g. JSON). This is probably accompanied by a
new setting (e.g. `interpreter.save-session-format`).
# Alternatives
The return type can also be `std::vector<std::pair<std::string,
SBCommandReturnObject>>`. This will make implementation easier, without
having to translate it to `SBStructuredData`. On the other hand,
`SBStructuredData` can convert to JSON easily, so it's more convenient
for user to process.
# Privacy
Both user commands and output/error in the transcript can contain
privacy data. However, as mentioned, the transcript is already available
to the user. The addition of the new API doesn't increase the level of
risk. In fact, it _lowers_ the risk of privacy data being leaked later
on, by avoiding writing such data to external storage.
Once the user (or their code) gets the transcript, it will be their
responsibility to make sure that any required privacy policies are
guaranteed.
# Tests
```
bin/llvm-lit -sv ../external/llvm-project/lldb/test/API/python_api/interpreter/TestCommandInterpreterAPI.py
```
```
bin/llvm-lit -sv ../external/llvm-project/lldb/test/API/commands/session/save/TestSessionSave.py
```
---------
Co-authored-by: Roy Shi <royshi@meta.com>
Co-authored-by: Med Ismail Bennani <ismail@bennani.ma>
This uses [teyit](https://pypi.org/project/teyit/) to modernize asserts,
as recommended by the [unittest release
notes](https://docs.python.org/3.12/whatsnew/3.12.html#id3).
For example, `assertTrue(a == b)` is replaced with `assertEqual(a, b)`.
This produces better error messages, e.g. `error: unexpectedly found 1
and 2 to be different` instead of `error: False`.
This is an ongoing series of commits that are reformatting our Python
code. Reformatting is done with `black` (23.1.0).
If you end up having problems merging this commit because you have made
changes to a python file, the best way to handle that is to run `git
checkout --ours <yourfile>` and then reformat it with black.
RFC: https://discourse.llvm.org/t/rfc-document-and-standardize-python-code-style
Differential revision: https://reviews.llvm.org/D151460
Eliminate boilerplate of having each test manually assign to `mydir` by calling
`compute_mydir` in lldbtest.py.
Differential Revision: https://reviews.llvm.org/D128077
Previously, when `interpreter.save-session-on-quit` was enabled, lldb
would save the session transcript only when running the `quit` command.
This patch changes that so the transcripts are saved when the debugger
object is destroyed if the setting is enabled.
rdar://72902650
Differential Revision: https://reviews.llvm.org/D105038
Signed-off-by: Med Ismail Bennani <medismail.bennani@gmail.com>
This patch introduces a new interpreter setting
`interpreter.save-session-directory` so the user can specify a directory
where the session transcripts will be saved.
If not set, the session transcript are saved on a temporary file.
rdar://72902842
Differential Revision: https://reviews.llvm.org/D105030
Signed-off-by: Med Ismail Bennani <medismail.bennani@gmail.com>
This patch moves the `history` subcommand from the `command` to `session`
command. I think it makes more sense to have it there because as the `command`
usage suggests, it should be used to manage custom LLDB commands.
However, `history` is essentially tied to a debugging session and holds
all the commands (not specifically custom ones).
This also makes it more discoverable by adding an alias for it (mimicking
the shell builtin).
Differential Revision: https://reviews.llvm.org/D84307
Signed-off-by: Med Ismail Bennani <medismail.bennani@gmail.com>
This patch introduce a new feature that allows the users to save their
debugging session's transcript (commands + outputs) to a file.
It differs from the reproducers since it doesn't require to capture a
session preemptively and replay the reproducer file in lldb.
The user can choose the save its session manually using the session save
command or automatically by setting the interpreter.save-session-on-quit
on their init file.
To do so, the patch adds a Stream object to the CommandInterpreter that
will hold the input command from the IOHandler and the CommandReturnObject
output and error. This way, that stream object accumulates passively all
the interactions throughout the session and will save them to disk on demand.
The user can specify a file path where the session's transcript will be
saved. However, it is optional, and when it is not provided, lldb will
create a temporary file name according to the session date and time.
rdar://63347792
Differential Revision: https://reviews.llvm.org/D82155
Signed-off-by: Med Ismail Bennani <medismail.bennani@gmail.com>
