| blob | 74f9f6115e8f5ce608b72449434f46872a0b7025 |
1 # How to Use the mruby Debugger
3 copyright (c) 2014 Specified Non-Profit Corporation mruby Forum
5 ## 1. Summary
7 This file documents the mruby debugger ('mrdb') methods.
9 ## 2 Debugging with mrdb
11 ## 2.1 Building mrdb
13 The trunk of the mruby source tree, with the most recent mrdb, can be checked out with the following command:
15 ```bash
16 $ git clone https://github.com/mruby/mruby.git
17 ```
19 To run the `make` command:
21 ```bash
22 $ cd mruby
23 $ make
24 ```
26 By default, the `make` command will install the debugger files into mruby/bin.
28 You can add the path for mrdb on your host environment with the following command:
30 ```bash
31 $ echo "export PATH=\$PATH:MRUBY_ROOT/bin" >> ~/.bashrc
32 $ source ~/.bashrc
33 ```
35 `*MRUBY_ROOT` is the directory in which mruby source code will be installed.
37 To confirm mrdb was installed properly, run mrdb with the `--version` option:
39 ```bash
40 $ mrdb --version
41 mruby 2.1.1 (2020-06-04)
42 ```
44 ## 2.2 Basic Operation
46 ### 2.2.1 Debugging mruby Script Files (rb file) with mrdb
48 To invoke the mruby debugger, just type `mrdb`.
50 To specify the script file:
52 ```bash
53 $ mrdb [option] file name
54 ```
56 For example: Debugging sample.rb
58 ```bash
59 $ mrdb sample.rb
60 ```
62 You can execute the shell commands listed below:
64 |command|description|
65 |:-:|:--|
66 |run|execute programs|
67 |step|execute stepping|
68 |continue|execute continuing program|
69 |break|configure the breaking point|
70 |delete|deleting the breaking points|
71 |disable|disabling the breaking points|
72 |enable|enabling the breaking points|
73 |info breakpoints|showing list of the breaking points|
74 |print|evaluating and printing the values of the mruby expressions in the script|
75 |list|displaying the source cords|
76 |help|showing help|
77 |quit|terminating the mruby debugger|
79 ### 2.2.2 Debugging mruby Binary Files (mrb file) with mrdb
81 You can debug the mruby binary files.
83 #### 2.2.2.1 Debugging the binary files
85 * notice
86 To debug mruby binary files, you need to compile mruby files with option `-g`.
88 ```bash
89 $ mrbc -g sample.rb
90 ```
92 You can debug the mruby binary files with following command and the option `-b`.
94 ```bash
95 $ mrdb -b sample.mrb
96 ```
98 Then you can execute all debugger shell commands.
100 #### Break Command
102 You can use any breakpoint to stop the program by specifying the line number and method name.
103 The breakpoint list will be displayed after you have set the breakpoint successfully.
105 Usage:
107 ```
108 break [file:]linenum
109 b [file:]linenum
110 break [class:]method
111 b [class:]method
112 ```
114 The breakpoint will be ordered in serial from 1.
115 The number, which was given to the deleted breakpoint, will never be given to another breakpoint again.
117 You can give multiple breakpoints to specified the line number and method.
118 Be ware that breakpoint command will not check the validity of the class name and method name.
120 You can get the current breakpoint information by the following options.
122 breakpoint breakpoint number : file name. line number
124 breakpoint breakpoint number : [class name,] method name
126 #### Continue Command
128 Usage:
130 ```
131 continue [N]
132 c [N]
133 ```
135 N: the next breakpoint number
137 When resuming the program, it will stop at breakpoint N (N-1 breakpoint will be ignored).
139 When you run the `continue` command without specifying N, the program will be stopped at the next breakpoint.
141 Example:
143 ```
144 (foo.rb:1) continue 3
145 ```
147 This will resume the program and stop it at the third breakpoint.
149 #### Delete Command
151 This will delete the specified breakpoint.
153 Usage:
155 ```
156 delete [breakpoint-no]
157 d [breakpoint-no]
158 ```
160 breakpoint-no: breakpoint number
162 Example:
164 ```
165 (foo.rb:1) delete
166 ```
168 This will delete all of the breakpoints.
170 ```
171 (foo.rb:1) delete 1 3
172 ```
174 This will delete the breakpoint at 1 and 3.
176 #### Disable Command
178 This will disable the specified breakpoint.
180 Usage:
182 ```
183 disable [breakpoint-no]
184 dis [breakpoint-no]
185 ```
187 reappointing: breakpoint number
189 Example:
191 ```
192 (foo.rb:1) disable
193 ```
195 Use `disable` if you would like to disable all of the breakpoints.
197 ```
198 (foo.rb:1) disable 1 3
199 ```
201 This will disable the breakpoints at 1 and 3.
203 #### Enable Command
205 This will enable the specified breakpoints.
207 Usage:
209 ```
210 enable [breakpoint-no]
211 e [breakpoint-no]
212 ```
214 breakpoint-no: breakpoint number
216 Example:
218 ```
219 (foo.rb:1) enable
220 ```
222 Enabling all breakpoints
223 ```
224 (foo.rb:1) enable 1 3
225 ```
227 Enabling the breakpoint 1 and 3
229 #### eval command
231 Evaluating the string as source code and printing the value.
233 Same as print command, please see print command.
235 #### help command
237 Displaying the help message.
239 Usage:
241 ```
242 help [command]
243 h [command]
244 ```
246 Typing `help` without any options will display the command list.
248 #### Info Breakpoints Command
250 Displaying the specified breakpoint information.
252 Usage:
254 ```
255 info breakpoints [breakpoint-no]
256 i b [breakpoint-no]
257 ```
259 breakpoint-no: breakpoint number
261 Typing "info breakpoints" without ant option will display all breakpoint information.
262 Example:
264 ```
265 (sample.rb:1) info breakpoints
266 Num Type Enb What
267 1 breakpoint y at sample.rb:3 -> file name,line number
268 2 breakpoint n in Sample_class:sample_class_method -> [class:]method name
269 3 breakpoint y in sample_global_method
270 ```
272 Displaying the specified breakpoint number:
274 ```
275 (foo.rb:1) info breakpoints 1 3
276 Num Type Enb What
277 1 breakpoint y at sample.rb:3
278 3 breakpoint y in sample_global_method
279 ```
281 #### List Command
283 To display the code of the source file.
285 Usage:
287 ```
288 list [filename:]first[,last]
289 l [filename]:first[,last]
290 ```
292 first: the opening row number
293 last : the closing row number
295 When you specify the `first`, but not the `last` option, you will receive 10 rows.
296 When you do not specify both the `first` and `last` options, you will receive the next 10 rows.
298 Example:
300 ```
301 Specifying file name and first row number
302 sample.rb:1) list sample2.rb:5
303 ```
305 Specifying the file name and the first and last row number:
307 ```
308 (sample.rb:1) list sample2.rb:6,7
309 ```
311 #### Print Command
313 Evaluating the string as source code and printing the value.
315 Usage:
317 ```
318 print [expr]
319 p [expr]
320 ```
322 expr: expression
324 The expression is mandatory.
325 The displayed expressions will be serially ordered from 1.
326 If an exception occurs, the exception information will be displayed and the debugging will be continued.
328 Example:
330 ```
331 (sample.rb:1) print 1+2
332 $1 = 3
333 (sample.rb:1) print self
334 $2 = main
335 ```
337 Below is the case of the exception:
339 ```
340 (sample.rb:1) print (1+2
341 $1 = SyntaxError: line 1: syntax error, unexpected $end, expecting ')'
342 ```
344 #### Quit Command
346 Quitting the debugger.
348 Usage:
350 ```
351 quit
352 q
353 ```
355 #### Run Command
357 Running the program and stopping at the first breakpoint.
359 Usage:
361 ```
362 run
363 r
364 ```
366 #### Step Command
368 This will run the program step by step.
369 When the method and the block are invoked, the program will be stop at the first row.
370 The program, which is developed in C, will be ignored.