From: Joel Brobecker Date: Thu, 21 Jan 2010 04:34:52 +0000 (+0000) Subject: Improve doc on how to execute a Python script from GDB. X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=95433b348df0563b42a4b4287d569fcd92e4ff24;p=binutils-gdb.git 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. --- diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 15d30a8cd8e..300ac23e3fb 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,16 @@ +2010-01-21 Joel Brobecker + + * 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 * gdb.texinfo (Command Files): Fix typo. diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index d716d0d07d4..fc11609122f 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