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

Joel Brobecker
2010-01-20T04:08:46Z

[-- Attachment #1: Type: text/plain, Size: 1841 bytes --]

[ARGH! Resending with the correct version of the patch, this time.
Sorry about that]

Thanks for the review, Eli.

> > +@item python execfile ("script-name")
> > +This method is based on the @code{execfile} Python built-in function,
> > +and thus is always available.
>
> "always" as in "when Python is compiled in", right?

That's correct. But since the documentation was inside the section
dedicated to Python support in GDB, I thought I could get away with
not having to conditionalize this with "when Python is compiled in".
I was going to add a small note, but I think we're already covered:
http://www.sourceware.org/gdb/current/onlinedocs/gdb/Python.html#Python

23.2 Scripting gdb using Python

You can script gdb using the Python programming language. This feature
is available only if gdb was configured using --with-python.

So I did not update the current text in this iteration. Let me know
if I should and I'll send a new patch shortly after. For your
convenience, I'm sending an extra diff, which shows the changes
from version 1 to version 2. Since the number of changes is small
compared to the size of the patch, it can be hard to spot these 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.

Ok to checkin?

Thanks,
--
Joel

[-- Attachment #2: source-python-doc.diff --]
[-- Type: text/x-diff, Size: 5202 bytes --]

commit b4561d6f19f96f04be3ad6f5b22ef7750a0c4f40
Author: Joel Brobecker <brobecker@adacore.com>
Date: Tue Jan 19 18:57:42 2010 +0400

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.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d716d0d..fbad9fe 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}
@@ -18907,6 +18905,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 +19170,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 +19195,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 +19472,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

[-- Attachment #3: updates.diff --]
[-- Type: text/x-diff, Size: 1953 bytes --]

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 8f31f45..fbad9fe 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -964,7 +964,7 @@ Connect to process ID @var{number}, as with the @code{attach} command.
@cindex @code{--command}
@cindex @code{-x}
Execute commands from file @var{file}. The contents of this file is
-evaluated exactly as if it was evaluated using the @code{source} command.
+evaluated exactly as the @code{source} command would.
@xref{Command Files,, Command files}.

@item -eval-command @var{command}
@@ -18907,17 +18907,19 @@ 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
+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. To control how GDB
-evaluates these files, the following setting can be used:
+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.
-@xref{Command Files,, Command files}.

@item set script-extension soft
The debugger determines the scripting language based on filename
@@ -19475,7 +19477,7 @@ interpreter:

@table @code
@item source @file{script-name}
-The script name must end with @samp{.py} and GDB must be configured
+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}.