aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJoel Brobecker <brobecker@gnat.com>2010-01-21 04:34:52 +0000
committerJoel Brobecker <brobecker@gnat.com>2010-01-21 04:34:52 +0000
commit95433b348df0563b42a4b4287d569fcd92e4ff24 (patch)
treea93fbbd11a409f556d8109fa11cf48d205f6b955
parent9ac9c2b6b0a2cc7c695880b35673fe6f9ccd2dc1 (diff)
downloadgdb-95433b348df0563b42a4b4287d569fcd92e4ff24.zip
gdb-95433b348df0563b42a4b4287d569fcd92e4ff24.tar.gz
gdb-95433b348df0563b42a4b4287d569fcd92e4ff24.tar.bz2
Improve doc on how to execute a Python script from GDB.
* gdb.texinfo (File Options): Adjust the documentation of this switch to refer to the "source" command rather than partially duplicating some of the relevant information. (Extending GDB): Introduce and document the set/show script-extension setting. (Command Files): Add note explaining that the "source" command is also used to evalute scripts written in other languages. Remove the short slightly incorrect reference to sourcing Python scripts. (Python Commands): Document how to execute a Python script from GDB.
-rw-r--r--gdb/doc/ChangeLog13
-rw-r--r--gdb/doc/gdb.texinfo90
2 files changed, 93 insertions, 10 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 15d30a8..300ac23 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,16 @@
+2010-01-21 Joel Brobecker <brobecker@adacore.com>
+
+ * gdb.texinfo (File Options): Adjust the documentation of this
+ switch to refer to the "source" command rather than partially
+ duplicating some of the relevant information.
+ (Extending GDB): Introduce and document the set/show script-extension
+ setting.
+ (Command Files): Add note explaining that the "source" command
+ is also used to evalute scripts written in other languages.
+ Remove the short slightly incorrect reference to sourcing Python
+ scripts.
+ (Python Commands): Document how to execute a Python script from GDB.
+
2010-01-19 Joel Brobecker <brobecker@adacore.com>
* gdb.texinfo (Command Files): Fix typo.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d716d0d..fc11609 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -963,10 +963,8 @@ Connect to process ID @var{number}, as with the @code{attach} command.
@itemx -x @var{file}
@cindex @code{--command}
@cindex @code{-x}
-Execute commands from file @var{file}. If @var{file} ends in
-@samp{.py}, then the file is evaluated as Python code. If Python
-support is not enabled in this @value{GDBN}, then the file is assumed to
-contain @value{GDBN} commands, regardless of its extension.
+Execute commands from file @var{file}. The contents of this file is
+evaluated exactly as the @code{source} command would.
@xref{Command Files,, Command files}.
@item -eval-command @var{command}
@@ -12849,6 +12847,34 @@ by qualifying the problematic names with package
@code{Standard} explicitly.
@end itemize
+Older versions of the compiler sometimes generate erroneous debugging
+information, resulting in the debugger incorrectly printing the value
+of affected entities. In some cases, the debugger is able to work
+around an issue automatically. In other cases, the debugger is able
+to work around the issue, but the work-around has to be specifically
+enabled.
+
+@kindex set ada trust-PAD-over-XVS
+@kindex show ada trust-PAD-over-XVS
+@table @code
+
+@item set ada trust-PAD-over-XVS on
+Configure GDB to strictly follow the GNAT encoding when computing the
+value of Ada entities, particularly when @code{PAD} and @code{PAD___XVS}
+types are involved (see @code{ada/exp_dbug.ads} in the GCC sources for
+a complete description of the encoding used by the GNAT compiler).
+This is the default.
+
+@item set ada trust-PAD-over-XVS off
+This is related to the encoding using by the GNAT compiler. If @value{GDBN}
+sometimes prints the wrong value for certain entities, changing @code{ada
+trust-PAD-over-XVS} to @code{off} activates a work-around which may fix
+the issue. It is always safe to set @code{ada trust-PAD-over-XVS} to
+@code{off}, but this incurs a slight performance penalty, so it is
+recommended to leave this setting to @code{on} unless necessary.
+
+@end table
+
@node Unsupported Languages
@section Unsupported Languages
@@ -18907,6 +18933,38 @@ Displays whether the debugger is operating in interactive mode or not.
on composition of @value{GDBN} commands, and the second is based on the
Python scripting language.
+To facilitate the use of these extensions, @value{GDBN} is capable
+of evaluating the contents of a file. When doing so, @value{GDBN}
+can recognize which scripting language is being used by looking at
+the filename extension. Files with an unrecognized filename extension
+are always treated as a @value{GDBN} Command Files.
+@xref{Command Files,, Command files}.
+
+You can control how @value{GDBN} evaluates these files with the following
+setting:
+
+@table @code
+@kindex set script-extension
+@kindex show script-extension
+@item set script-extension off
+All scripts are always evaluated as @value{GDBN} Command Files.
+
+@item set script-extension soft
+The debugger determines the scripting language based on filename
+extension. If this scripting language is supported, @value{GDBN}
+evaluates the script using that language. Otherwise, it evaluates
+the file as a @value{GDBN} Command File.
+
+@item set script-extension strict
+The debugger determines the scripting language based on filename
+extension, and evaluates the script using that language. If the
+language is not supported, then the evaluation fails.
+
+@item show script-extension
+Display the current value of the @code{script-extension} option.
+
+@end table
+
@menu
* Sequences:: Canned Sequences of Commands
* Python:: Scripting @value{GDBN} using Python
@@ -19140,7 +19198,10 @@ does not mean to repeat the last command, as it would from the
terminal.
You can request the execution of a command file with the @code{source}
-command:
+command. Note that the @code{source} command is also used to evaluate
+scripts that are not Command Files. The exact behavior can be configured
+using the @code{script-extension} setting.
+@xref{Extending GDB,, Extending GDB}.
@table @code
@kindex source
@@ -19162,11 +19223,6 @@ If @code{-v}, for verbose mode, is given then @value{GDBN} displays
each command as it is executed. The option must be given before
@var{filename}, and is interpreted as part of the filename anywhere else.
-If @var{filename} ends in @samp{.py}, then @value{GDBN} evaluates the
-contents of the file as Python code. If Python support is not compiled
-into @value{GDBN}, then the file is assumed to contain @value{GDBN}
-commands, regardless of its extension.
-
Commands that would ask for confirmation if used interactively proceed
without asking when used in a command file. Many @value{GDBN} commands that
normally print messages to say what they are doing omit the messages
@@ -19444,6 +19500,20 @@ printing is enabled; if @code{off}, then Python stack printing is
disabled.
@end table
+It is also possible to execute a Python script from the @value{GDBN}
+interpreter:
+
+@table @code
+@item source @file{script-name}
+The script name must end with @samp{.py} and @value{GDBN} must be configured
+to recognize the script language based on filename extension using
+the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
+
+@item python execfile ("script-name")
+This method is based on the @code{execfile} Python built-in function,
+and thus is always available.
+@end table
+
@node Python API
@subsection Python API
@cindex python api