|
4175
|
1 @c Copyright (C) 1996, 1997 John W. Eaton |
|
|
2 @c This is part of the Octave manual. |
|
|
3 @c For copying conditions, see the file gpl.texi. |
|
|
4 |
|
|
5 @node Debugging |
|
|
6 @chapter Debugging |
|
|
7 |
|
6646
|
8 Octave includes a built-in debugger to aid in the development of |
|
|
9 scripts. This can be used to interrupt the execution of an Octave script |
|
|
10 at a certain point, or when certain conditions are met. Once execution |
|
|
11 has stopped, and debug mode is entered, the symbol table at the point |
|
|
12 where execution has stopped can be examined and modified to check for |
|
|
13 errors. |
|
4175
|
14 |
|
6646
|
15 The normal commandline editing and history functions are available in |
|
|
16 debug mode. However, one limitation on the debug mode is that |
|
|
17 commands entered at the debug prompt are evaluated as strings, rather |
|
|
18 than being handled by the Octave parser. This means that all commands in |
|
|
19 debug mode must be contained on a single line. That is, it is alright to |
|
|
20 write |
|
|
21 |
|
|
22 @example |
|
|
23 debug> for i = 1:n, foo(i); endfor |
|
|
24 @end example |
|
4175
|
25 |
|
6646
|
26 @noindent |
|
|
27 in debug mode. However, writing the above in three lines will not be |
|
|
28 correctly evaluated. To leave the debug mode, you should simply type |
|
6647
|
29 either @code{quit}, @code{exit}, @code{return} or @code{dbcont}. |
|
6646
|
30 |
|
|
31 @menu |
|
|
32 * Entering Debug Mode:: |
|
|
33 * Breakpoints:: |
|
|
34 * Debug Mode:: |
|
|
35 @end menu |
|
4175
|
36 |
|
6646
|
37 @node Entering Debug Mode |
|
|
38 @section Entering Debug Mode |
|
4175
|
39 |
|
6646
|
40 There are two basic means of interrupting the execution of an Octave |
|
|
41 script. These are breakpoints @ref{Breakpoints}, discussed in the next |
|
|
42 section and interruption based on some condition. |
|
|
43 |
|
|
44 Octave supports three means to stop execution based on the values set in |
|
|
45 the functions @code{debug_on_interrupt}, @code{debug_on_warning} and |
|
|
46 @code{debug_on_error}. |
|
4175
|
47 |
|
4185
|
48 @DOCSTRING(debug_on_interrupt) |
|
4175
|
49 |
|
|
50 @DOCSTRING(debug_on_warning) |
|
4185
|
51 |
|
|
52 @DOCSTRING(debug_on_error) |
|
6646
|
53 |
|
|
54 @node Breakpoints |
|
|
55 @section Breakpoints |
|
|
56 |
|
|
57 Breakpoints can be set in any Octave function, using the @code{dbstop} |
|
|
58 function. |
|
|
59 |
|
|
60 @DOCSTRING(dbstop) |
|
|
61 |
|
|
62 @noindent |
|
|
63 Note that breakpoints can not be set in built-in functions |
|
|
64 (eg. @code{sin}, etc) or dynamically loaded function (ie. oct-files). To |
|
|
65 set a breakpoint immediately on entering a function, the breakpoint |
|
|
66 should be set to line 1. The leading comment block will be ignored and |
|
|
67 the breakpoint will be set to the first executable statement in the |
|
|
68 function. For example |
|
|
69 |
|
|
70 @example |
|
|
71 @group |
|
|
72 dbstop ("asind", 1) |
|
|
73 @result{} 27 |
|
|
74 @end group |
|
|
75 @end example |
|
|
76 |
|
|
77 @noindent |
|
|
78 Note that the return value of @code{27} means that the breakpoint was |
|
|
79 effectively set to line 27. The status of breakpoints in a function can |
|
|
80 be queried with the @code{dbstatus} function. |
|
|
81 |
|
|
82 @DOCSTRING(dbstatus) |
|
|
83 |
|
|
84 @noindent |
|
|
85 Taking the above as an example, @code{dbstatus ("asind")} should return |
|
|
86 27. The breakpoints can then be cleared with the @code{dbclear} function |
|
|
87 |
|
|
88 @DOCSTRING(dbclear) |
|
|
89 |
|
|
90 @noindent |
|
|
91 To clear all of the breakpoints in a function the recommended means, |
|
|
92 following the above example, is then |
|
|
93 |
|
|
94 @example |
|
|
95 dbclear ("asind", dbstatus ("asind")); |
|
|
96 @end example |
|
|
97 |
|
|
98 Another simple means of setting a breakpoint in an Octave script is the |
|
|
99 use of the @code{keyboard} function. |
|
|
100 |
|
|
101 @DOCSTRING(keyboard) |
|
|
102 |
|
|
103 @noindent |
|
|
104 The @code{keyboard} function is typically placed in a script at the |
|
|
105 point where the user desires that the execution is stopped. It |
|
|
106 automatically sets the running script into the debug mode. |
|
|
107 |
|
|
108 @node Debug Mode |
|
|
109 @section Debug Mode |
|
|
110 |
|
|
111 There are two additional support functions that allow the user to |
|
|
112 interrogate where in the execution of a script Octave entered the debug |
|
|
113 mode and to print the code in the script surrounding the point where |
|
|
114 Octave entered debug mode. |
|
|
115 |
|
|
116 @DOCSTRING(dbwhere) |
|
|
117 |
|
|
118 @DOCSTRING(dbtype) |
|
6647
|
119 |
|
6648
|
120 Debug mode equally allows single line stepping through a function using |
|
|
121 the commands @code{dbstep} and @code{dbnext}. These differ slightly in |
|
|
122 the way they treat the next executable line if the next line itself is a |
|
|
123 function defined in an m-file. The @code{dbnext} command will execute |
|
|
124 the next line, while staying in the existing function being debugged. |
|
|
125 The @code{dbstep} command will step in to the new function. |
