Mercurial > octave-antonio
annotate doc/interpreter/debug.txi @ 7787:6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
author | David Bateman <dbateman@free.fr> |
---|---|
date | Tue, 13 May 2008 21:12:12 +0200 |
parents | fd42779a8428 |
children | bbaa5d7d0143 |
rev | line source |
---|---|
6778 | 1 @c Copyright (C) 1996, 1997, 2007 John W. Eaton |
7018 | 2 @c |
3 @c This file is part of Octave. | |
4 @c | |
5 @c Octave is free software; you can redistribute it and/or modify it | |
6 @c under the terms of the GNU General Public License as published by the | |
7 @c Free Software Foundation; either version 3 of the License, or (at | |
8 @c your option) any later version. | |
9 @c | |
10 @c Octave is distributed in the hope that it will be useful, but WITHOUT | |
11 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
12 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
13 @c for more details. | |
14 @c | |
15 @c You should have received a copy of the GNU General Public License | |
16 @c along with Octave; see the file COPYING. If not, see | |
17 @c <http://www.gnu.org/licenses/>. | |
4175 | 18 |
19 @node Debugging | |
20 @chapter Debugging | |
21 | |
6646 | 22 Octave includes a built-in debugger to aid in the development of |
23 scripts. This can be used to interrupt the execution of an Octave script | |
24 at a certain point, or when certain conditions are met. Once execution | |
25 has stopped, and debug mode is entered, the symbol table at the point | |
26 where execution has stopped can be examined and modified to check for | |
27 errors. | |
4175 | 28 |
6646 | 29 The normal commandline editing and history functions are available in |
7787
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
30 debug mode. |
6646 | 31 |
32 @menu | |
33 * Entering Debug Mode:: | |
7787
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
34 * Leaving Debug Mode:: |
6646 | 35 * Breakpoints:: |
36 * Debug Mode:: | |
7787
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
37 * Call Stack:: |
6646 | 38 @end menu |
4175 | 39 |
6646 | 40 @node Entering Debug Mode |
41 @section Entering Debug Mode | |
4175 | 42 |
6646 | 43 There are two basic means of interrupting the execution of an Octave |
44 script. These are breakpoints @ref{Breakpoints}, discussed in the next | |
45 section and interruption based on some condition. | |
46 | |
47 Octave supports three means to stop execution based on the values set in | |
48 the functions @code{debug_on_interrupt}, @code{debug_on_warning} and | |
49 @code{debug_on_error}. | |
4175 | 50 |
4185 | 51 @DOCSTRING(debug_on_interrupt) |
4175 | 52 |
53 @DOCSTRING(debug_on_warning) | |
4185 | 54 |
55 @DOCSTRING(debug_on_error) | |
6646 | 56 |
7787
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
57 @node Leaving Debug Mode |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
58 @section Leavinging Debug Mode |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
59 |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
60 To leave the debug mode, you should simply type either @code{dbcont} |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
61 or @code{return}. |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
62 |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
63 @DOCSTRING(dbcont} |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
64 |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
65 To quit debug mode and return directly to the prompt @code{dbquit} |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
66 should be used instead |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
67 |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
68 @DOCSTRING(dbquit) |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
69 |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
70 Finally, typing @code{exit} or @code{quit} at the debug prompt will |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
71 result in Octave terminating normally. |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
72 |
6646 | 73 @node Breakpoints |
74 @section Breakpoints | |
75 | |
76 Breakpoints can be set in any Octave function, using the @code{dbstop} | |
77 function. | |
78 | |
79 @DOCSTRING(dbstop) | |
80 | |
81 @noindent | |
82 Note that breakpoints can not be set in built-in functions | |
83 (eg. @code{sin}, etc) or dynamically loaded function (ie. oct-files). To | |
84 set a breakpoint immediately on entering a function, the breakpoint | |
85 should be set to line 1. The leading comment block will be ignored and | |
86 the breakpoint will be set to the first executable statement in the | |
87 function. For example | |
88 | |
89 @example | |
90 @group | |
91 dbstop ("asind", 1) | |
92 @result{} 27 | |
93 @end group | |
94 @end example | |
95 | |
96 @noindent | |
97 Note that the return value of @code{27} means that the breakpoint was | |
98 effectively set to line 27. The status of breakpoints in a function can | |
99 be queried with the @code{dbstatus} function. | |
100 | |
101 @DOCSTRING(dbstatus) | |
102 | |
103 @noindent | |
104 Taking the above as an example, @code{dbstatus ("asind")} should return | |
105 27. The breakpoints can then be cleared with the @code{dbclear} function | |
106 | |
107 @DOCSTRING(dbclear) | |
108 | |
109 @noindent | |
110 To clear all of the breakpoints in a function the recommended means, | |
111 following the above example, is then | |
112 | |
113 @example | |
114 dbclear ("asind", dbstatus ("asind")); | |
115 @end example | |
116 | |
117 Another simple means of setting a breakpoint in an Octave script is the | |
118 use of the @code{keyboard} function. | |
119 | |
120 @DOCSTRING(keyboard) | |
121 | |
122 @noindent | |
123 The @code{keyboard} function is typically placed in a script at the | |
124 point where the user desires that the execution is stopped. It | |
125 automatically sets the running script into the debug mode. | |
126 | |
127 @node Debug Mode | |
128 @section Debug Mode | |
129 | |
130 There are two additional support functions that allow the user to | |
131 interrogate where in the execution of a script Octave entered the debug | |
132 mode and to print the code in the script surrounding the point where | |
133 Octave entered debug mode. | |
134 | |
135 @DOCSTRING(dbwhere) | |
136 | |
137 @DOCSTRING(dbtype) | |
6647 | 138 |
6648 | 139 Debug mode equally allows single line stepping through a function using |
7787
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
140 the commands @code{dbstep}. |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
141 |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
142 @c leave dbnext undocumented |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
143 |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
144 @DOCSTRING(dbstep) |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
145 |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
146 @node Call Stack |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
147 @section Call Stack |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
148 |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
149 @DOCSTRING(dbstack) |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
150 |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
151 @DOCSTRING(dbup) |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
152 |
6b521b1e3631
Add dbquit and make dbstep compatible. Use parser in debug mode to handle multi-line input
David Bateman <dbateman@free.fr>
parents:
7018
diff
changeset
|
153 @DOCSTRING(dbdown) |