third-party/mruby/doc/guides/debugger.md

   1 # How to Use the mruby Debugger
   2
   3 copyright (c) 2014 Specified Non-Profit Corporation mruby Forum
   4
   5 ## 1. Summary
   6
   7 This file documents the mruby debugger ('mrdb') methods.
   8
   9 ## 2 Debugging with mrdb
  10
  11 ## 2.1 Building mrdb
  12
  13 The trunk of the mruby source tree, with the most recent mrdb, can be checked out with the following command:
  14
  15 ```bash
  16 $ git clone https://github.com/mruby/mruby.git
  17 ```
  18
  19 To run the `make` command:
  20
  21 ```bash
  22 $ cd mruby
  23 $ make
  24 ```
  25
  26 By default, the `make` command will install the debugger files into mruby/bin.
  27
  28 You can add the path for mrdb on your host environment with the following command:
  29
  30 ```bash
  31 $ echo "export PATH=\$PATH:MRUBY_ROOT/bin" >> ~/.bashrc
  32 $ source ~/.bashrc
  33 ```
  34
  35 `*MRUBY_ROOT` is the directory in which mruby source code will be installed.
  36
  37 To confirm mrdb was installed properly, run mrdb with the `--version` option:
  38
  39 ```bash
  40 $ mrdb --version
  41 mruby 2.1.2 (2020-08-06)
  42 ```
  43
  44 ## 2.2 Basic Operation
  45
  46 ### 2.2.1 Debugging mruby Script Files (rb file) with mrdb
  47
  48 To invoke the mruby debugger, just type `mrdb`.
  49
  50 To specify the script file:
  51
  52 ```bash
  53 $ mrdb [option] file name
  54 ```
  55
  56 For example: Debugging sample.rb
  57
  58 ```bash
  59 $ mrdb sample.rb
  60 ```
  61
  62 You can execute the shell commands listed below:
  63
  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|
  78
  79 ### 2.2.2 Debugging mruby Binary Files (mrb file) with mrdb
  80
  81 You can debug the mruby binary files.
  82
  83 #### 2.2.2.1 Debugging the binary files
  84
  85 * notice
  86 To debug mruby binary files, you need to compile mruby files with option `-g`.
  87
  88 ```bash
  89 $ mrbc -g sample.rb
  90 ```
  91
  92 You can debug the mruby binary files with following command and the option `-b`.
  93
  94 ```bash
  95 $ mrdb -b sample.mrb
  96 ```
  97
  98 Then you can execute all debugger shell commands.
  99
 100 #### Break Command
 101
 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.
 104
 105 Usage:
 106
 107 ```
 108 break [file:]linenum
 109 b [file:]linenum
 110 break [class:]method
 111 b [class:]method
 112 ```
 113
 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.
 116
 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.
 119
 120 You can get the current breakpoint information by the following options.
 121
 122 breakpoint breakpoint number : file name. line number
 123
 124 breakpoint breakpoint number : [class name,] method name
 125
 126 #### Continue Command
 127
 128 Usage:
 129
 130 ```
 131 continue [N]
 132 c [N]
 133 ```
 134
 135 N: the next breakpoint number
 136
 137 When resuming the program, it will stop at breakpoint N (N-1 breakpoint will be ignored).
 138
 139 When you run the `continue` command without specifying N, the program will be stopped at the next breakpoint.
 140
 141 Example:
 142
 143 ```
 144 (foo.rb:1) continue 3
 145 ```
 146
 147 This will resume the program and stop it at the third breakpoint.
 148
 149 #### Delete Command
 150
 151 This will delete the specified breakpoint.
 152
 153 Usage:
 154
 155 ```
 156 delete [breakpoint-no]
 157 d [breakpoint-no]
 158 ```
 159
 160 breakpoint-no: breakpoint number
 161
 162 Example:
 163
 164 ```
 165 (foo.rb:1) delete
 166 ```
 167
 168 This will delete all of the breakpoints.
 169
 170 ```
 171 (foo.rb:1) delete 1 3
 172 ```
 173
 174 This will delete the breakpoint at 1 and 3.
 175
 176 #### Disable Command
 177
 178 This will disable the specified breakpoint.
 179
 180 Usage:
 181
 182 ```
 183 disable [breakpoint-no]
 184 dis [breakpoint-no]
 185 ```
 186
 187 reappointing: breakpoint number
 188
 189 Example:
 190
 191 ```
 192 (foo.rb:1) disable
 193 ```
 194
 195 Use `disable` if you would like to disable all of the breakpoints.
 196
 197 ```
 198 (foo.rb:1) disable 1 3
 199 ```
 200
 201 This will disable the breakpoints at 1 and 3.
 202
 203 #### Enable Command
 204
 205 This will enable the specified breakpoints.
 206
 207 Usage:
 208
 209 ```
 210 enable [breakpoint-no]
 211 e [breakpoint-no]
 212 ```
 213
 214 breakpoint-no: breakpoint number
 215
 216 Example:
 217
 218 ```
 219 (foo.rb:1) enable
 220 ```
 221
 222 Enabling all breakpoints
 223 ```
 224 (foo.rb:1) enable 1 3
 225 ```
 226
 227 Enabling the breakpoint 1 and 3
 228
 229 #### eval command
 230
 231 Evaluating the string as source code and printing the value.
 232
 233 Same as print command, please see print command.
 234
 235 #### help command
 236
 237 Displaying the help message.
 238
 239 Usage:
 240
 241 ```
 242 help [command]
 243 h [command]
 244 ```
 245
 246 Typing `help` without any options will display the command list.
 247
 248 #### Info Breakpoints Command
 249
 250 Displaying the specified breakpoint information.
 251
 252 Usage:
 253
 254 ```
 255 info breakpoints [breakpoint-no]
 256 i b [breakpoint-no]
 257 ```
 258
 259 breakpoint-no: breakpoint number
 260
 261 Typing "info breakpoints" without ant option will display all breakpoint information.
 262 Example:
 263
 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 ```
 271
 272 Displaying the specified breakpoint number:
 273
 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 ```
 280
 281 #### List Command
 282
 283 To display the code of the source file.
 284
 285 Usage:
 286
 287 ```
 288 list [filename:]first[,last]
 289 l [filename]:first[,last]
 290 ```
 291
 292 first: the opening row number
 293 last : the closing row number
 294
 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.
 297
 298 Example:
 299
 300 ```
 301 Specifying file name and first row number
 302 sample.rb:1) list sample2.rb:5
 303 ```
 304
 305 Specifying the file name and the first and last row number:
 306
 307 ```
 308 (sample.rb:1) list sample2.rb:6,7
 309 ```
 310
 311 #### Print Command
 312
 313 Evaluating the string as source code and printing the value.
 314
 315 Usage:
 316
 317 ```
 318 print [expr]
 319 p [expr]
 320 ```
 321
 322 expr: expression
 323
 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.
 327
 328 Example:
 329
 330 ```
 331 (sample.rb:1) print 1+2
 332 $1 = 3
 333 (sample.rb:1) print self
 334 $2 = main
 335 ```
 336
 337 Below is the case of the exception:
 338
 339 ```
 340 (sample.rb:1) print (1+2
 341 $1 =  SyntaxError: line 1: syntax error, unexpected $end, expecting ')'
 342 ```
 343
 344 #### Quit Command
 345
 346 Quitting the debugger.
 347
 348 Usage:
 349
 350 ```
 351 quit
 352 q
 353 ```
 354
 355 #### Run Command
 356
 357 Running the program and stopping at the first breakpoint.
 358
 359 Usage:
 360
 361 ```
 362 run
 363 r
 364 ```
 365
 366 #### Step Command
 367
 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.