diff options
author | Johnny Chen <johnny.chen@apple.com> | 2011-07-16 21:15:39 +0000 |
---|---|---|
committer | Johnny Chen <johnny.chen@apple.com> | 2011-07-16 21:15:39 +0000 |
commit | dc7d3c121b93cd8d51c5efdc3cd576959d00ccab (patch) | |
tree | 92f4937dda7ecff81dbeaa7942815d708bf9a736 | |
parent | 60635494704f3847e0b0bc4bea4b2ae1768ed68f (diff) | |
download | bcm5719-llvm-dc7d3c121b93cd8d51c5efdc3cd576959d00ccab.tar.gz bcm5719-llvm-dc7d3c121b93cd8d51c5efdc3cd576959d00ccab.zip |
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.
llvm-svn: 135355
-rw-r--r-- | lldb/include/lldb/API/SBTarget.h | 96 | ||||
-rw-r--r-- | lldb/scripts/Python/interface/SBTarget.i | 449 | ||||
-rw-r--r-- | lldb/scripts/Python/modify-python-lldb.py | 59 | ||||
-rw-r--r-- | lldb/scripts/lldb.swig | 2 |
4 files changed, 494 insertions, 112 deletions
diff --git a/lldb/include/lldb/API/SBTarget.h b/lldb/include/lldb/API/SBTarget.h index 849af1c1723..e34e679c6cf 100644 --- a/lldb/include/lldb/API/SBTarget.h +++ b/lldb/include/lldb/API/SBTarget.h @@ -18,41 +18,8 @@ namespace lldb { class SBBreakpoint; -#ifdef SWIG -%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; -#endif class SBTarget { -#ifdef SWIG - %feature("autodoc", "1"); -#endif public: //------------------------------------------------------------------ // Broadcaster bits. @@ -87,9 +54,6 @@ public: lldb::SBProcess GetProcess (); -#ifdef SWIG - %feature("docstring", " -#endif //------------------------------------------------------------------ /// Launch a new process. /// @@ -146,23 +110,6 @@ public: /// @return /// A process object for the newly created process. //------------------------------------------------------------------ -#ifdef SWIG - -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; -#endif lldb::SBProcess Launch (SBListener &listener, char const **argv, @@ -176,9 +123,6 @@ run to completion if no user interaction is required. lldb::SBError& error); -#ifdef SWIG - %feature("docstring", " -#endif //------------------------------------------------------------------ /// Launch a new process with sensible defaults. /// @@ -205,24 +149,11 @@ run to completion if no user interaction is required. /// @return /// A process object for the newly created process. //------------------------------------------------------------------ -#ifdef SWIG - -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; -#endif lldb::SBProcess LaunchSimple (const char **argv, const char **envp, const char *working_directory); -#ifdef SWIG - %feature("docstring", " -#endif //------------------------------------------------------------------ /// Attach to process with pid. /// @@ -241,17 +172,11 @@ executable. /// @return /// A process object for the attached process. //------------------------------------------------------------------ -#ifdef SWIG - ") AttachToProcessWithID; -#endif lldb::SBProcess AttachToProcessWithID (SBListener &listener, lldb::pid_t pid, lldb::SBError& error); -#ifdef SWIG - %feature("docstring", " -#endif //------------------------------------------------------------------ /// Attach to process with name. /// @@ -273,18 +198,12 @@ executable. /// @return /// A process object for the attached process. //------------------------------------------------------------------ -#ifdef SWIG - ") AttachToProcessWithName; -#endif lldb::SBProcess AttachToProcessWithName (SBListener &listener, const char *name, bool wait_for, lldb::SBError& error); -#ifdef SWIG - %feature("docstring", " -#endif //------------------------------------------------------------------ /// Connect to a remote debug server with url. /// @@ -306,9 +225,6 @@ executable. /// @return /// A process object for the connected process. //------------------------------------------------------------------ -#ifdef SWIG - ") ConnectRemote; -#endif lldb::SBProcess ConnectRemote (SBListener &listener, const char *url, @@ -330,9 +246,6 @@ executable. lldb::SBModule FindModule (const lldb::SBFileSpec &file_spec); -#ifdef SWIG - %feature("docstring", " -#endif //------------------------------------------------------------------ /// Find functions by name. /// @@ -357,18 +270,12 @@ executable. /// @return /// The number of matches added to \a sc_list. //------------------------------------------------------------------ -#ifdef SWIG - ") FindFunctions; -#endif 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); -#ifdef SWIG - %feature("docstring", " -#endif //------------------------------------------------------------------ /// Find global and static variables by name. /// @@ -382,9 +289,6 @@ executable. /// @return /// A list of matched variables in an SBValueList. //------------------------------------------------------------------ -#ifdef SWIG - ") FindGlobalVariables; -#endif lldb::SBValueList FindGlobalVariables (const char *name, uint32_t max_matches); diff --git a/lldb/scripts/Python/interface/SBTarget.i b/lldb/scripts/Python/interface/SBTarget.i new file mode 100644 index 00000000000..a7ddd64b4c0 --- /dev/null +++ b/lldb/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 diff --git a/lldb/scripts/Python/modify-python-lldb.py b/lldb/scripts/Python/modify-python-lldb.py index cc24ab66189..789e2e73337 100644 --- a/lldb/scripts/Python/modify-python-lldb.py +++ b/lldb/scripts/Python/modify-python-lldb.py @@ -36,9 +36,8 @@ else: c_endif_swig = "#endif" c_ifdef_swig = "#ifdef SWIG" c_comment_marker = "//------------" -trailing_blank_line = ' ' # The pattern for recognizing the doxygen comment block line. -doxygen_comment_start = re.compile("^\s*( /// ?)") +doxygen_comment_start = re.compile("^\s*(/// ?)") # The demarcation point for turning on/off residue removal state. # When bracketed by the lines, the CLEANUP_DOCSTRING state (see below) is ON. toggle_docstring_cleanup_line = ' """' @@ -150,8 +149,31 @@ def list_to_frag(list): frag.write("self.{0}() == other.{0}()".format(list[i])) return frag.getvalue() +class NewContent(StringIO.StringIO): + """Simple facade to keep track of the previous line to be committed.""" + def __init__(self): + StringIO.StringIO.__init__(self) + self.prev_line = None + def add_line(self, a_line): + """Add a line to the content, if there is a previous line, commit it.""" + if self.prev_line != None: + print >> self, self.prev_line + self.prev_line = a_line + def del_line(self): + """Forget about the previous line, do not commit it.""" + self.prev_line = None + def del_blank_line(self): + """Forget about the previous line if it is a blank line.""" + if self.prev_line != None and not self.prev_line.strip(): + self.prev_line = None + def finish(self): + """Call this when you're finished with populating content.""" + if self.prev_line != None: + print >> self, self.prev_line + self.prev_line = None + # The new content will have the iteration protocol defined for our lldb objects. -new_content = StringIO.StringIO() +new_content = NewContent() with open(output_name, 'r') as f_in: content = f_in.read() @@ -200,6 +222,9 @@ for line in content.splitlines(): # CLEANUP_DOCSTRING state or out of it. if line == toggle_docstring_cleanup_line: if state & CLEANUP_DOCSTRING: + # Special handling of the trailing blank line right before the '"""' + # end docstring marker. + new_content.del_blank_line() state ^= CLEANUP_DOCSTRING else: state |= CLEANUP_DOCSTRING @@ -208,7 +233,7 @@ for line in content.splitlines(): match = class_pattern.search(line) # Inserts the lldb_iter() definition before the first class definition. if not lldb_iter_defined and match: - print >> new_content, lldb_iter_def + new_content.add_line(lldb_iter_def) lldb_iter_defined = True # If we are at the beginning of the class definitions, prepare to @@ -231,15 +256,15 @@ for line in content.splitlines(): # # But note that SBTarget has two types of iterations. if cls == "SBTarget": - print >> new_content, module_iter % (d[cls]['module']) - print >> new_content, breakpoint_iter % (d[cls]['breakpoint']) + new_content.add_line(module_iter % (d[cls]['module'])) + new_content.add_line(breakpoint_iter % (d[cls]['breakpoint'])) else: if (state & DEFINING_ITERATOR): - print >> new_content, iter_def % d[cls] - print >> new_content, len_def % d[cls][0] + new_content.add_line(iter_def % d[cls]) + new_content.add_line(len_def % d[cls][0]) if (state & DEFINING_EQUALITY): - print >> new_content, eq_def % (cls, list_to_frag(e[cls])) - print >> new_content, ne_def + new_content.add_line(eq_def % (cls, list_to_frag(e[cls]))) + new_content.add_line(ne_def) # Next state will be NORMAL. state = NORMAL @@ -248,9 +273,10 @@ for line in content.splitlines(): # Cleanse the lldb.py of the autodoc'ed residues. if c_ifdef_swig in line or c_endif_swig in line: continue - # As well as the comment marker line and trailing blank line. - if c_comment_marker in line or line == trailing_blank_line: + # As well as the comment marker line. + if c_comment_marker in line: continue + # Also remove the '\a ' and '\b 'substrings. line = line.replace('\a ', '') line = line.replace('\b ', '') @@ -272,11 +298,14 @@ for line in content.splitlines(): # Look for 'def IsValid(*args):', and once located, add implementation # of truth value testing for this object by delegation. if isvalid_pattern.search(line): - print >> new_content, nonzero_def + new_content.add_line(nonzero_def) # Pass the original line of content to new_content. - print >> new_content, line - + new_content.add_line(line) + +# We are finished with recording new content. +new_content.finish() + with open(output_name, 'w') as f_out: f_out.write(new_content.getvalue()) f_out.write("debugger_unique_id = 0\n") diff --git a/lldb/scripts/lldb.swig b/lldb/scripts/lldb.swig index 158004c68d1..ea8a2510919 100644 --- a/lldb/scripts/lldb.swig +++ b/lldb/scripts/lldb.swig @@ -223,7 +223,7 @@ o SBLineEntry: Specifies an association with a contiguous range of instructions %include "lldb/API/SBSymbol.h" %include "lldb/API/SBSymbolContext.h" %include "lldb/API/SBSymbolContextList.h" -%include "lldb/API/SBTarget.h" +%include "./Python/interface/SBTarget.i" %include "lldb/API/SBThread.h" %include "lldb/API/SBType.h" %include "lldb/API/SBValue.h" |