From af54eaf253b1840abb721c3e584d9936fad12c8a Mon Sep 17 00:00:00 2001 From: Jonas Devlieghere Date: Tue, 8 Jul 2025 16:37:20 -0700 Subject: [PATCH 1/4] [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 | 868 +++++++++++++++++++++++++++-- 1 file changed, 821 insertions(+), 47 deletions(-) diff --git a/lldb/include/lldb/API/SBDebugger.h b/lldb/include/lldb/API/SBDebugger.h index 192fbee9c0c6d..81e86d54a7998 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,33 @@ 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. + /// + /// \return The name of the broadcaster class. static const char *GetBroadcasterClass(); + /// Check if a specific language is supported by LLDB. + /// + /// \param [in] language + /// The language to check. + /// + /// \return + /// True if the language is supported, false otherwise. static bool SupportsLanguage(lldb::LanguageType language); + /// Get the broadcaster associated with this debugger. + /// + /// \return + /// A broadcaster object that allows subscribing to events from this + /// debugger. lldb::SBBroadcaster GetBroadcaster(); /// Get progress data from a SBEvent whose type is eBroadcastBitProgress. @@ -106,44 +124,122 @@ class LLDB_API SBDebugger { bool &is_debugger_specific); #endif + /// Get structured progress data from an event. + /// + /// \param [in] event + /// The event to extract the progress information from. + /// + /// \return + /// A structured data object containing progress information, or an invalid + /// SBStructuredData if the event was not a progress event. static lldb::SBStructuredData GetProgressDataFromEvent(const lldb::SBEvent &event); + /// Get diagnostic information from an event. + /// + /// \param [in] event + /// The event to extract the diagnostic information from. + /// + /// \return + /// A structured data object containing diagnostic information, or an + /// invalid SBStructuredData if the event was not a diagnostic 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. + /// + /// \return + /// An SBError object that indicates success or failure. 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). + /// + /// \return + /// A new SBDebugger object. LLDB_DEPRECATED_FIXME("Use one of the other Create variants", "Create(bool)") static lldb::SBDebugger Create(); + /// Create a new debugger instance. + /// + /// \param [in] source_init_files + /// If true, the debugger will source .lldbinit files from the home + /// directory and current directory. + /// + /// \return + /// A new SBDebugger object. static lldb::SBDebugger Create(bool source_init_files); + /// Create a new debugger instance with a custom log handler. + /// + /// \param [in] source_init_files + /// If true, the debugger will source .lldbinit files from the home + /// directory and current directory. + /// + /// \param [in] log_callback + /// A callback function to handle log messages. + /// + /// \param [in] baton + /// A user data pointer passed to the log callback function. + /// + /// \return + /// A new SBDebugger object. static lldb::SBDebugger Create(bool source_init_files, lldb::LogOutputCallback log_callback, void *baton); + /// Destroy a debugger instance. + /// + /// \param [in] debugger + /// The debugger instance to destroy. 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. + /// + /// \return + /// True if this object is valid, false otherwise. explicit operator bool() const; + /// Check if this is a valid SBDebugger object. + /// + /// \return + /// True if this object is valid, false otherwise. 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: @@ -153,70 +249,221 @@ class LLDB_API SBDebugger { /// lldb::SBStructuredData settings = debugger.GetSetting("target.arg0"); /// lldb::SBStructuredData settings = debugger.GetSetting("target"); /// - /// \param[out] setting + /// \param[in] setting /// Property setting path to retrieve values. e.g "target.source-map" /// + /// \return + /// An SBStructuredData object containing the requested settings. 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. + /// + /// \param [in] b + /// True to enable asynchronous mode, false for synchronous mode. void SetAsync(bool b); + /// Get whether the debugger is running in asynchronous mode. + /// + /// \return + /// True if the debugger is in asynchronous mode, false otherwise. bool GetAsync(); + /// Set whether to skip loading .lldbinit files. + /// + /// \param [in] b + /// True to skip loading LLDB init files, false to load them. void SkipLLDBInitFiles(bool b); + /// Set whether to skip loading application-specific .lldbinit files. + /// + /// \param [in] b + /// True to skip loading application init files, false to load them. void SkipAppInitFiles(bool b); #ifndef SWIG + /// Set the input file handle for the debugger. + /// + /// \param [in] f + /// The file handle to use for input. + /// + /// \param [in] transfer_ownership + /// If true, the debugger takes ownership of the file handle. void SetInputFileHandle(FILE *f, bool transfer_ownership); + /// Set the output file handle for the debugger. + /// + /// \param [in] f + /// The file handle to use for output. + /// + /// \param [in] transfer_ownership + /// If true, the debugger takes ownership of the file handle. void SetOutputFileHandle(FILE *f, bool transfer_ownership); + /// Set the error file handle for the debugger. + /// + /// \param [in] f + /// The file handle to use for error output. + /// + /// \param [in] transfer_ownership + /// If true, the debugger takes ownership of the file handle. void SetErrorFileHandle(FILE *f, bool transfer_ownership); #endif #ifndef SWIG + /// Get the input file handle for the debugger. + /// + /// \return + /// The current input file handle. FILE *GetInputFileHandle(); + /// Get the output file handle for the debugger. + /// + /// \return + /// The current output file handle. FILE *GetOutputFileHandle(); + /// Get the error file handle for the debugger. + /// + /// \return + /// The current error file handle. FILE *GetErrorFileHandle(); #endif + /// Set the input from a string. + /// + /// \param [in] data + /// The string to use as input. + /// + /// \return + /// An SBError object indicating success or failure. SBError SetInputString(const char *data); + /// Set the input file for the debugger. + /// + /// \param [in] file + /// The file to use for input. + /// + /// \return + /// An SBError object indicating success or failure. SBError SetInputFile(SBFile file); + /// Set the output file for the debugger. + /// + /// \param [in] file + /// The file to use for output. + /// + /// \return + /// An SBError object indicating success or failure. SBError SetOutputFile(SBFile file); + /// Set the error file for the debugger. + /// + /// \param [in] file + /// The file to use for error output. + /// + /// \return + /// An SBError object indicating success or failure. SBError SetErrorFile(SBFile file); + /// Set the input file for the debugger using a FileSP. + /// + /// \param [in] file + /// The file to use for input. + /// + /// \return + /// An SBError object indicating success or failure. SBError SetInputFile(FileSP file); + /// Set the output file for the debugger using a FileSP. + /// + /// \param [in] file + /// The file to use for output. + /// + /// \return + /// An SBError object indicating success or failure. SBError SetOutputFile(FileSP file); + /// Set the error file for the debugger using a FileSP. + /// + /// \param [in] file + /// The file to use for error output. + /// + /// \return + /// An SBError object indicating success or failure. SBError SetErrorFile(FileSP file); + /// Get the input file for the debugger. + /// + /// \return + /// The current input file. SBFile GetInputFile(); + /// Get the output file for the debugger. + /// + /// \return + /// The current output file. SBFile GetOutputFile(); + /// Get the error file for the debugger. + /// + /// \return + /// The current error file. 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. + /// + /// \return + /// The command interpreter object. lldb::SBCommandInterpreter GetCommandInterpreter(); + /// Execute a command in the command interpreter. + /// + /// \param [in] command + /// The command to execute. 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. + /// + /// \return + /// True if an interrupt has been requested, false otherwise. bool InterruptRequested(); + /// Get the listener associated with this debugger. + /// + /// \return + /// The listener object. lldb::SBListener GetListener(); #ifndef SWIG + /// Handle a process event (deprecated). + /// + /// \param [in] process + /// The process that generated the event. + /// + /// \param [in] event + /// The event to handle. + /// + /// \param [in] out + /// The file to write standard output to. + /// + /// \param [in] err + /// The file to write error output to. LLDB_DEPRECATED_FIXME( "Use HandleProcessEvent(const SBProcess &, const SBEvent &, SBFile, " "SBFile) or HandleProcessEvent(const SBProcess &, const SBEvent &, " @@ -226,266 +473,770 @@ class LLDB_API SBDebugger { const lldb::SBEvent &event, FILE *out, FILE *err); #endif + /// Handle a process event. + /// + /// \param [in] process + /// The process that generated the event. + /// + /// \param [in] event + /// The event to handle. + /// + /// \param [in] out + /// The file to write standard output to. + /// + /// \param [in] err + /// The file to write error output to. void HandleProcessEvent(const lldb::SBProcess &process, const lldb::SBEvent &event, SBFile out, SBFile err); #ifdef SWIG + /// Handle a process event using FileSP objects. + /// + /// \param [in] process + /// The process that generated the event. + /// + /// \param [in] event + /// The event to handle. + /// + /// \param [in] out + /// The file to write standard output to. + /// + /// \param [in] err + /// The file to write error output to. void HandleProcessEvent(const lldb::SBProcess &process, const lldb::SBEvent &event, FileSP BORROWED, FileSP BORROWED); #else + /// Handle a process event using FileSP objects. + /// + /// \param [in] process + /// The process that generated the event. + /// + /// \param [in] event + /// The event to handle. + /// + /// \param [in] out + /// The file to write standard output to. + /// + /// \param [in] err + /// The file to write error output to. void HandleProcessEvent(const lldb::SBProcess &process, const lldb::SBEvent &event, FileSP out, FileSP err); #endif + /// Create a target with the specified parameters. + /// + /// \param [in] filename + /// The name of the executable file to debug. + /// + /// \param [in] target_triple + /// The target triple string (e.g., "x86_64-apple-macosx"). + /// + /// \param [in] platform_name + /// The name of the platform to use. + /// + /// \param [in] add_dependent_modules + /// Whether to add dependent modules to the target. + /// + /// \param [out] error + /// An SBError object that will be set if there is an error. + /// + /// \return + /// An SBTarget object. 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. + /// + /// \param [in] filename + /// The name of the executable file to debug. + /// + /// \param [in] target_triple + /// The target triple string (e.g., "x86_64-apple-macosx"). + /// + /// \return + /// An SBTarget object. lldb::SBTarget CreateTargetWithFileAndTargetTriple(const char *filename, const char *target_triple); + /// Create a target with the specified file and architecture. + /// + /// \param [in] filename + /// The name of the executable file to debug. + /// + /// \param [in] archname + /// The name of the architecture (e.g., "x86_64"). + /// + /// \return + /// An SBTarget object. lldb::SBTarget CreateTargetWithFileAndArch(const char *filename, const char *archname); + /// Create a target with the specified file. + /// + /// \param [in] filename + /// The name of the executable file to debug. + /// + /// \return + /// An SBTarget object. lldb::SBTarget CreateTarget(const char *filename); + /// Get the dummy target. + /// + /// The dummy target is used when no target is available. + /// + /// \return + /// The dummy target. 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. + /// + /// \param [in] data + /// The telemetry data to dispatch. 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. + /// + /// \param [in] target + /// The target to delete. + /// + /// \return + /// True if the target was successfully deleted, false otherwise. bool DeleteTarget(lldb::SBTarget &target); + /// Get a target by index. + /// + /// \param [in] idx + /// The index of the target to retrieve. + /// + /// \return + /// The target at the specified index. lldb::SBTarget GetTargetAtIndex(uint32_t idx); + /// Get the index of a target. + /// + /// \param [in] target + /// The target to find the index of. + /// + /// \return + /// The index of the target, or UINT32_MAX if not found. uint32_t GetIndexOfTarget(lldb::SBTarget target); + /// Find a target with the specified process ID. + /// + /// \param [in] pid + /// The process ID to search for. + /// + /// \return + /// The target with the specified process ID, or an invalid target if not + /// found. lldb::SBTarget FindTargetWithProcessID(lldb::pid_t pid); + /// Find a target with the specified file and architecture. + /// + /// \param [in] filename + /// The name of the executable file. + /// + /// \param [in] arch + /// The name of the architecture. + /// + /// \return + /// The target with the specified file and architecture, or an invalid + /// target if not found. lldb::SBTarget FindTargetWithFileAndArch(const char *filename, const char *arch); + /// Get the number of targets in the debugger. + /// + /// \return + /// The number of targets. uint32_t GetNumTargets(); + /// Get the currently selected target. + /// + /// \return + /// The selected target. lldb::SBTarget GetSelectedTarget(); + /// Set the selected target. + /// + /// \param [in] target + /// The target to select. void SetSelectedTarget(SBTarget &target); + /// Get the selected platform. + /// + /// \return + /// The selected platform. lldb::SBPlatform GetSelectedPlatform(); + /// Set the selected platform. + /// + /// \param [in] platform + /// The platform to select. void SetSelectedPlatform(lldb::SBPlatform &platform); /// Get the number of currently active platforms. + /// + /// \return + /// The number of active platforms. uint32_t GetNumPlatforms(); /// Get one of the currently active platforms. + /// + /// \param [in] idx + /// The index of the platform to retrieve. + /// + /// \return + /// The platform at the specified index. lldb::SBPlatform GetPlatformAtIndex(uint32_t idx); /// Get the number of available platforms. /// /// The return value should match the number of entries output by the /// "platform list" command. + /// + /// \return + /// The number of available platforms. 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. + /// + /// \return + /// The source manager object. 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. + /// + /// \param [in] input + /// True to use an external editor, false otherwise. + /// + /// \return + /// True if the setting was successfully changed, false otherwise. bool SetUseExternalEditor(bool input); + /// Get whether an external editor is being used. + /// + /// \return + /// True if an external editor is being used, false otherwise. bool GetUseExternalEditor(); + /// Set whether to use color in output. + /// + /// \param [in] use_color + /// True to use color, false otherwise. + /// + /// \return + /// True if the setting was successfully changed, false otherwise. bool SetUseColor(bool use_color); + /// Get whether color is being used in output. + /// + /// \return + /// True if color is being used, false otherwise. bool GetUseColor() const; - bool SetShowInlineDiagnostics(bool); + /// Set whether to show inline diagnostics. + /// + /// \param [in] b + /// True to show inline diagnostics, false otherwise. + /// + /// \return + /// True if the setting was successfully changed, false otherwise. + bool SetShowInlineDiagnostics(bool b); + /// Set whether to use the source cache. + /// + /// \param [in] use_source_cache + /// True to use the source cache, false otherwise. + /// + /// \return + /// True if the setting was successfully changed, false otherwise. bool SetUseSourceCache(bool use_source_cache); + /// Get whether the source cache is being used. + /// + /// \return + /// True if the source cache is being used, false otherwise. 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. + /// + /// \param [in] arch_name + /// The name of the architecture to set as default. + /// + /// \return + /// True if the default architecture was successfully set, false otherwise. static bool SetDefaultArchitecture(const char *arch_name); + /// Get the scripting language by name. + /// + /// \param [in] script_language_name + /// The name of the scripting language. + /// + /// \return + /// The scripting language enum value. 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. + /// + /// \return + /// The version string. static const char *GetVersionString(); + /// Convert a state type to a string. + /// + /// \param [in] state + /// The state type to convert. + /// + /// \return + /// A string representation of the state. 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. + /// + /// \param [in] state + /// The state to check. + /// + /// \return + /// True if the state is a running state, false otherwise. static bool StateIsRunningState(lldb::StateType state); + /// Check if a state is a stopped state. + /// + /// \param [in] state + /// The state to check. + /// + /// \return + /// True if the state is a stopped state, false otherwise. 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. + /// + /// \param [in] reader + /// The input reader to push. void PushInputReader(lldb::SBInputReader &reader); #endif + /// Get the instance name of this debugger. + /// + /// \return + /// The instance name. 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. + /// + /// \return + /// The terminal width in characters. uint32_t GetTerminalWidth() const; + /// Set the terminal width. + /// + /// \param [in] term_width + /// The terminal width in characters. void SetTerminalWidth(uint32_t term_width); + /// Get the terminal height. + /// + /// \return + /// The terminal height in characters. uint32_t GetTerminalHeight() const; + /// Set the terminal height. + /// + /// \param [in] term_height + /// The terminal height in characters. void SetTerminalHeight(uint32_t term_height); + /// Get the unique ID of this debugger. + /// + /// \return + /// The debugger ID. lldb::user_id_t GetID(); + /// Get the command prompt string. + /// + /// \return + /// The prompt string. const char *GetPrompt() const; + /// Set the command prompt string. + /// + /// \param [in] prompt + /// The new prompt string. void SetPrompt(const char *prompt); + /// Get the path to the reproducer. + /// + /// \return + /// The path to the reproducer, or nullptr if no reproducer is active. const char *GetReproducerPath() const; + /// Get the current scripting language. + /// + /// \return + /// The current scripting language. lldb::ScriptLanguage GetScriptLanguage() const; + /// Set the current scripting language. + /// + /// \param [in] script_lang + /// The scripting language to set. void SetScriptLanguage(lldb::ScriptLanguage script_lang); + /// Get the current REPL language. + /// + /// \return + /// The current REPL language. lldb::LanguageType GetREPLLanguage() const; + /// Set the current REPL language. + /// + /// \param [in] repl_lang + /// The REPL language to set. 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. + /// + /// \param [in] category_name + /// The name of the category to get. + /// + /// \return + /// The type category with the specified name. SBTypeCategory GetCategory(const char *category_name); + /// Get a type category by language. + /// + /// \param [in] lang_type + /// The language type to get the category for. + /// + /// \return + /// The type category for the specified language. SBTypeCategory GetCategory(lldb::LanguageType lang_type); + /// Create a new type category. + /// + /// \param [in] category_name + /// The name of the category to create. + /// + /// \return + /// The newly created type category. SBTypeCategory CreateCategory(const char *category_name); + /// Delete a type category. + /// + /// \param [in] category_name + /// The name of the category to delete. + /// + /// \return + /// True if the category was successfully deleted, false otherwise. bool DeleteCategory(const char *category_name); + /// Get the number of type categories. + /// + /// \return + /// The number of type categories. uint32_t GetNumCategories(); - SBTypeCategory GetCategoryAtIndex(uint32_t); + /// Get a type category by index. + /// + /// \param [in] index + /// The index of the category to get. + /// + /// \return + /// The type category at the specified index. + SBTypeCategory GetCategoryAtIndex(uint32_t index); + /// Get the default type category. + /// + /// \return + /// The default type category. SBTypeCategory GetDefaultCategory(); - SBTypeFormat GetFormatForType(SBTypeNameSpecifier); + /// Get the format for a type. + /// + /// \param [in] type_name_spec + /// The type name specifier. + /// + /// \return + /// The format for the specified type. + SBTypeFormat GetFormatForType(SBTypeNameSpecifier type_name_spec); - SBTypeSummary GetSummaryForType(SBTypeNameSpecifier); + /// Get the summary for a type. + /// + /// \param [in] type_name_spec + /// The type name specifier. + /// + /// \return + /// The summary for the specified type. + SBTypeSummary GetSummaryForType(SBTypeNameSpecifier type_name_spec); - SBTypeFilter GetFilterForType(SBTypeNameSpecifier); + /// Get the filter for a type. + /// + /// \param [in] type_name_spec + /// The type name specifier. + /// + /// \return + /// The filter for the specified type. + SBTypeFilter GetFilterForType(SBTypeNameSpecifier type_name_spec); - SBTypeSynthetic GetSyntheticForType(SBTypeNameSpecifier); + /// Get the synthetic for a type. + /// + /// \param [in] type_name_spec + /// The type name specifier. + /// + /// \return + /// The synthetic for the specified 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 +1248,43 @@ class LLDB_API SBDebugger { bool &stopped_for_crash); #ifndef SWIG + /// Run the command interpreter with options and return a result object. + /// + /// \param[in] options + /// Parameter collection of type SBCommandInterpreterRunOptions. + /// + /// \return + /// An SBCommandInterpreterRunResult object containing the result of running + /// the command interpreter. SBCommandInterpreterRunResult RunCommandInterpreter(const SBCommandInterpreterRunOptions &options); #endif + /// Run a REPL (Read-Eval-Print Loop) for the specified language. + /// + /// \param[in] language + /// The language to use for the REPL. + /// + /// \param[in] repl_options + /// Options for the REPL. + /// + /// \return + /// An SBError object indicating success or failure. 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); From b4e11354cb3ebc0cebdfb11751eaab32ec6f2975 Mon Sep 17 00:00:00 2001 From: Jonas Devlieghere Date: Wed, 9 Jul 2025 09:58:05 -0700 Subject: [PATCH 2/4] Use single line comments for getters and setters --- lldb/include/lldb/API/SBDebugger.h | 278 +---------------------------- 1 file changed, 1 insertion(+), 277 deletions(-) diff --git a/lldb/include/lldb/API/SBDebugger.h b/lldb/include/lldb/API/SBDebugger.h index 81e86d54a7998..7b9899ffb5b4e 100644 --- a/lldb/include/lldb/API/SBDebugger.h +++ b/lldb/include/lldb/API/SBDebugger.h @@ -124,7 +124,7 @@ class LLDB_API SBDebugger { bool &is_debugger_specific); #endif - /// Get structured progress data from an event. + /// Get progress data from an event. /// /// \param [in] event /// The event to extract the progress information from. @@ -284,132 +284,54 @@ class LLDB_API SBDebugger { #ifndef SWIG /// Set the input file handle for the debugger. - /// - /// \param [in] f - /// The file handle to use for input. - /// - /// \param [in] transfer_ownership - /// If true, the debugger takes ownership of the file handle. void SetInputFileHandle(FILE *f, bool transfer_ownership); /// Set the output file handle for the debugger. - /// - /// \param [in] f - /// The file handle to use for output. - /// - /// \param [in] transfer_ownership - /// If true, the debugger takes ownership of the file handle. void SetOutputFileHandle(FILE *f, bool transfer_ownership); /// Set the error file handle for the debugger. - /// - /// \param [in] f - /// The file handle to use for error output. - /// - /// \param [in] transfer_ownership - /// If true, the debugger takes ownership of the file handle. void SetErrorFileHandle(FILE *f, bool transfer_ownership); #endif #ifndef SWIG /// Get the input file handle for the debugger. - /// - /// \return - /// The current input file handle. FILE *GetInputFileHandle(); /// Get the output file handle for the debugger. - /// - /// \return - /// The current output file handle. FILE *GetOutputFileHandle(); /// Get the error file handle for the debugger. - /// - /// \return - /// The current error file handle. FILE *GetErrorFileHandle(); #endif /// Set the input from a string. - /// - /// \param [in] data - /// The string to use as input. - /// - /// \return - /// An SBError object indicating success or failure. SBError SetInputString(const char *data); /// Set the input file for the debugger. - /// - /// \param [in] file - /// The file to use for input. - /// - /// \return - /// An SBError object indicating success or failure. SBError SetInputFile(SBFile file); /// Set the output file for the debugger. - /// - /// \param [in] file - /// The file to use for output. - /// - /// \return - /// An SBError object indicating success or failure. SBError SetOutputFile(SBFile file); /// Set the error file for the debugger. - /// - /// \param [in] file - /// The file to use for error output. - /// - /// \return - /// An SBError object indicating success or failure. SBError SetErrorFile(SBFile file); /// Set the input file for the debugger using a FileSP. - /// - /// \param [in] file - /// The file to use for input. - /// - /// \return - /// An SBError object indicating success or failure. SBError SetInputFile(FileSP file); /// Set the output file for the debugger using a FileSP. - /// - /// \param [in] file - /// The file to use for output. - /// - /// \return - /// An SBError object indicating success or failure. SBError SetOutputFile(FileSP file); /// Set the error file for the debugger using a FileSP. - /// - /// \param [in] file - /// The file to use for error output. - /// - /// \return - /// An SBError object indicating success or failure. SBError SetErrorFile(FileSP file); /// Get the input file for the debugger. - /// - /// \return - /// The current input file. SBFile GetInputFile(); /// Get the output file for the debugger. - /// - /// \return - /// The current output file. SBFile GetOutputFile(); /// Get the error file for the debugger. - /// - /// \return - /// The current error file. SBFile GetErrorFile(); /// Save the current terminal state. @@ -421,9 +343,6 @@ class LLDB_API SBDebugger { void RestoreInputTerminalState(); /// Get the command interpreter for this debugger. - /// - /// \return - /// The command interpreter object. lldb::SBCommandInterpreter GetCommandInterpreter(); /// Execute a command in the command interpreter. @@ -445,9 +364,6 @@ class LLDB_API SBDebugger { bool InterruptRequested(); /// Get the listener associated with this debugger. - /// - /// \return - /// The listener object. lldb::SBListener GetListener(); #ifndef SWIG @@ -652,39 +568,21 @@ class LLDB_API SBDebugger { const char *arch); /// Get the number of targets in the debugger. - /// - /// \return - /// The number of targets. uint32_t GetNumTargets(); /// Get the currently selected target. - /// - /// \return - /// The selected target. lldb::SBTarget GetSelectedTarget(); /// Set the selected target. - /// - /// \param [in] target - /// The target to select. void SetSelectedTarget(SBTarget &target); /// Get the selected platform. - /// - /// \return - /// The selected platform. lldb::SBPlatform GetSelectedPlatform(); /// Set the selected platform. - /// - /// \param [in] platform - /// The platform to select. void SetSelectedPlatform(lldb::SBPlatform &platform); /// Get the number of currently active platforms. - /// - /// \return - /// The number of active platforms. uint32_t GetNumPlatforms(); /// Get one of the currently active platforms. @@ -700,9 +598,6 @@ class LLDB_API SBDebugger { /// /// The return value should match the number of entries output by the /// "platform list" command. - /// - /// \return - /// The number of available platforms. uint32_t GetNumAvailablePlatforms(); /// Get information about one of the available platforms. @@ -716,9 +611,6 @@ class LLDB_API SBDebugger { lldb::SBStructuredData GetAvailablePlatformInfoAtIndex(uint32_t idx); /// Get the source manager for this debugger. - /// - /// \return - /// The source manager object. lldb::SBSourceManager GetSourceManager(); /// Set the current platform by name. @@ -740,57 +632,24 @@ class LLDB_API SBDebugger { bool SetCurrentPlatformSDKRoot(const char *sysroot); /// Set whether to use an external editor. - /// - /// \param [in] input - /// True to use an external editor, false otherwise. - /// - /// \return - /// True if the setting was successfully changed, false otherwise. bool SetUseExternalEditor(bool input); /// Get whether an external editor is being used. - /// - /// \return - /// True if an external editor is being used, false otherwise. bool GetUseExternalEditor(); /// Set whether to use color in output. - /// - /// \param [in] use_color - /// True to use color, false otherwise. - /// - /// \return - /// True if the setting was successfully changed, false otherwise. bool SetUseColor(bool use_color); /// Get whether color is being used in output. - /// - /// \return - /// True if color is being used, false otherwise. bool GetUseColor() const; /// Set whether to show inline diagnostics. - /// - /// \param [in] b - /// True to show inline diagnostics, false otherwise. - /// - /// \return - /// True if the setting was successfully changed, false otherwise. bool SetShowInlineDiagnostics(bool b); /// Set whether to use the source cache. - /// - /// \param [in] use_source_cache - /// True to use the source cache, false otherwise. - /// - /// \return - /// True if the setting was successfully changed, false otherwise. bool SetUseSourceCache(bool use_source_cache); /// Get whether the source cache is being used. - /// - /// \return - /// True if the source cache is being used, false otherwise. bool GetUseSourceCache() const; /// Get the default architecture. @@ -807,21 +666,9 @@ class LLDB_API SBDebugger { static bool GetDefaultArchitecture(char *arch_name, size_t arch_name_len); /// Set the default architecture. - /// - /// \param [in] arch_name - /// The name of the architecture to set as default. - /// - /// \return - /// True if the default architecture was successfully set, false otherwise. static bool SetDefaultArchitecture(const char *arch_name); /// Get the scripting language by name. - /// - /// \param [in] script_language_name - /// The name of the scripting language. - /// - /// \return - /// The scripting language enum value. lldb::ScriptLanguage GetScriptingLanguage(const char *script_language_name); /// Get information about a script interpreter. @@ -834,18 +681,9 @@ class LLDB_API SBDebugger { SBStructuredData GetScriptInterpreterInfo(ScriptLanguage language); /// Get the LLDB version string. - /// - /// \return - /// The version string. static const char *GetVersionString(); /// Convert a state type to a string. - /// - /// \param [in] state - /// The state type to convert. - /// - /// \return - /// A string representation of the state. static const char *StateAsCString(lldb::StateType state); /// Get the build configuration. @@ -855,21 +693,9 @@ class LLDB_API SBDebugger { static SBStructuredData GetBuildConfiguration(); /// Check if a state is a running state. - /// - /// \param [in] state - /// The state to check. - /// - /// \return - /// True if the state is a running state, false otherwise. static bool StateIsRunningState(lldb::StateType state); /// Check if a state is a stopped state. - /// - /// \param [in] state - /// The state to check. - /// - /// \return - /// True if the state is a stopped state, false otherwise. static bool StateIsStoppedState(lldb::StateType state); /// Enable logging for a specific channel. @@ -961,16 +787,10 @@ class LLDB_API SBDebugger { #ifndef SWIG /// Push an input reader onto the IO handler stack. - /// - /// \param [in] reader - /// The input reader to push. void PushInputReader(lldb::SBInputReader &reader); #endif /// Get the instance name of this debugger. - /// - /// \return - /// The instance name. const char *GetInstanceName(); /// Find a debugger by ID. @@ -1023,75 +843,39 @@ class LLDB_API SBDebugger { bool GetDescription(lldb::SBStream &description); /// Get the terminal width. - /// - /// \return - /// The terminal width in characters. uint32_t GetTerminalWidth() const; /// Set the terminal width. - /// - /// \param [in] term_width - /// The terminal width in characters. void SetTerminalWidth(uint32_t term_width); /// Get the terminal height. - /// - /// \return - /// The terminal height in characters. uint32_t GetTerminalHeight() const; /// Set the terminal height. - /// - /// \param [in] term_height - /// The terminal height in characters. void SetTerminalHeight(uint32_t term_height); /// Get the unique ID of this debugger. - /// - /// \return - /// The debugger ID. lldb::user_id_t GetID(); /// Get the command prompt string. - /// - /// \return - /// The prompt string. const char *GetPrompt() const; /// Set the command prompt string. - /// - /// \param [in] prompt - /// The new prompt string. void SetPrompt(const char *prompt); /// Get the path to the reproducer. - /// - /// \return - /// The path to the reproducer, or nullptr if no reproducer is active. const char *GetReproducerPath() const; /// Get the current scripting language. - /// - /// \return - /// The current scripting language. lldb::ScriptLanguage GetScriptLanguage() const; /// Set the current scripting language. - /// - /// \param [in] script_lang - /// The scripting language to set. void SetScriptLanguage(lldb::ScriptLanguage script_lang); /// Get the current REPL language. - /// - /// \return - /// The current REPL language. lldb::LanguageType GetREPLLanguage() const; /// Set the current REPL language. - /// - /// \param [in] repl_lang - /// The REPL language to set. void SetREPLLanguage(lldb::LanguageType repl_lang); /// Get whether to close input on EOF (deprecated). @@ -1103,96 +887,36 @@ class LLDB_API SBDebugger { void SetCloseInputOnEOF(bool b); /// Get a type category by name. - /// - /// \param [in] category_name - /// The name of the category to get. - /// - /// \return - /// The type category with the specified name. SBTypeCategory GetCategory(const char *category_name); /// Get a type category by language. - /// - /// \param [in] lang_type - /// The language type to get the category for. - /// - /// \return - /// The type category for the specified language. SBTypeCategory GetCategory(lldb::LanguageType lang_type); /// Create a new type category. - /// - /// \param [in] category_name - /// The name of the category to create. - /// - /// \return - /// The newly created type category. SBTypeCategory CreateCategory(const char *category_name); /// Delete a type category. - /// - /// \param [in] category_name - /// The name of the category to delete. - /// - /// \return - /// True if the category was successfully deleted, false otherwise. bool DeleteCategory(const char *category_name); /// Get the number of type categories. - /// - /// \return - /// The number of type categories. uint32_t GetNumCategories(); /// Get a type category by index. - /// - /// \param [in] index - /// The index of the category to get. - /// - /// \return - /// The type category at the specified index. SBTypeCategory GetCategoryAtIndex(uint32_t index); /// Get the default type category. - /// - /// \return - /// The default type category. SBTypeCategory GetDefaultCategory(); /// Get the format for a type. - /// - /// \param [in] type_name_spec - /// The type name specifier. - /// - /// \return - /// The format for the specified type. SBTypeFormat GetFormatForType(SBTypeNameSpecifier type_name_spec); /// Get the summary for a type. - /// - /// \param [in] type_name_spec - /// The type name specifier. - /// - /// \return - /// The summary for the specified type. SBTypeSummary GetSummaryForType(SBTypeNameSpecifier type_name_spec); /// Get the filter for a type. - /// - /// \param [in] type_name_spec - /// The type name specifier. - /// - /// \return - /// The filter for the specified type. SBTypeFilter GetFilterForType(SBTypeNameSpecifier type_name_spec); /// Get the synthetic for a type. - /// - /// \param [in] type_name_spec - /// The type name specifier. - /// - /// \return - /// The synthetic for the specified type. SBTypeSynthetic GetSyntheticForType(SBTypeNameSpecifier type_name_spec); /// Clear collected statistics for targets belonging to this debugger. From 33e3b8ff73e5d6215265ba5c3010b4a4b6a0e270 Mon Sep 17 00:00:00 2001 From: Jonas Devlieghere Date: Wed, 9 Jul 2025 09:59:42 -0700 Subject: [PATCH 3/4] Simplify two more functions --- lldb/include/lldb/API/SBDebugger.h | 6 ------ 1 file changed, 6 deletions(-) diff --git a/lldb/include/lldb/API/SBDebugger.h b/lldb/include/lldb/API/SBDebugger.h index 7b9899ffb5b4e..72700e082a564 100644 --- a/lldb/include/lldb/API/SBDebugger.h +++ b/lldb/include/lldb/API/SBDebugger.h @@ -221,15 +221,9 @@ class LLDB_API SBDebugger { static void MemoryPressureDetected(); /// Check if this is a valid SBDebugger object. - /// - /// \return - /// True if this object is valid, false otherwise. explicit operator bool() const; /// Check if this is a valid SBDebugger object. - /// - /// \return - /// True if this object is valid, false otherwise. bool IsValid() const; /// Clear this debugger instance. From 4fb7553ad97e3a340e4b5575e775483fc26906ed Mon Sep 17 00:00:00 2001 From: Jonas Devlieghere Date: Wed, 9 Jul 2025 12:15:54 -0700 Subject: [PATCH 4/4] Comma d'Oxford --- lldb/include/lldb/API/SBDebugger.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lldb/include/lldb/API/SBDebugger.h b/lldb/include/lldb/API/SBDebugger.h index 72700e082a564..7419db2f3c398 100644 --- a/lldb/include/lldb/API/SBDebugger.h +++ b/lldb/include/lldb/API/SBDebugger.h @@ -916,7 +916,7 @@ class LLDB_API SBDebugger { /// 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. + /// all modules, breakpoint resolve time, and target statistics. void ResetStatistics(); #ifndef SWIG