From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 13299 invoked by alias); 20 Jan 2010 04:03:23 -0000 Received: (qmail 13039 invoked by uid 22791); 20 Jan 2010 04:03:20 -0000 X-SWARE-Spam-Status: No, hits=-2.4 required=5.0 tests=AWL,BAYES_00 X-Spam-Check-By: sourceware.org Received: from rock.gnat.com (HELO rock.gnat.com) (205.232.38.15) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Wed, 20 Jan 2010 04:03:15 +0000 Received: from localhost (localhost.localdomain [127.0.0.1]) by filtered-rock.gnat.com (Postfix) with ESMTP id 480A52BAB09; Tue, 19 Jan 2010 23:03:13 -0500 (EST) Received: from rock.gnat.com ([127.0.0.1]) by localhost (rock.gnat.com [127.0.0.1]) (amavisd-new, port 10024) with LMTP id tCcwKkqhcDEw; Tue, 19 Jan 2010 23:03:13 -0500 (EST) Received: from joel.gnat.com (localhost.localdomain [127.0.0.1]) by rock.gnat.com (Postfix) with ESMTP id 49E022BAAE5; Tue, 19 Jan 2010 23:03:12 -0500 (EST) Received: by joel.gnat.com (Postfix, from userid 1000) id EC899F5980; Wed, 20 Jan 2010 08:03:04 +0400 (RET) Date: Wed, 20 Jan 2010 04:03:00 -0000 From: Joel Brobecker To: Eli Zaretskii Cc: gdb-patches@sourceware.org Subject: Re: [RFA/doco] Improve doc on how to execute a Python script from GDB. Message-ID: <20100120040304.GV17397@adacore.com> References: <1263913679-22046-1-git-send-email-brobecker@adacore.com> <83hbqh7ovh.fsf@gnu.org> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="9dgjiU4MmWPVapMU" Content-Disposition: inline In-Reply-To: <83hbqh7ovh.fsf@gnu.org> User-Agent: Mutt/1.5.20 (2009-06-14) Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2010-01/txt/msg00493.txt.bz2 --9dgjiU4MmWPVapMU Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-length: 1754 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 --9dgjiU4MmWPVapMU Content-Type: text/x-diff; charset=us-ascii Content-Disposition: attachment; filename="source-python-doc.diff" Content-length: 5205 commit 77c39f2b86a6cc65c187d31ec8c470b45c8faff1 Author: Joel Brobecker 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..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 --9dgjiU4MmWPVapMU Content-Type: text/x-diff; charset=us-ascii Content-Disposition: attachment; filename="updates.diff" Content-length: 1953 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}. --9dgjiU4MmWPVapMU--