Mercurial > octave-antonio
annotate doc/interpreter/debug.txi @ 8828:8463d1a2e544
Doc fixes.
* 2]$$. => 2].$$
* @var{extrapval} => @var{extrapval}.
* call helloworld.oct => called @file{helloworld.oct}
* @itemize => @table @code
* shows. => shows:
* save => @code{save}
* @ref{Breakpoints} => @pxref{Breakpoints}
* add @noindent following example
* which is computed => and compute it
* clarify wording
* remove comma
* good => well
* set => number
* by writing => with the command
* has the option of directly calling => can call
* [-like-] {+of the right size,+}
* solvers => routines
* handle => test for
* add introductory section
* add following
* {+the+} [0..bitmax] => [0,bitmax]
* of the => with
* number => value
* add usual
* Besides when doing comparisons, logical => Logical {+also+}
* array comparison => array, comparisons
* param => parameter
* works very similar => is similar
* strings, => strings
* most simple => simplest
* easier => more easily
* like => as
* called => called,
* clarify wording
* you should simply type => use
* clarify wording
* means => way
* equally => also
* [-way much-] {+way+}
* add with mean value parameter given by the first argument, @var{l}
* add Functions described as @dfn{mapping functions} apply the given
operation to each element when given a matrix argument.
* in this brief introduction => here
* It is worth noticing => Note
* add following
* means => ways
author | Brian Gough <bjg@network-theory.co.uk> |
---|---|
date | Fri, 20 Feb 2009 11:17:01 -0500 |
parents | 03b7f618ab3d |
children | eb63fbe60fab |
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 |
8485
2beb59bf773a
[docs] commandline => command-line
Brian Gough <bjg@gnu.org>
parents:
8347
diff
changeset
|
29 The normal command-line 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 |
8828 | 44 script. These are breakpoints @pxref{Breakpoints}, discussed in the next |
6646 | 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 |
8828 | 60 To leave the debug mode, use either @code{dbcont} |
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
|
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 |
8275 | 63 @DOCSTRING(dbcont) |
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
|
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 | |
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
8286
diff
changeset
|
82 Note that breakpoints cannot be set in built-in functions |
6646 | 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 | |
8828 | 110 These functions can be used to clear all the breakpoints in a function. For example, |
6646 | 111 |
112 @example | |
113 dbclear ("asind", dbstatus ("asind")); | |
114 @end example | |
115 | |
7984
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
116 A breakpoint can be set in a subfunction. For example if a file contains |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
117 the functions |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
118 |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
119 @example |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
120 function y = func1 (x) |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
121 y = func2 (x); |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
122 endfunction |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
123 function y = func2 (x) |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
124 y = x + 1; |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
125 endfunction |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
126 @end example |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
127 |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
128 @noindent |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
129 then a breakpoint can be set at the start of the subfunction directly |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
130 with |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
131 |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
132 @example |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
133 @group |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
134 dbstop (["func1", filemarker(), "func2"]) |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
135 @result{} 5 |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
136 @end group |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
137 @end example |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
138 |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
139 Note that @code{filemarker} returns a character that marks the |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
140 subfunctions from the file containing them. |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7787
diff
changeset
|
141 |
8828 | 142 Another simple way of setting a breakpoint in an Octave script is the |
6646 | 143 use of the @code{keyboard} function. |
144 | |
145 @DOCSTRING(keyboard) | |
146 | |
147 @noindent | |
148 The @code{keyboard} function is typically placed in a script at the | |
149 point where the user desires that the execution is stopped. It | |
150 automatically sets the running script into the debug mode. | |
151 | |
152 @node Debug Mode | |
153 @section Debug Mode | |
154 | |
155 There are two additional support functions that allow the user to | |
156 interrogate where in the execution of a script Octave entered the debug | |
157 mode and to print the code in the script surrounding the point where | |
158 Octave entered debug mode. | |
159 | |
160 @DOCSTRING(dbwhere) | |
161 | |
162 @DOCSTRING(dbtype) | |
6647 | 163 |
8817
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8485
diff
changeset
|
164 You may also use @code{isdebugmode} to determine whether the debugger is |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8485
diff
changeset
|
165 currently active. |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8485
diff
changeset
|
166 |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8485
diff
changeset
|
167 @DOCSTRING(isdebugmode) |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8485
diff
changeset
|
168 |
8828 | 169 Debug mode also 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
|
170 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
|
171 |
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
|
172 @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
|
173 |
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
|
174 @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
|
175 @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
|
176 |
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
|
177 @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
|
178 |
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
|
179 @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
|
180 |
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
|
181 @DOCSTRING(dbdown) |