| blob | 7059132c0e0d09987fa5ed4c27d5f0a750f39124 |
1 <!-- summary: About the Debugger with the `mrdb` Command -->
3 # How to Use the mruby Debugger
5 copyright (c) 2014 Specified Non-Profit Corporation mruby Forum
7 ## 1. Summary
9 This file documents the mruby debugger ('mrdb') methods.
11 ## 2 Debugging with mrdb
13 ## 2.1 Building mrdb
15 The trunk of the mruby source tree, with the most recent mrdb, can be checked out with the following command:
17 ```bash
18 $ git clone https://github.com/mruby/mruby.git
19 ```
21 To run the `make` command:
23 ```bash
24 $ cd mruby
25 $ make
26 ```
28 By default, the `make` command will install the debugger files into mruby/bin.
30 You can add the path for mrdb on your host environment with the following command:
32 ```bash
33 $ echo "export PATH=\$PATH:MRUBY_ROOT/bin" >> ~/.bashrc
34 $ source ~/.bashrc
35 ```
37 `*MRUBY_ROOT` is the directory in which mruby source code will be installed.
39 To confirm mrdb was installed properly, run mrdb with the `--version` option:
41 ```bash
42 $ mrdb --version
43 mruby 3.4.0 (2025-04-20)
44 ```
46 ## 2.2 Basic Operation
48 ### 2.2.1 Debugging mruby Script Files (rb file) with mrdb
50 To invoke the mruby debugger, just type `mrdb`.
52 To specify the script file:
54 ```bash
55 $ mrdb [option] filename
56 ```
58 For example: Debugging sample.rb
60 ```bash
61 $ mrdb sample.rb
62 ```
64 You can execute the shell commands listed below:
66 | command | description |
67 | :--------------: | :------------------------------------------------------------------------ |
68 | run | execute programs |
69 | step | execute stepping |
70 | continue | execute continuing program |
71 | break | configure the breaking point |
72 | delete | deleting the breaking points |
73 | disable | disabling the breaking points |
74 | enable | enabling the breaking points |
75 | info breakpoints | showing list of the breaking points |
76 | print | evaluating and printing the values of the mruby expressions in the script |
77 | list | displaying the source cords |
78 | help | showing help |
79 | quit | terminating the mruby debugger |
81 ### 2.2.2 Debugging mruby Binary Files (mrb file) with mrdb
83 You can debug the mruby binary files.
85 #### 2.2.2.1 Debugging the binary files
87 - notice
88 To debug mruby binary files, you need to compile mruby files with option `-g`.
90 ```bash
91 $ mrbc -g sample.rb
92 ```
94 You can debug the mruby binary files with following command and the option `-b`.
96 ```bash
97 $ mrdb -b sample.mrb
98 ```
100 Then you can execute all debugger shell commands.
102 #### Break Command
104 You can use any breakpoint to stop the program by specifying the line number and method name.
105 The breakpoint list will be displayed after you have set the breakpoint successfully.
107 Usage:
109 ```
110 break [file:]linenum
111 b [file:]linenum
112 break [class:]method
113 b [class:]method
114 ```
116 The breakpoint will be ordered in serial from 1.
117 The number, which was given to the deleted breakpoint, will never be given to another breakpoint again.
119 You can give multiple breakpoints to the specified the line number and method.
120 Be aware that the breakpoint command will not check the validity of the class name and method name.
122 You can get the current breakpoint information by the following options.
124 breakpoint breakpoint number : filename. line number
126 breakpoint breakpoint number : [class name,] method name
128 #### Continue Command
130 Usage:
132 ```
133 continue [N]
134 c [N]
135 ```
137 N: the next breakpoint number
139 When resuming the program, it will stop at breakpoint N (N-1 breakpoint will be ignored).
141 When you run the `continue` command without specifying N, the program will be stopped at the next breakpoint.
143 Example:
145 ```
146 (foo.rb:1) continue 3
147 ```
149 This will resume the program and stop it at the third breakpoint.
151 #### Delete Command
153 This will delete the specified breakpoint.
155 Usage:
157 ```
158 delete [breakpoint-no]
159 d [breakpoint-no]
160 ```
162 breakpoint-no: breakpoint number
164 Example:
166 ```
167 (foo.rb:1) delete
168 ```
170 This will delete all the breakpoints.
172 ```
173 (foo.rb:1) delete 1 3
174 ```
176 This will delete the breakpoint at 1 and 3.
178 #### Disable Command
180 This will disable the specified breakpoint.
182 Usage:
184 ```
185 disable [breakpoint-no]
186 dis [breakpoint-no]
187 ```
189 reappointing: breakpoint number
191 Example:
193 ```
194 (foo.rb:1) disable
195 ```
197 Use `disable` if you would like to disable all the breakpoints.
199 ```
200 (foo.rb:1) disable 1 3
201 ```
203 This will disable the breakpoints at 1 and 3.
205 #### Enable Command
207 This will enable the specified breakpoints.
209 Usage:
211 ```
212 enable [breakpoint-no]
213 e [breakpoint-no]
214 ```
216 breakpoint-no: breakpoint number
218 Example:
220 ```
221 (foo.rb:1) enable
222 ```
224 Enabling all breakpoints
226 ```
227 (foo.rb:1) enable 1 3
228 ```
230 Enabling the breakpoint 1 and 3
232 #### eval command
234 Evaluating the string as source code and printing the value.
236 Same as print command, please see print command.
238 #### help command
240 Displaying the help message.
242 Usage:
244 ```
245 help [command]
246 h [command]
247 ```
249 Typing `help` without any options will display the command list.
251 #### Info Breakpoints Command
253 Displaying the specified breakpoint information.
255 Usage:
257 ```
258 info breakpoints [breakpoint-no]
259 i b [breakpoint-no]
260 ```
262 breakpoint-no: breakpoint number
264 Typing "info breakpoints" without ant option will display all breakpoint information.
265 Example:
267 ```
268 (sample.rb:1) info breakpoints
269 Num Type Enb What
270 1 breakpoint y at sample.rb:3 -> filename,line number
271 2 breakpoint n in Sample_class:sample_class_method -> [class:]method name
272 3 breakpoint y in sample_global_method
273 ```
275 Displaying the specified breakpoint number:
277 ```
278 (foo.rb:1) info breakpoints 1 3
279 Num Type Enb What
280 1 breakpoint y at sample.rb:3
281 3 breakpoint y in sample_global_method
282 ```
284 #### List Command
286 To display the code of the source file.
288 Usage:
290 ```
291 list [filename:]first[,last]
292 l [filename]:first[,last]
293 ```
295 first: the opening row number
296 last : the closing row number
298 When you specify the `first`, but not the `last` option, you will receive 10 rows.
299 When you do not specify both the `first` and `last` options, you will receive the next 10 rows.
301 Example:
303 ```
304 Specifying filename and first row number
305 sample.rb:1) list sample2.rb:5
306 ```
308 Specifying the filename and the first and last row number:
310 ```
311 (sample.rb:1) list sample2.rb:6,7
312 ```
314 #### Print Command
316 Evaluating the string as source code and printing the value.
318 Usage:
320 ```
321 print [expr]
322 p [expr]
323 ```
325 expr: expression
327 The expression is mandatory.
328 The displayed expressions will be serially ordered from 1.
329 If an exception occurs, the exception information will be displayed, and the debugging will be continued.
331 Example:
333 ```
334 (sample.rb:1) print 1+2
335 $1 = 3
336 (sample.rb:1) print self
337 $2 = main
338 ```
340 Below is the case of the exception:
342 ```
343 (sample.rb:1) print (1+2
344 $1 = SyntaxError: line 1: syntax error, unexpected $end, expecting ')'
345 ```
347 #### Quit Command
349 Quitting the debugger.
351 Usage:
353 ```
354 quit
355 q
356 ```
358 #### Run Command
360 Running the program and stopping at the first breakpoint.
362 Usage:
364 ```
365 run
366 r
367 ```
369 #### Step Command
371 This will run the program step by step.
372 When the method and the block are invoked, the program will stop at the first row.
373 The program, which is developed in C, will be ignored.