Create an interface file for SBTarget named SBTarget.i which relieves SBTarget.h
of the duty of having SWIG docstring features and multiline string literals
embedded within.
lldb.swig now %include .../SBTarget.i, instead of .../SBTarget.h. Will create
other interface files and transition them over.
Also update modify-python-lldb.py to better handle the trailing blank line right
before the ending '"""' Python docstring delimiter.
git-svn-id: https://llvm.org/svn/llvm-project/llvdb/trunk@135355 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/scripts/Python/interface/SBTarget.i b/scripts/Python/interface/SBTarget.i
new file mode 100644
index 0000000..a7ddd64
--- /dev/null
+++ b/scripts/Python/interface/SBTarget.i
@@ -0,0 +1,449 @@
+//===-- SWIG Interface for SBTarget -----------------------------*- C++ -*-===//
+//
+// The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+namespace lldb {
+
+%feature("docstring",
+"Represents the target program running under the debugger.
+
+SBTarget supports module and breakpoint iterations. For example,
+
+ for m in target.module_iter():
+ print m
+
+produces:
+
+(x86_64) /Volumes/data/lldb/svn/trunk/test/python_api/lldbutil/iter/a.out
+(x86_64) /usr/lib/dyld
+(x86_64) /usr/lib/libstdc++.6.dylib
+(x86_64) /usr/lib/libSystem.B.dylib
+(x86_64) /usr/lib/system/libmathCommon.A.dylib
+(x86_64) /usr/lib/libSystem.B.dylib(__commpage)
+
+and,
+
+ for b in target.breakpoint_iter():
+ print b
+
+produces:
+
+SBBreakpoint: id = 1, file ='main.cpp', line = 66, locations = 1
+SBBreakpoint: id = 2, file ='main.cpp', line = 85, locations = 1
+"
+ ) SBTarget;
+class SBTarget
+{
+ %feature("autodoc", "1");
+public:
+ //------------------------------------------------------------------
+ // Broadcaster bits.
+ //------------------------------------------------------------------
+ enum
+ {
+ eBroadcastBitBreakpointChanged = (1 << 0),
+ eBroadcastBitModulesLoaded = (1 << 1),
+ eBroadcastBitModulesUnloaded = (1 << 2)
+ };
+
+ //------------------------------------------------------------------
+ // Constructors
+ //------------------------------------------------------------------
+ SBTarget ();
+
+ SBTarget (const lldb::SBTarget& rhs);
+
+#ifndef SWIG
+ const lldb::SBTarget&
+ operator = (const lldb::SBTarget& rhs);
+#endif
+
+ //------------------------------------------------------------------
+ // Destructor
+ //------------------------------------------------------------------
+ ~SBTarget();
+
+ bool
+ IsValid() const;
+
+ lldb::SBProcess
+ GetProcess ();
+
+ %feature("docstring", "
+ //------------------------------------------------------------------
+ /// Launch a new process.
+ ///
+ /// Launch a new process by spawning a new process using the
+ /// target object's executable module's file as the file to launch.
+ /// Arguments are given in \a argv, and the environment variables
+ /// are in \a envp. Standard input and output files can be
+ /// optionally re-directed to \a stdin_path, \a stdout_path, and
+ /// \a stderr_path.
+ ///
+ /// @param[in] listener
+ /// An optional listener that will receive all process events.
+ /// If \a listener is valid then \a listener will listen to all
+ /// process events. If not valid, then this target's debugger
+ /// (SBTarget::GetDebugger()) will listen to all process events.
+ ///
+ /// @param[in] argv
+ /// The argument array.
+ ///
+ /// @param[in] envp
+ /// The environment array.
+ ///
+ /// @param[in] launch_flags
+ /// Flags to modify the launch (@see lldb::LaunchFlags)
+ ///
+ /// @param[in] stdin_path
+ /// The path to use when re-directing the STDIN of the new
+ /// process. If all stdXX_path arguments are NULL, a pseudo
+ /// terminal will be used.
+ ///
+ /// @param[in] stdout_path
+ /// The path to use when re-directing the STDOUT of the new
+ /// process. If all stdXX_path arguments are NULL, a pseudo
+ /// terminal will be used.
+ ///
+ /// @param[in] stderr_path
+ /// The path to use when re-directing the STDERR of the new
+ /// process. If all stdXX_path arguments are NULL, a pseudo
+ /// terminal will be used.
+ ///
+ /// @param[in] working_directory
+ /// The working directory to have the child process run in
+ ///
+ /// @param[in] launch_flags
+ /// Some launch options specified by logical OR'ing
+ /// lldb::LaunchFlags enumeration values together.
+ ///
+ /// @param[in] stop_at_endtry
+ /// If false do not stop the inferior at the entry point.
+ ///
+ /// @param[out]
+ /// An error object. Contains the reason if there is some failure.
+ ///
+ /// @return
+ /// A process object for the newly created process.
+ //------------------------------------------------------------------
+
+ For example,
+
+ process = target.Launch(self.dbg.GetListener(), None, None,
+ None, '/tmp/stdout.txt', None,
+ None, 0, False, error)
+
+ launches a new process by passing nothing for both the args and the envs
+ and redirect the standard output of the inferior to the /tmp/stdout.txt
+ file. It does not specify a working directory so that the debug server
+ will use its idea of what the current working directory is for the
+ inferior. Also, we ask the debugger not to stop the inferior at the
+ entry point. If no breakpoint is specified for the inferior, it should
+ run to completion if no user interaction is required.
+ ") Launch;
+ lldb::SBProcess
+ Launch (SBListener &listener,
+ char const **argv,
+ char const **envp,
+ const char *stdin_path,
+ const char *stdout_path,
+ const char *stderr_path,
+ const char *working_directory,
+ uint32_t launch_flags, // See LaunchFlags
+ bool stop_at_entry,
+ lldb::SBError& error);
+
+ %feature("docstring", "
+ //------------------------------------------------------------------
+ /// Launch a new process with sensible defaults.
+ ///
+ /// @param[in] argv
+ /// The argument array.
+ ///
+ /// @param[in] envp
+ /// The environment array.
+ ///
+ /// @param[in] working_directory
+ /// The working directory to have the child process run in
+ ///
+ /// Default: listener
+ /// Set to the target's debugger (SBTarget::GetDebugger())
+ ///
+ /// Default: launch_flags
+ /// Empty launch flags
+ ///
+ /// Default: stdin_path
+ /// Default: stdout_path
+ /// Default: stderr_path
+ /// A pseudo terminal will be used.
+ ///
+ /// @return
+ /// A process object for the newly created process.
+ //------------------------------------------------------------------
+
+ For example,
+
+ process = target.LaunchSimple(['X', 'Y', 'Z'], None, os.getcwd())
+
+ launches a new process by passing 'X', 'Y', 'Z' as the args to the
+ executable.
+ ") LaunchSimple;
+ lldb::SBProcess
+ LaunchSimple (const char **argv,
+ const char **envp,
+ const char *working_directory);
+
+ %feature("docstring", "
+ //------------------------------------------------------------------
+ /// Attach to process with pid.
+ ///
+ /// @param[in] listener
+ /// An optional listener that will receive all process events.
+ /// If \a listener is valid then \a listener will listen to all
+ /// process events. If not valid, then this target's debugger
+ /// (SBTarget::GetDebugger()) will listen to all process events.
+ ///
+ /// @param[in] pid
+ /// The process ID to attach to.
+ ///
+ /// @param[out]
+ /// An error explaining what went wrong if attach fails.
+ ///
+ /// @return
+ /// A process object for the attached process.
+ //------------------------------------------------------------------
+ ") AttachToProcessWithID;
+ lldb::SBProcess
+ AttachToProcessWithID (SBListener &listener,
+ lldb::pid_t pid,
+ lldb::SBError& error);
+
+ %feature("docstring", "
+ //------------------------------------------------------------------
+ /// Attach to process with name.
+ ///
+ /// @param[in] listener
+ /// An optional listener that will receive all process events.
+ /// If \a listener is valid then \a listener will listen to all
+ /// process events. If not valid, then this target's debugger
+ /// (SBTarget::GetDebugger()) will listen to all process events.
+ ///
+ /// @param[in] name
+ /// Basename of process to attach to.
+ ///
+ /// @param[in] wait_for
+ /// If true wait for a new instance of 'name' to be launched.
+ ///
+ /// @param[out]
+ /// An error explaining what went wrong if attach fails.
+ ///
+ /// @return
+ /// A process object for the attached process.
+ //------------------------------------------------------------------
+ ") AttachToProcessWithName;
+ lldb::SBProcess
+ AttachToProcessWithName (SBListener &listener,
+ const char *name,
+ bool wait_for,
+ lldb::SBError& error);
+
+ %feature("docstring", "
+ //------------------------------------------------------------------
+ /// Connect to a remote debug server with url.
+ ///
+ /// @param[in] listener
+ /// An optional listener that will receive all process events.
+ /// If \a listener is valid then \a listener will listen to all
+ /// process events. If not valid, then this target's debugger
+ /// (SBTarget::GetDebugger()) will listen to all process events.
+ ///
+ /// @param[in] url
+ /// The url to connect to, e.g., 'connect://localhost:12345'.
+ ///
+ /// @param[in] plugin_name
+ /// The plugin name to be used; can be NULL.
+ ///
+ /// @param[out]
+ /// An error explaining what went wrong if the connect fails.
+ ///
+ /// @return
+ /// A process object for the connected process.
+ //------------------------------------------------------------------
+ ") ConnectRemote;
+ lldb::SBProcess
+ ConnectRemote (SBListener &listener,
+ const char *url,
+ const char *plugin_name,
+ SBError& error);
+
+ lldb::SBFileSpec
+ GetExecutable ();
+
+ uint32_t
+ GetNumModules () const;
+
+ lldb::SBModule
+ GetModuleAtIndex (uint32_t idx);
+
+ lldb::SBDebugger
+ GetDebugger() const;
+
+ lldb::SBModule
+ FindModule (const lldb::SBFileSpec &file_spec);
+
+ %feature("docstring", "
+ //------------------------------------------------------------------
+ /// Find functions by name.
+ ///
+ /// @param[in] name
+ /// The name of the function we are looking for.
+ ///
+ /// @param[in] name_type_mask
+ /// A logical OR of one or more FunctionNameType enum bits that
+ /// indicate what kind of names should be used when doing the
+ /// lookup. Bits include fully qualified names, base names,
+ /// C++ methods, or ObjC selectors.
+ /// See FunctionNameType for more details.
+ ///
+ /// @param[in] append
+ /// If true, any matches will be appended to \a sc_list, else
+ /// matches replace the contents of \a sc_list.
+ ///
+ /// @param[out] sc_list
+ /// A symbol context list that gets filled in with all of the
+ /// matches.
+ ///
+ /// @return
+ /// The number of matches added to \a sc_list.
+ //------------------------------------------------------------------
+ ") FindFunctions;
+ uint32_t
+ FindFunctions (const char *name,
+ uint32_t name_type_mask, // Logical OR one or more FunctionNameType enum bits
+ bool append,
+ lldb::SBSymbolContextList& sc_list);
+
+ %feature("docstring", "
+ //------------------------------------------------------------------
+ /// Find global and static variables by name.
+ ///
+ /// @param[in] name
+ /// The name of the global or static variable we are looking
+ /// for.
+ ///
+ /// @param[in] max_matches
+ /// Allow the number of matches to be limited to \a max_matches.
+ ///
+ /// @return
+ /// A list of matched variables in an SBValueList.
+ //------------------------------------------------------------------
+ ") FindGlobalVariables;
+ lldb::SBValueList
+ FindGlobalVariables (const char *name,
+ uint32_t max_matches);
+
+ void
+ Clear ();
+
+ bool
+ ResolveLoadAddress (lldb::addr_t vm_addr,
+ lldb::SBAddress& addr);
+
+ SBSymbolContext
+ ResolveSymbolContextForAddress (const SBAddress& addr,
+ uint32_t resolve_scope);
+
+ lldb::SBBreakpoint
+ BreakpointCreateByLocation (const char *file, uint32_t line);
+
+ lldb::SBBreakpoint
+ BreakpointCreateByLocation (const lldb::SBFileSpec &file_spec, uint32_t line);
+
+ lldb::SBBreakpoint
+ BreakpointCreateByName (const char *symbol_name, const char *module_name = NULL);
+
+ lldb::SBBreakpoint
+ BreakpointCreateByRegex (const char *symbol_name_regex, const char *module_name = NULL);
+
+ lldb::SBBreakpoint
+ BreakpointCreateByAddress (addr_t address);
+
+ uint32_t
+ GetNumBreakpoints () const;
+
+ lldb::SBBreakpoint
+ GetBreakpointAtIndex (uint32_t idx) const;
+
+ bool
+ BreakpointDelete (break_id_t break_id);
+
+ lldb::SBBreakpoint
+ FindBreakpointByID (break_id_t break_id);
+
+ bool
+ EnableAllBreakpoints ();
+
+ bool
+ DisableAllBreakpoints ();
+
+ bool
+ DeleteAllBreakpoints ();
+
+ lldb::SBBroadcaster
+ GetBroadcaster () const;
+
+#ifndef SWIG
+ bool
+ operator == (const lldb::SBTarget &rhs) const;
+
+ bool
+ operator != (const lldb::SBTarget &rhs) const;
+
+#endif
+
+#ifndef SWIG
+ bool
+ GetDescription (lldb::SBStream &description, lldb::DescriptionLevel description_level);
+#endif
+
+ bool
+ GetDescription (lldb::SBStream &description, lldb::DescriptionLevel description_level) const;
+
+protected:
+ friend class SBAddress;
+ friend class SBDebugger;
+ friend class SBFunction;
+ friend class SBProcess;
+ friend class SBSymbol;
+ friend class SBModule;
+
+ //------------------------------------------------------------------
+ // Constructors are private, use static Target::Create function to
+ // create an instance of this class.
+ //------------------------------------------------------------------
+
+ SBTarget (const lldb::TargetSP& target_sp);
+
+ void
+ reset (const lldb::TargetSP& target_sp);
+
+ lldb_private::Target *
+ operator ->() const;
+
+ lldb_private::Target *
+ get() const;
+
+private:
+ //------------------------------------------------------------------
+ // For Target only
+ //------------------------------------------------------------------
+
+ lldb::TargetSP m_opaque_sp;
+};
+
+} // namespace lldb