This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[RFA/doco] Improve doc on how to execute a Python script from GDB.


This patch improves on a previous documentation update, which I rebased
an applied, but turned out to be grossly out of sync with the actual
code changes.

gdb/doc/ChangeLog:

        * 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.

I hope that this patch is going to improve the documentation, because
I ended up spending a lot of time working on it :-(. I think it was
a combination of the "source" command being documented at an
inconveninent location, and me sucking big time at writing docs.

---
 gdb/doc/gdb.texinfo |   60 ++++++++++++++++++++++++++++++++++++++++++--------
 1 files changed, 50 insertions(+), 10 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d716d0d..8f31f45 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 if it was evaluated using the @code{source} command.
 @xref{Command Files,, Command files}.
 
 @item -eval-command @var{command}
@@ -18907,6 +18905,36 @@ 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 exploiting
+the filename extension.  Files with an unrecognized filename extension
+are always treated as a @value{GDBN} Command Files.  To control how GDB
+evaluates these files, the following setting can be used:
+
+@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.
+@xref{Command Files,, 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 +19168,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 +19193,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 +19470,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 GDB 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
-- 
1.6.3.3


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]