gdb

2009-04-01  Tom Tromey  <tromey@redhat.com>
	    Thiago Jung Bauermann  <bauerman@br.ibm.com>
	    Phil Muldoon  <pmuldoon@redhat.com>

	* python/python.c: Include objfiles.h, observer.h.
	(gdbpy_auto_load): New global.
	(gdbpy_current_objfile): Likewise.
	(GDBPY_AUTO_FILENAME): New define.
	(gdbpy_new_objfile): New function.
	(gdbpy_get_current_objfile): Likewise.
	(gdbpy_objfiles): Likewise.
	(_initialize_python): Add "maint set auto-load".  Call
	gdbpy_initialize_objfile.  Attach objfile observer.
	(GdbMethods): New methods current_objfile, objfiles.
	* python/python-objfile.c: New file.
	* python/python-internal.h (objfile_to_objfile_object): Declare.
	(objfpy_get_printers): Likewise.
	(gdbpy_initialize_objfile): Likewise.
	* Makefile.in (SUBDIR_PYTHON_OBS): Add python-objfile.o.
	(SUBDIR_PYTHON_SRCS): Add python-objfile.c.
	(python-objfile.o): New target.

gdb/doc

2009-04-01  Tom Tromey  <tromey@redhat.com>
	    Thiago Jung Bauermann  <bauerman@br.ibm.com>

	* gdb.texinfo (Python API): Update.
	(Auto-loading): New node.
	(Objfiles In Python): New node.

gdb/testsuite

2009-04-06  Tom Tromey  <tromey@redhat.com>

	* gdb.python/python.exp (gdb_py_test_multiple): Add two objfile
	tests.
	* gdb.python/python-value.exp (py_objfile_tests): New proc.
	Call it.

2 files changed, 103 insertions, 0 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 6d81aef..c5594ff 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,12 @@
+2009-05-27  Tom Tromey  <tromey@redhat.com>
+	    Thiago Jung Bauermann  <bauerman@br.ibm.com>
+	    Phil Muldoon  <pmuldoon@redhat.com>
+
+	* gdb.texinfo: Add @syncodeindex for `tp'.
+	(Python API): Update.
+	(Auto-loading): New node.
+	(Objfiles In Python): New node.
+
 2009-05-15  Paul Pluzhnikov  <ppluzhnikov@google.com>
 
 	* gdb.texinfo (Threads): Document libthread-db-search-path.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b7bf14e..ba06b42 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -21,6 +21,7 @@
 
 @finalout
 @syncodeindex ky cp
+@syncodeindex tp cp
 
 @c readline appendices use @vindex, @findex and @ftable,
 @c annotate.texi and gdbmi use @findex.
@@ -18513,9 +18514,11 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown.
 @menu
 * Basic Python::                Basic Python Functions.
 * Exception Handling::
+* Auto-loading::                Automatically loading Python code.
 * Values From Inferior::
 * Commands In Python::          Implementing new commands in Python.
 * Functions In Python::         Writing new convenience functions.
+* Objfiles In Python::          Object files.
 * Frames In Python::            Acessing inferior stack frames from Python.
 @end menu
 
@@ -18614,6 +18617,53 @@ message as its value, and the Python call stack backtrace at the
 Python statement closest to where the @value{GDBN} error occured as the
 traceback.
 
+@node Auto-loading
+@subsubsection Auto-loading
+@cindex auto-loading, Python
+
+When a new object file is read (for example, due to the @code{file}
+command, or because the inferior has loaded a shared library),
+@value{GDBN} will look for a file named @file{@var{objfile}-gdb.py},
+where @var{objfile} is the object file's real name, formed by ensuring
+that the file name is absolute, following all symlinks, and resolving
+@code{.} and @code{..}  components.  If this file exists and is
+readable, @value{GDBN} will evaluate it as a Python script.
+
+If this file does not exist, and if the parameter
+@code{debug-file-directory} is set (@pxref{Separate Debug Files}),
+then @value{GDBN} will use the file named
+@file{@var{debug-file-directory}/@var{real-name}}, where
+@var{real-name} is the object file's real name, as described above.
+
+Finally, if this file does not exist, then @value{GDBN} will look for
+a file named @file{@var{data-directory}/python/auto-load/@var{real-name}}, where
+@var{data-directory} is @value{GDBN}'s data directory (available via
+@code{show data-directory}, @pxref{Data Files}), and @var{real-name}
+is the object file's real name, as described above.
+
+When reading an auto-loaded file, @value{GDBN} sets the ``current
+objfile''.  This is available via the @code{gdb.current_objfile}
+function (@pxref{Objfiles In Python}).  This can be useful for
+registering objfile-specific pretty-printers.
+
+The auto-loading feature is useful for supplying application-specific
+debugging commands and scripts.  You can enable or disable this
+feature, and view its current state.
+
+@table @code
+@kindex maint set python auto-load
+@item maint set python auto-load [yes|no]
+Enable or disable the Python auto-loading feature.
+
+@kindex show python auto-load
+@item show python auto-load
+Show whether Python auto-loading is enabled or disabled.
+@end table
+
+@value{GDBN} does not track which files it has already auto-loaded.
+So, your @samp{-gdb.py} file should take care to ensure that it may be
+evaluated multiple times without error.
+
 @node Values From Inferior
 @subsubsection Values From Inferior
 @cindex values from inferior, with Python
@@ -19027,6 +19077,50 @@ registration of the function with @value{GDBN}.  Depending on how the
 Python code is read into @value{GDBN}, you may need to import the
 @code{gdb} module explicitly.
 
+@node Objfiles In Python
+@subsubsection Objfiles In Python
+
+@cindex objfiles in python
+@tindex gdb.Objfile
+@tindex Objfile
+@value{GDBN} loads symbols for an inferior from various
+symbol-containing files (@pxref{Files}).  These include the primary
+executable file, any shared libraries used by the inferior, and any
+separate debug info files (@pxref{Separate Debug Files}).
+@value{GDBN} calls these symbol-containing files @dfn{objfiles}.
+
+The following objfile-related functions are available in the
+@code{gdb} module:
+
+@findex gdb.current_objfile
+@defun current_objfile
+When auto-loading a Python script (@pxref{Auto-loading}), @value{GDBN}
+sets the ``current objfile'' to the corresponding objfile.  This
+function returns the current objfile.  If there is no current objfile,
+this function returns @code{None}.
+@end defun
+
+@findex gdb.objfiles
+@defun objfiles
+Return a sequence of all the objfiles current known to @value{GDBN}.
+@xref{Objfiles In Python}.
+@end defun
+
+Each objfile is represented by an instance of the @code{gdb.Objfile}
+class.
+
+@defivar Objfile filename
+The file name of the objfile as a string.
+@end defivar
+
+@defivar Objfile pretty_printers
+The @code{pretty_printers} attribute is a list of functions.  It is
+used to look up pretty-printers.  A @code{Value} is passed to each
+function in order; if the function returns @code{None}, then the
+search continues.  Otherwise, the return value should be an object
+which is used to format the value.
+@end defivar
+
 @node Frames In Python
 @subsubsection Acessing inferior stack frames from Python.