maxjhandsome
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Releases Wiki Activity

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
This commit is contained in:
Johnny Chen 2011-07-16 21:15:39 +00:00
parent 6063549470
commit dc7d3c121b
4 changed files with 494 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
lldb/include/lldb/API/SBTarget.h
View File

@ -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);

449
lldb/scripts/Python/interface/SBTarget.i Normal file
View File

@ -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

59
lldb/scripts/Python/modify-python-lldb.py
View File

@ -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")

2
lldb/scripts/lldb.swig
View File

@ -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"