From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 30296 invoked by alias); 13 Nov 2008 20:58:57 -0000 Mailing-List: contact archer-commits-help@sourceware.org; run by ezmlm Sender: Precedence: bulk List-Post: List-Help: List-Subscribe: Received: (qmail 30097 invoked by uid 306); 13 Nov 2008 20:58:56 -0000 Date: Thu, 13 Nov 2008 20:58:00 -0000 Message-ID: <20081113205856.30078.qmail@sourceware.org> From: tromey@sourceware.org To: archer-commits@sourceware.org Subject: [SCM] archer-tromey-python: * gdb.texinfo (Basic Python): Document gdb.get_objfiles and X-Git-Refname: refs/heads/archer-tromey-python X-Git-Reftype: branch X-Git-Oldrev: c72d8bd86890c414f264984a8e63f8d16a08df94 X-Git-Newrev: 2186d22ef00b023f4dfd6c84f104b23797c08558 X-SW-Source: 2008-q4/txt/msg00103.txt.bz2 List-Id: The branch, archer-tromey-python has been updated via 2186d22ef00b023f4dfd6c84f104b23797c08558 (commit) from c72d8bd86890c414f264984a8e63f8d16a08df94 (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email. - Log ----------------------------------------------------------------- commit 2186d22ef00b023f4dfd6c84f104b23797c08558 Author: Tom Tromey Date: Thu Nov 13 13:58:38 2008 -0700 * gdb.texinfo (Basic Python): Document gdb.get_objfiles and gdb.get_current_objfile. (Objfiles in Python): New node. (Auto-loading): Change to -gdb.py convention. (Pretty Printing): Update example. Document objfile search. ----------------------------------------------------------------------- Summary of changes: gdb/doc/ChangeLog | 8 ++++ gdb/doc/gdb.texinfo | 89 +++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 81 insertions(+), 16 deletions(-) First 500 lines of diff: diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index a25df37..6dad6d3 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,11 @@ +2008-11-13 Tom Tromey + + * gdb.texinfo (Basic Python): Document gdb.get_objfiles and + gdb.get_current_objfile. + (Objfiles in Python): New node. + (Auto-loading): Change to -gdb.py convention. + (Pretty Printing): Update example. Document objfile search. + 2008-11-06 Tom Tromey * gdb.texinfo (File Options): Document -x on .py files. diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index a7038b5..42ed962 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -17712,6 +17712,7 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown. * Threads In Python:: Accessing inferior threads from Python. * Commands In Python:: Implementing new commands in Python. * Parameters In Python:: Adding new @value{GDBN} parameters. +* Objfiles in Python:: Object files. @end menu @node Basic Python @@ -17737,6 +17738,20 @@ command as having originated from the user invoking it interactively. It must be a boolean value. If omitted, it defaults to @code{False}. @end defun +@findex gdb.get_current_objfile +@defun get_current_objfile +When auto-loading a Python script (@pxref{Auto-loading}), @var{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.get_objfiles +@defun get_objfiles +Return a sequence of all the objfiles current known to @var{GDBN}. +@xref{Objfiles in Python}. +@end defun + @findex gdb.get_parameter @defun get_parameter parameter Return the value of a @value{GDBN} parameter. @var{parameter} is a @@ -17797,21 +17812,26 @@ traceback. @node Auto-loading @subsubsection Auto-loading -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{.gdb.py} in the -directory holding the object file. If this file exists and is -readable, @value{GDBN} will evaluate it as a Python script. Note -that, if a separate debug file is used, @value{GDBN} will look for -@file{.gdb.py} both in the directory associated with the application -and the directory associated with the separate debug file. +When a new object file (@pxref{Objfiles in Python}) 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 by +adding @samp{-gdb.py} to the object file's name. If this file exists +and is readable, @value{GDBN} will evaluate it as a Python script. +Note that, if a separate debug file is used, @value{GDBN} will look +for the @samp{-gdb.py} file both in the directory associated with the +application and the directory associated with the separate debug file. + +When reading a @samp{-gdb.py} file, @var{GDBN} sets the ``current +objfile''. This is available via the @code{gdb.get_current_objfile} +function. This can be useful for registering objfile-specific +pretty-printers. This feature is useful for supplying application-specific debugging commands and scripts. It can be disabled using @code{maint set python auto-load}. @value{GDBN} does not track which files it has already auto-loaded. -So, your @file{.gdb.py} should take care to ensure that it may be +So, your @samp{-gdb.py} file should take care to ensure that it may be evaluated multiple times without error. @node Values From Inferior @@ -18008,7 +18028,8 @@ This method must return a string. @subsubsection Selecting Pretty-Printers The Python dictionary @code{gdb.pretty_printers} maps regular -expressions (strings) onto constructors. A constructor, in this +expressions (strings) onto constructors. Each @code{gdb.Objfile} also +contains a @code{pretty_printers} attribute. A constructor, in this context, is a function which takes a single @code{gdb.Value} argument and returns a a pretty-printer conforming to the interface definition above. @@ -18016,12 +18037,20 @@ above. When printing a value, @value{GDBN} first computes the value's canonical type by following typedefs, following a reference type to its referenced type, and removing qualifiers, such as @code{const} or -@code{volatile}. The name of this type is then compared to each -regular expression. If a regular expression matches, then the -corresponding pretty-printer is invoked with a @code{gdb.Value} -representing the value to be printed. +@code{volatile}. + +Then, @var{GDBN} tests each regular expression against this type name. +@var{GDBN} first checks the @code{pretty_printers} attribute of each +@code{gdb.Objfile}; after these have been exhausted it tries the +global @code{gdb.pretty_printers}. + +If a regular expression matches, then the corresponding pretty-printer +is invoked with a @code{gdb.Value} representing the value to be +printed. -The order in which the regular expressions are tried is not specified. +The order in which the objfiles are searched is not specified. +Similarly, the order in which the regular expressions in a given +dictionary are tried is not specified. Here is an example showing how a @code{std::string} printer might be written: @@ -18036,7 +18065,8 @@ class StdStringPrinter: def to_string(self): return self.val['_M_dataplus']['_M_p'] -gdb.pretty_printers['^std::basic_string$'] = StdStringPrinter +obj = gdb.get_current_objfile() +obj.pretty_printers['^std::basic_string$'] = StdStringPrinter @end smallexample @node Threads In Python @@ -18395,6 +18425,33 @@ The value is a string, which must be one of a collection string constants provided when the parameter is created. @end table +@node Objfiles in Python +@subsubsection Objfiles in Python + +@cindex objfiles in python +@cindex python objfiles +@tindex gdb.Objfile +@tindex Objfile +@var{GDBN} loads symbols for an inferior from various +symbol-containing files. These include the primary executable file, +any shared libraries used by the inferior, and any separate debug info +files. @var{GDBN} calls these symbol-containing files +@dfn{objfiles}. + +Each objfile is represented by an instance of the @code{gdb.Objfile} +class. + +@defmethod Objfile get_filename +Return the file name of the objfile as a string. +@end defmethod + +@defivar Objfile pretty_printers +The @code{pretty_printers} attribute is used to look up +pretty-printers by type. This is a dictionary which maps regular +expressions (strings) to pretty-printing objects. @xref{Pretty +Printing}, for more information. +@end defivar + @node Interpreters @chapter Command Interpreters @cindex command interpreters hooks/post-receive -- Repository for Project Archer.