[Lldb-commits] [lldb] [lldb] Document the SBDebugger public interface (PR #147621)
Alex Langford via lldb-commits
lldb-commits at lists.llvm.org
Wed Jul 9 10:51:53 PDT 2025
================
@@ -292,200 +594,367 @@ class LLDB_API SBDebugger {
/// "platform list" command.
uint32_t GetNumAvailablePlatforms();
- /// Get the name and description of one of the available platforms.
+ /// Get information about 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().
+ /// Zero-based index of the platform for which info should be retrieved,
+ /// must be less than the value returned by GetNumAvailablePlatforms().
+ ///
+ /// \return
+ /// A structured data object containing platform information.
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.
+ ///
+ /// \param [in] platform_name
+ /// The name of the platform to set as current.
+ ///
+ /// \return
+ /// An SBError object indicating success or failure.
lldb::SBError SetCurrentPlatform(const char *platform_name);
+ /// Set the SDK root for the current platform.
+ ///
+ /// \param [in] sysroot
+ /// The path to the SDK root.
+ ///
+ /// \return
+ /// True if the SDK root was successfully set, false otherwise.
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.
+ ///
+ /// \param [out] arch_name
+ /// A buffer to store the architecture name.
+ ///
+ /// \param [in] arch_name_len
+ /// The size of the buffer.
+ ///
+ /// \return
+ /// True if the default architecture was successfully retrieved, false
+ /// otherwise.
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.
+ ///
+ /// \param [in] language
+ /// The scripting language to get information about.
+ ///
+ /// \return
+ /// A structured data object containing script interpreter information.
+ 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.
+ ///
+ /// \return
+ /// A structured data object containing build configuration information.
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.
+ ///
+ /// \param [in] channel
+ /// The name of the channel to enable.
+ ///
+ /// \param [in] categories
+ /// An array of category names to enable, terminated by nullptr.
+ ///
+ /// \return
+ /// True if logging was successfully enabled, false otherwise.
bool EnableLog(const char *channel, const char **categories);
+ /// Set a callback for log output.
+ ///
+ /// \param [in] log_callback
+ /// The callback function to handle log output.
+ ///
+ /// \param [in] baton
+ /// A user data pointer passed to the callback function.
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).
+ ///
+ /// \param [in] destroy_callback
+ /// The callback function to call when the debugger is destroyed.
+ ///
+ /// \param [in] baton
+ /// A user data pointer passed to the callback function.
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.
+ ///
+ /// \param [in] destroy_callback
+ /// The callback function to call when the debugger is destroyed.
+ ///
+ /// \param [in] baton
+ /// A user data pointer passed to the callback function.
+ ///
+ /// \return
+ /// 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.
+ ///
+ /// \param [in] token
+ /// The token returned from AddDestroyCallback.
+ ///
+ /// \return
+ /// True if the callback was successfully removed, false otherwise.
bool RemoveDestroyCallback(lldb::callback_token_t token);
#ifndef SWIG
+ /// Dispatch input to the debugger (deprecated).
+ ///
+ /// \param [in] baton
+ /// A user data pointer.
+ ///
+ /// \param [in] data
+ /// The input data.
+ ///
+ /// \param [in] data_len
+ /// The length of the input data.
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.
+ ///
+ /// \param [in] data
+ /// The input data.
+ ///
+ /// \param [in] data_len
+ /// The length of the input data.
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.
+ ///
+ /// \param [in] id
+ /// The ID of the debugger to find.
+ ///
+ /// \return
+ /// The debugger with the specified ID, or an invalid debugger if not found.
static SBDebugger FindDebuggerWithID(int id);
+ /// Set an internal variable.
+ ///
+ /// \param [in] var_name
+ /// The name of the variable to set.
+ ///
+ /// \param [in] value
+ /// The value to set.
+ ///
+ /// \param [in] debugger_instance_name
+ /// The name of the debugger instance to set the variable in.
+ ///
+ /// \return
+ /// An SBError object indicating success or failure.
static lldb::SBError SetInternalVariable(const char *var_name,
const char *value,
const char *debugger_instance_name);
+ /// Get the value of an internal variable.
+ ///
+ /// \param [in] var_name
+ /// The name of the variable to get.
+ ///
+ /// \param [in] debugger_instance_name
+ /// The name of the debugger instance to get the variable from.
+ ///
+ /// \return
+ /// A string list containing the variable value.
static lldb::SBStringList
GetInternalVariableValue(const char *var_name,
const char *debugger_instance_name);
+ /// Get a description of this debugger.
+ ///
+ /// \param [out] description
+ /// A stream to write the description to.
+ ///
+ /// \return
+ /// True if the description was successfully written, false otherwise.
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.
----------------
bulbazord wrote:
nit: Oxford comma? 😄
https://github.com/llvm/llvm-project/pull/147621
More information about the lldb-commits
mailing list