https://github.com/JDevlieghere updated
https://github.com/llvm/llvm-project/pull/147621
>From 337a7e43efcab08061ca6a5a0bd05547d783c63c Mon Sep 17 00:00:00 2001
From: Jonas Devlieghere <jo...@devlieghere.com>
Date: Fri, 11 Jul 2025 13:33:53 -0700
Subject: [PATCH] [lldb] Document the SBDebugger public interface
Despite our best efforts, improved documentation of the public API
remains a common request amongst its users. We have the Docstrings files
in the bindings directory, but coverage and quality varies greatly by
class.
I've noticed that we a bunch of Doxygen comments throughout LLDB, but
relatively few in the SB API, which might be explained by the
aforementioned Docstrings files. With #147617, we can leverage the
Doxygen documentation to automatically generate Pydoc documentation for
the Python bindings using SWIG.
Going forward, I'd like to invest in the Doxygen documentation for the
public API. This PR is a first step in that direction. The Doxygen
comments will benefit both C++ and Python clients. Additionally, the
compiler (through the -Wdocumentation flag) can help catch quality and
correctness issues.
---
lldb/include/lldb/API/SBDebugger.h | 252 +++++++++++++++++++++++------
1 file changed, 200 insertions(+), 52 deletions(-)
diff --git a/lldb/include/lldb/API/SBDebugger.h
b/lldb/include/lldb/API/SBDebugger.h
index 192fbee9c0c6d..f77b0c1d7f0ee 100644
--- a/lldb/include/lldb/API/SBDebugger.h
+++ b/lldb/include/lldb/API/SBDebugger.h
@@ -44,6 +44,7 @@ class LLDB_API SBInputReader {
class LLDB_API SBDebugger {
public:
+ /// Broadcast bit definitions for the SBDebugger.
FLAGS_ANONYMOUS_ENUM() {
eBroadcastBitProgress = lldb::DebuggerBroadcastBit::eBroadcastBitProgress,
eBroadcastBitWarning = lldb::DebuggerBroadcastBit::eBroadcastBitWarning,
@@ -55,16 +56,22 @@ class LLDB_API SBDebugger {
eBroadcastBitExternalProgressCategory =
lldb::DebuggerBroadcastBit::eBroadcastBitExternalProgressCategory,
};
+
+ /// Default constructor creates an invalid SBDebugger instance.
SBDebugger();
SBDebugger(const lldb::SBDebugger &rhs);
~SBDebugger();
+ /// Get the broadcaster class name.
static const char *GetBroadcasterClass();
+ /// Check if a specific language is supported by LLDB.
static bool SupportsLanguage(lldb::LanguageType language);
+ /// Get the broadcaster that allows subscribing to events from this
+ /// debugger.
lldb::SBBroadcaster GetBroadcaster();
/// Get progress data from a SBEvent whose type is eBroadcastBitProgress.
@@ -106,44 +113,80 @@ class LLDB_API SBDebugger {
bool &is_debugger_specific);
#endif
+ /// Get progress data from an event.
static lldb::SBStructuredData
GetProgressDataFromEvent(const lldb::SBEvent &event);
+ /// Get diagnostic information from an event.
static lldb::SBStructuredData
GetDiagnosticFromEvent(const lldb::SBEvent &event);
+ /// Assignment operator.
lldb::SBDebugger &operator=(const lldb::SBDebugger &rhs);
+ /// Initialize LLDB and its subsystems.
+ ///
+ /// This function should be called before any other LLDB functions. It
+ /// initializes all required subsystems for proper LLDB functionality.
static void Initialize();
+ /// Initialize the LLDB debugger subsystem with error handling.
+ ///
+ /// Similar to Initialize(), but returns an error if initialization fails.
static lldb::SBError InitializeWithErrorHandling();
+ /// Configure LLDB to print a stack trace when it crashes.
static void PrintStackTraceOnError();
+ /// Configure LLDB to print diagnostic information when it crashes.
static void PrintDiagnosticsOnError();
+ /// Terminate LLDB and its subsystems.
+ ///
+ /// This should be called when LLDB is no longer needed.
static void Terminate();
+ /// Create a new debugger instance (deprecated).
LLDB_DEPRECATED_FIXME("Use one of the other Create variants", "Create(bool)")
static lldb::SBDebugger Create();
+ /// Create a new debugger instance.
+ ///
+ /// If source_init_files is true, the debugger will source .lldbinit files
+ /// from the home directory and current directory.
static lldb::SBDebugger Create(bool source_init_files);
+ /// Create a new debugger instance with a custom log handler and user data
+ /// passed to the log callback.
+ ///
+ /// If source_init_files is true, the debugger will source .lldbinit files
+ /// from the home directory and current directory.
static lldb::SBDebugger Create(bool source_init_files,
lldb::LogOutputCallback log_callback,
void *baton);
+ /// Destroy a debugger instance.
static void Destroy(lldb::SBDebugger &debugger);
+ /// Notify the debugger that system memory pressure has been detected.
+ ///
+ /// This can be used to free up memory resources by clearing caches.
static void MemoryPressureDetected();
+ /// Check if this is a valid SBDebugger object.
explicit operator bool() const;
+ /// Check if this is a valid SBDebugger object.
bool IsValid() const;
+ /// Clear this debugger instance.
+ ///
+ /// This will close all IO handlers and reset the debugger to its initial
+ /// state.
void Clear();
- /// Getting a specific setting value into SBStructuredData format.
+ /// Get debugger settings as structured data.
+ ///
/// Client can specify empty string or null to get all settings.
///
/// Example usages:
@@ -152,71 +195,102 @@ class LLDB_API SBDebugger {
/// lldb::SBStructuredData settings = debugger.GetSetting("");
/// lldb::SBStructuredData settings = debugger.GetSetting("target.arg0");
/// lldb::SBStructuredData settings = debugger.GetSetting("target");
- ///
- /// \param[out] setting
- /// Property setting path to retrieve values. e.g "target.source-map"
- ///
lldb::SBStructuredData GetSetting(const char *setting = nullptr);
+ /// Set whether the debugger should run in asynchronous mode.
+ ///
+ /// When in asynchronous mode, events are processed on a background thread.
void SetAsync(bool b);
+ /// Get whether the debugger is running in asynchronous mode.
bool GetAsync();
+ /// Set whether to skip loading .lldbinit files.
void SkipLLDBInitFiles(bool b);
+ /// Set whether to skip loading application-specific .lldbinit files.
void SkipAppInitFiles(bool b);
#ifndef SWIG
+ /// Set the input file handle for the debugger.
void SetInputFileHandle(FILE *f, bool transfer_ownership);
+ /// Set the output file handle for the debugger.
void SetOutputFileHandle(FILE *f, bool transfer_ownership);
+ /// Set the error file handle for the debugger.
void SetErrorFileHandle(FILE *f, bool transfer_ownership);
#endif
#ifndef SWIG
+ /// Get the input file handle for the debugger.
FILE *GetInputFileHandle();
+ /// Get the output file handle for the debugger.
FILE *GetOutputFileHandle();
+ /// Get the error file handle for the debugger.
FILE *GetErrorFileHandle();
#endif
+ /// Set the input from a string.
SBError SetInputString(const char *data);
+ /// Set the input file for the debugger.
SBError SetInputFile(SBFile file);
+ /// Set the output file for the debugger.
SBError SetOutputFile(SBFile file);
+ /// Set the error file for the debugger.
SBError SetErrorFile(SBFile file);
+ /// Set the input file for the debugger using a FileSP.
SBError SetInputFile(FileSP file);
+ /// Set the output file for the debugger using a FileSP.
SBError SetOutputFile(FileSP file);
+ /// Set the error file for the debugger using a FileSP.
SBError SetErrorFile(FileSP file);
+ /// Get the input file for the debugger.
SBFile GetInputFile();
+ /// Get the output file for the debugger.
SBFile GetOutputFile();
+ /// Get the error file for the debugger.
SBFile GetErrorFile();
+ /// Save the current terminal state.
+ ///
+ /// This should be called before modifying terminal settings.
void SaveInputTerminalState();
+ /// Restore the previously saved terminal state.
void RestoreInputTerminalState();
+ /// Get the command interpreter for this debugger.
lldb::SBCommandInterpreter GetCommandInterpreter();
+ /// Execute a command in the command interpreter.
void HandleCommand(const char *command);
+ /// Request an interrupt of the current operation.
void RequestInterrupt();
+
+ /// Cancel a previously requested interrupt.
void CancelInterruptRequest();
+
+ /// Check if an interrupt has been requested.
bool InterruptRequested();
+ /// Get the listener associated with this debugger.
lldb::SBListener GetListener();
#ifndef SWIG
+ /// Handle a process event (deprecated).
LLDB_DEPRECATED_FIXME(
"Use HandleProcessEvent(const SBProcess &, const SBEvent &, SBFile, "
"SBFile) or HandleProcessEvent(const SBProcess &, const SBEvent &, "
@@ -226,58 +300,78 @@ class LLDB_API SBDebugger {
const lldb::SBEvent &event, FILE *out, FILE *err);
#endif
+ /// Handle a process event.
void HandleProcessEvent(const lldb::SBProcess &process,
const lldb::SBEvent &event, SBFile out, SBFile err);
#ifdef SWIG
+ /// Handle a process event using FileSP objects.
void HandleProcessEvent(const lldb::SBProcess &process,
const lldb::SBEvent &event, FileSP BORROWED, FileSP
BORROWED);
#else
+ /// Handle a process event using FileSP objects.
void HandleProcessEvent(const lldb::SBProcess &process,
const lldb::SBEvent &event, FileSP out, FileSP err);
#endif
+ /// Create a target with the specified parameters.
lldb::SBTarget CreateTarget(const char *filename, const char *target_triple,
const char *platform_name,
bool add_dependent_modules, lldb::SBError
&error);
+ /// Create a target with the specified file and target triple.
lldb::SBTarget CreateTargetWithFileAndTargetTriple(const char *filename,
const char
*target_triple);
+ /// Create a target with the specified file and architecture.
lldb::SBTarget CreateTargetWithFileAndArch(const char *filename,
const char *archname);
+ /// Create a target with the specified file.
lldb::SBTarget CreateTarget(const char *filename);
+ /// Get the dummy target.
+ ///
+ /// The dummy target is used when no target is available.
lldb::SBTarget GetDummyTarget();
#ifndef SWIG
- // Dispatch telemery from client to server if client-telemetry is enabled
- // (by vendor), otherwise the data is ignored.
- // Invoking this from python client (with SWIG) is not supported.
+ /// Dispatch telemetry data from client to server.
+ ///
+ /// This is used to send telemetry data from the client to the server if
+ /// client-telemetry is enabled. If not enabled, the data is ignored.
void DispatchClientTelemetry(const lldb::SBStructuredData &data);
#endif
- // Return true if target is deleted from the target list of the debugger.
+ /// Delete a target from the debugger.
bool DeleteTarget(lldb::SBTarget &target);
+ /// Get a target by index.
lldb::SBTarget GetTargetAtIndex(uint32_t idx);
+ /// Get the index of a target.
uint32_t GetIndexOfTarget(lldb::SBTarget target);
+ /// Find a target with the specified process ID.
lldb::SBTarget FindTargetWithProcessID(lldb::pid_t pid);
+ /// Find a target with the specified file and architecture.
lldb::SBTarget FindTargetWithFileAndArch(const char *filename,
const char *arch);
+ /// Get the number of targets in the debugger.
uint32_t GetNumTargets();
+ /// Get the currently selected target.
lldb::SBTarget GetSelectedTarget();
+ /// Set the selected target.
void SetSelectedTarget(SBTarget &target);
+ /// Get the selected platform.
lldb::SBPlatform GetSelectedPlatform();
+ /// Set the selected platform.
void SetSelectedPlatform(lldb::SBPlatform &platform);
/// Get the number of currently active platforms.
@@ -292,200 +386,247 @@ class LLDB_API SBDebugger {
/// "platform list" command.
uint32_t GetNumAvailablePlatforms();
- /// Get the name and description of one of the available platforms.
- ///
- /// \param[in] idx
- /// Zero-based index of the platform for which info should be retrieved,
- /// must be less than the value returned by GetNumAvailablePlatforms().
+ /// Get information about the available platform at the given index as
+ /// structured data.
lldb::SBStructuredData GetAvailablePlatformInfoAtIndex(uint32_t idx);
+ /// Get the source manager for this debugger.
lldb::SBSourceManager GetSourceManager();
- // REMOVE: just for a quick fix, need to expose platforms through
- // SBPlatform from this class.
+ /// Set the current platform by name.
lldb::SBError SetCurrentPlatform(const char *platform_name);
+ /// Set the SDK root for the current platform.
bool SetCurrentPlatformSDKRoot(const char *sysroot);
- // FIXME: Once we get the set show stuff in place, the driver won't need
- // an interface to the Set/Get UseExternalEditor.
+ /// Set whether to use an external editor.
bool SetUseExternalEditor(bool input);
+ /// Get whether an external editor is being used.
bool GetUseExternalEditor();
+ /// Set whether to use color in output.
bool SetUseColor(bool use_color);
+ /// Get whether color is being used in output.
bool GetUseColor() const;
- bool SetShowInlineDiagnostics(bool);
+ /// Set whether to show inline diagnostics.
+ bool SetShowInlineDiagnostics(bool b);
+ /// Set whether to use the source cache.
bool SetUseSourceCache(bool use_source_cache);
+ /// Get whether the source cache is being used.
bool GetUseSourceCache() const;
+ /// Get the default architecture.
static bool GetDefaultArchitecture(char *arch_name, size_t arch_name_len);
+ /// Set the default architecture.
static bool SetDefaultArchitecture(const char *arch_name);
+ /// Get the scripting language by name.
lldb::ScriptLanguage GetScriptingLanguage(const char *script_language_name);
- SBStructuredData GetScriptInterpreterInfo(ScriptLanguage);
+ /// Get information about a script interpreter as structured data.
+ SBStructuredData GetScriptInterpreterInfo(ScriptLanguage language);
+ /// Get the LLDB version string.
static const char *GetVersionString();
+ /// Convert a state type to a string.
static const char *StateAsCString(lldb::StateType state);
+ /// Get the build configuration as structured data.
static SBStructuredData GetBuildConfiguration();
+ /// Check if a state is a running state.
static bool StateIsRunningState(lldb::StateType state);
+ /// Check if a state is a stopped state.
static bool StateIsStoppedState(lldb::StateType state);
+ /// Enable logging for a specific channel and category.
bool EnableLog(const char *channel, const char **categories);
+ /// Set a callback for log output.
void SetLoggingCallback(lldb::LogOutputCallback log_callback, void *baton);
- /// Clear all previously added callbacks and only add the given one.
+ /// Set a callback for when the debugger is destroyed (deprecated).
LLDB_DEPRECATED_FIXME("Use AddDestroyCallback and RemoveDestroyCallback",
"AddDestroyCallback")
void SetDestroyCallback(lldb::SBDebuggerDestroyCallback destroy_callback,
void *baton);
- /// Add a callback for when the debugger is destroyed. Return a token, which
- /// can be used to remove said callback. Multiple callbacks can be added by
- /// calling this function multiple times, and will be invoked in FIFO order.
+ /// Add a callback for when the debugger is destroyed. Returns a token that
+ /// can be used to remove the callback.
lldb::callback_token_t
AddDestroyCallback(lldb::SBDebuggerDestroyCallback destroy_callback,
void *baton);
- /// Remove the specified callback. Return true if successful.
+ /// Remove a destroy callback.
bool RemoveDestroyCallback(lldb::callback_token_t token);
#ifndef SWIG
+ /// Dispatch input to the debugger (deprecated).
LLDB_DEPRECATED_FIXME("Use DispatchInput(const void *, size_t)",
"DispatchInput(const void *, size_t)")
void DispatchInput(void *baton, const void *data, size_t data_len);
#endif
+ /// Dispatch input to the debugger.
void DispatchInput(const void *data, size_t data_len);
+ /// Interrupt the current input dispatch.
void DispatchInputInterrupt();
+ /// Signal end-of-file to the current input dispatch.
void DispatchInputEndOfFile();
#ifndef SWIG
+ /// Push an input reader onto the IO handler stack.
void PushInputReader(lldb::SBInputReader &reader);
#endif
+ /// Get the instance name of this debugger.
const char *GetInstanceName();
+ /// Find a debugger by ID. Returns an invalid debugger if not found.
static SBDebugger FindDebuggerWithID(int id);
+ /// Set an internal variable.
static lldb::SBError SetInternalVariable(const char *var_name,
const char *value,
const char *debugger_instance_name);
+ /// Get the value of an internal variable.
static lldb::SBStringList
GetInternalVariableValue(const char *var_name,
const char *debugger_instance_name);
+ /// Get a description of this debugger.
bool GetDescription(lldb::SBStream &description);
+ /// Get the terminal width.
uint32_t GetTerminalWidth() const;
+ /// Set the terminal width.
void SetTerminalWidth(uint32_t term_width);
+ /// Get the terminal height.
uint32_t GetTerminalHeight() const;
+ /// Set the terminal height.
void SetTerminalHeight(uint32_t term_height);
+ /// Get the unique ID of this debugger.
lldb::user_id_t GetID();
+ /// Get the command prompt string.
const char *GetPrompt() const;
+ /// Set the command prompt string.
void SetPrompt(const char *prompt);
+ /// Get the path to the reproducer.
const char *GetReproducerPath() const;
+ /// Get the current scripting language.
lldb::ScriptLanguage GetScriptLanguage() const;
+ /// Set the current scripting language.
void SetScriptLanguage(lldb::ScriptLanguage script_lang);
+ /// Get the current REPL language.
lldb::LanguageType GetREPLLanguage() const;
+ /// Set the current REPL language.
void SetREPLLanguage(lldb::LanguageType repl_lang);
+ /// Get whether to close input on EOF (deprecated).
LLDB_DEPRECATED("SBDebugger::GetCloseInputOnEOF() is deprecated.")
bool GetCloseInputOnEOF() const;
+ /// Set whether to close input on EOF (deprecated).
LLDB_DEPRECATED("SBDebugger::SetCloseInputOnEOF() is deprecated.")
void SetCloseInputOnEOF(bool b);
+ /// Get a type category by name.
SBTypeCategory GetCategory(const char *category_name);
+ /// Get a type category by language.
SBTypeCategory GetCategory(lldb::LanguageType lang_type);
+ /// Create a new type category.
SBTypeCategory CreateCategory(const char *category_name);
+ /// Delete a type category.
bool DeleteCategory(const char *category_name);
+ /// Get the number of type categories.
uint32_t GetNumCategories();
- SBTypeCategory GetCategoryAtIndex(uint32_t);
+ /// Get a type category by index.
+ SBTypeCategory GetCategoryAtIndex(uint32_t index);
+ /// Get the default type category.
SBTypeCategory GetDefaultCategory();
- SBTypeFormat GetFormatForType(SBTypeNameSpecifier);
+ /// Get the format for a type.
+ SBTypeFormat GetFormatForType(SBTypeNameSpecifier type_name_spec);
- SBTypeSummary GetSummaryForType(SBTypeNameSpecifier);
+ /// Get the summary for a type.
+ SBTypeSummary GetSummaryForType(SBTypeNameSpecifier type_name_spec);
- SBTypeFilter GetFilterForType(SBTypeNameSpecifier);
+ /// Get the filter for a type.
+ SBTypeFilter GetFilterForType(SBTypeNameSpecifier type_name_spec);
- SBTypeSynthetic GetSyntheticForType(SBTypeNameSpecifier);
+ /// Get the synthetic for a type.
+ SBTypeSynthetic GetSyntheticForType(SBTypeNameSpecifier type_name_spec);
- /// Clear collected statistics for targets belonging to this debugger. This
- /// includes clearing symbol table and debug info parsing/index time for all
- /// modules, breakpoint resolve time and target statistics.
+ /// Clear collected statistics for targets belonging to this debugger.
+ ///
+ /// This includes clearing symbol table and debug info parsing/index time for
+ /// all modules, breakpoint resolve time, and target statistics.
void ResetStatistics();
#ifndef SWIG
/// Run the command interpreter.
///
/// \param[in] auto_handle_events
- /// If true, automatically handle resulting events. This takes precedence
- /// and overrides the corresponding option in
- /// SBCommandInterpreterRunOptions.
+ /// If true, automatically handle resulting events. This takes precedence
+ /// and overrides the corresponding option in
+ /// SBCommandInterpreterRunOptions.
///
/// \param[in] spawn_thread
- /// If true, start a new thread for IO handling. This takes precedence
- /// and overrides the corresponding option in
- /// SBCommandInterpreterRunOptions.
+ /// If true, start a new thread for IO handling. This takes precedence and
+ /// overrides the corresponding option in SBCommandInterpreterRunOptions.
void RunCommandInterpreter(bool auto_handle_events, bool spawn_thread);
#endif
- /// Run the command interpreter.
+ /// Run the command interpreter with options.
///
/// \param[in] auto_handle_events
- /// If true, automatically handle resulting events. This takes precedence
- /// and overrides the corresponding option in
- /// SBCommandInterpreterRunOptions.
+ /// If true, automatically handle resulting events. This takes precedence
+ /// and overrides the corresponding option in
+ /// SBCommandInterpreterRunOptions.
///
/// \param[in] spawn_thread
- /// If true, start a new thread for IO handling. This takes precedence
- /// and overrides the corresponding option in
- /// SBCommandInterpreterRunOptions.
+ /// If true, start a new thread for IO handling. This takes precedence and
+ /// overrides the corresponding option in SBCommandInterpreterRunOptions.
///
/// \param[in] options
- /// Parameter collection of type SBCommandInterpreterRunOptions.
+ /// Parameter collection of type SBCommandInterpreterRunOptions.
///
/// \param[out] num_errors
- /// The number of errors.
+ /// The number of errors.
///
/// \param[out] quit_requested
- /// Whether a quit was requested.
+ /// Whether a quit was requested.
///
/// \param[out] stopped_for_crash
- /// Whether the interpreter stopped for a crash.
+ /// Whether the interpreter stopped for a crash.
#ifdef SWIG
%apply int& INOUT { int& num_errors };
%apply bool& INOUT { bool& quit_requested };
@@ -497,20 +638,27 @@ class LLDB_API SBDebugger {
bool &stopped_for_crash);
#ifndef SWIG
+ /// Run the command interpreter with options and return a result object.
SBCommandInterpreterRunResult
RunCommandInterpreter(const SBCommandInterpreterRunOptions &options);
#endif
+ /// Run a REPL (Read-Eval-Print Loop) for the specified language.
SBError RunREPL(lldb::LanguageType language, const char *repl_options);
- /// Load a trace from a trace description file and create Targets,
- /// Processes and Threads based on the contents of such file.
+ /// Load a trace from a trace description file.
+ ///
+ /// This will create Targets, Processes and Threads based on the contents of
+ /// the file.
///
/// \param[out] error
/// An error if the trace could not be created.
///
/// \param[in] trace_description_file
/// The file containing the necessary information to load the trace.
+ ///
+ /// \return
+ /// An SBTrace object representing the loaded trace.
SBTrace LoadTraceFromFile(SBError &error,
const SBFileSpec &trace_description_file);
_______________________________________________
lldb-commits mailing list
lldb-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
