byebug 0.0.1 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. data/.gitignore +4 -0
  2. data/.travis.yml +0 -5
  3. data/CHANGELOG.md +6 -0
  4. data/Gemfile +1 -1
  5. data/LICENSE +23 -20
  6. data/byebug.gemspec +5 -5
  7. data/ext/byebug/breakpoint.c +102 -134
  8. data/ext/byebug/byebug.c +110 -64
  9. data/ext/byebug/byebug.h +2 -3
  10. data/ext/byebug/context.c +72 -39
  11. data/lib/byebug.rb +34 -38
  12. data/lib/byebug/command.rb +19 -24
  13. data/lib/byebug/commands/breakpoints.rb +11 -12
  14. data/lib/byebug/commands/catchpoint.rb +1 -1
  15. data/lib/byebug/commands/control.rb +2 -4
  16. data/lib/byebug/commands/finish.rb +1 -1
  17. data/lib/byebug/commands/frame.rb +15 -17
  18. data/lib/byebug/commands/info.rb +29 -28
  19. data/lib/byebug/commands/irb.rb +23 -21
  20. data/lib/byebug/commands/method.rb +4 -4
  21. data/lib/byebug/commands/reload.rb +8 -6
  22. data/lib/byebug/commands/set.rb +27 -23
  23. data/lib/byebug/commands/show.rb +6 -4
  24. data/lib/byebug/commands/stepping.rb +2 -2
  25. data/lib/byebug/commands/threads.rb +10 -10
  26. data/lib/byebug/commands/trace.rb +13 -14
  27. data/lib/byebug/commands/variables.rb +14 -12
  28. data/lib/byebug/context.rb +2 -15
  29. data/lib/byebug/interface.rb +5 -0
  30. data/lib/byebug/processor.rb +59 -64
  31. data/lib/byebug/version.rb +2 -1
  32. data/old_doc/Makefile +20 -0
  33. data/{man/rdebug.1 → old_doc/byebug.1} +5 -5
  34. data/old_doc/byebug.html +6178 -0
  35. data/old_doc/byebug.texi +3775 -0
  36. data/{doc → old_doc}/hanoi.rb +0 -0
  37. data/{doc → old_doc}/primes.rb +0 -0
  38. data/{doc → old_doc}/test-tri2.rb +0 -0
  39. data/{doc → old_doc}/tri3.rb +0 -0
  40. data/{doc → old_doc}/triangle.rb +0 -0
  41. data/test/breakpoints_test.rb +96 -60
  42. data/test/conditions_test.rb +15 -12
  43. data/test/examples/info.rb +5 -5
  44. data/test/examples/stepping.rb +1 -1
  45. data/test/frame_test.rb +40 -39
  46. data/test/info_test.rb +105 -96
  47. data/test/irb_test.rb +66 -61
  48. data/test/jump_test.rb +18 -9
  49. data/test/list_test.rb +114 -107
  50. data/test/restart_test.rb +51 -58
  51. data/test/save_test.rb +8 -7
  52. data/test/set_test.rb +8 -11
  53. data/test/show_test.rb +3 -5
  54. data/test/stepping_test.rb +43 -53
  55. data/test/support/context.rb +1 -0
  56. data/test/support/processor.rb +10 -4
  57. data/test/support/test_dsl.rb +46 -18
  58. data/test/support/test_interface.rb +8 -5
  59. data/test/test_helper.rb +2 -2
  60. data/test/trace_test.rb +123 -124
  61. metadata +39 -17
  62. data/AUTHORS +0 -10
  63. data/doc/rdebug-emacs.texi +0 -1030
@@ -0,0 +1,3775 @@
1
+ \input texinfo @c -*-texinfo-*-
2
+ @setfilename byebug.info
3
+
4
+ @set DBG byebug
5
+ @set ttbyebug @code{byebug}
6
+ @set ttDBG @code{@value{DBG}}
7
+
8
+ @set txicodequoteundirected
9
+ @set txicodequotebacktick
10
+ @set BYEBUG_VERSION 0.0.1
11
+ @set EDITION 0.0.1
12
+ @set UPDATED March-2013
13
+
14
+ @macro Example {}
15
+ @iftex
16
+ @cartouche
17
+ @end iftex
18
+ @smallexample
19
+ @end macro
20
+
21
+ @macro EndExample {}
22
+ @iftex
23
+ @end cartouche
24
+ @end iftex
25
+ @end smallexample
26
+ @end macro
27
+
28
+ @macro DBG {}
29
+ @value{DBG}
30
+ @end macro
31
+
32
+ @macro ttDBG {}
33
+ @value{ttbyebug}
34
+ @end macro
35
+
36
+ @c How to show optional variables.
37
+ @macro ovar{varname}
38
+ @r{[}@var{\varname\}@r{]}
39
+ @end macro
40
+
41
+ @settitle Byebug
42
+ @setchapternewpage odd
43
+ @c %**end of header
44
+
45
+ @finalout
46
+
47
+ @c This is a dir.info fragment to support semi-automated addition of
48
+ @c manuals to an info tree.
49
+ @dircategory Programming & development tools.
50
+ @direntry
51
+ * byebug: (byebug). Ruby Byebug
52
+ @end direntry
53
+
54
+ @titlepage
55
+ @title Debugging with @code{byebug}
56
+ @sp 1
57
+ @subtitle @value{EDITION} Edition
58
+ @subtitle @value{UPDATED-MONTH}
59
+ @author Rocky Bernstein, Kent Sibilev, and Mark Moseley
60
+ @page
61
+ @ifset WHERETO
62
+ @tex
63
+ {\parskip=0pt
64
+ \hfill (Send bugs and comments on byebug to fill in...)\par
65
+ \hfill {\it Debugging with {\tt byebug}\par
66
+ \hfill \TeX{}info \texinfoversion\par
67
+ }
68
+ @end tex
69
+ @end ifset
70
+ @end titlepage
71
+ @page
72
+
73
+ @ifnottex
74
+ @node Top, Summary, (dir), (dir)
75
+ @top Debugging with byebug
76
+
77
+ This file describes Byebug, a Ruby 2.0 debugger,
78
+ version @value{BYEBUG_VERSION}
79
+
80
+ This is the @value{EDITION} Edition, @value{UPDATED}
81
+ @c Copyleft (U+0254) 2013
82
+
83
+ @menu
84
+ * Summary:: Overview of Byebug with sample sessions
85
+ * Invocation:: Getting in and out
86
+ * Byebug Command Reference:: Byebug's commands
87
+ * Post-Mortem Debugging:: Debugging on an uncaught exception
88
+ * Byebug Module and Class:: Byebug's module and class
89
+
90
+ Appendix
91
+ * Using from GitHub::
92
+
93
+ Indexes
94
+ * Class Module Method Index:: An item for each Class, Module and Method.
95
+ * Command Index:: An item for each command name.
96
+ * General Index:: An item for each concept.
97
+ @end menu
98
+
99
+ @end ifnottex
100
+
101
+ @contents
102
+
103
+ @node Summary
104
+ @chapter Summary of @code{byebug}
105
+
106
+ The purpose of a debugger such as @DBG{} is to allow you to see what is going on
107
+ ``inside'' a Ruby program while it executes.
108
+
109
+ @ttDBG{} can do four main kinds of things (plus other things in support of these)
110
+ to help you catch bugs in the act:
111
+
112
+ @itemize @bullet
113
+ @item
114
+ Start your script, specifying anything that might affect its behavior.
115
+
116
+ @item
117
+ Make your script stop on specified conditions.
118
+
119
+ @item
120
+ Examine what has happened, when your script has stopped.
121
+
122
+ @item
123
+ Change things in your script, so you can experiment with correcting the effects of
124
+ one bug and go on to learn about another.
125
+ @end itemize
126
+
127
+ Although you can use @value{ttbyebug} to invoke your Ruby programs via a debugger
128
+ at the outset, there are other ways to use and enter the debugger
129
+
130
+ @menu
131
+ * First Sample Session:: A Simple Sample @code{byebug} session
132
+ * Second Sample Session:: Second Session Delving a little deeper @code{byebug} session
133
+ * Unit Testing Session:: Using byebug in unit testing
134
+ * Byebug.start with a block:: Using the Byebug.start with a block
135
+ * Debugging Oddities:: How debugging Ruby may be different...
136
+ @end menu
137
+
138
+ @node First Sample Session
139
+ @section The First Sample @code{byebug} Session (@code{list}, @code{display}, @code{print}, and @code{quit})
140
+
141
+ You can use this manual at your leisure to read all about @value{ttDBG}.
142
+ However, a handful of commands are enough to get started using the
143
+ byebug. The following sections illustrates these commands.
144
+
145
+ @iftex
146
+ In this sample session, we emphasize user input like this: @b{input},
147
+ to make it easier to pick out from the surrounding output.
148
+ @end iftex
149
+
150
+ Below is Ruby code to compute a triangle number of a given
151
+ length.@footnote{There are of course shorter ways to define @code{triangle}
152
+ such as:
153
+ @smallexample
154
+ def triangle(n) (n * (n+1)) / 2 end
155
+ @end smallexample
156
+ The code we use in this example and the next is more for pedagogical
157
+ purposes than how to write short Ruby code.}
158
+
159
+
160
+ @smallexample
161
+ $ @b{byebug triangle.rb}
162
+ triangle.rb:4 def hanoi(n,a,b,c)
163
+ (rdb:1) @b{list}
164
+ [-1, 8] in ./triangle.rb
165
+ 1 #!/usr/bin/env ruby
166
+ 2 # Compute the n'th triangle number - the hard way
167
+ 3 # triangle(n) == (n * (n+1)) / 2
168
+ => 4 def triangle(n)
169
+ 5 tri = 0
170
+ 6 0.upto(n) do |i|
171
+ 7 tri += i
172
+ 8 end
173
+ (rdb:1) @b{l}
174
+ [9, 18] in ./triangle.rb
175
+ 9 tri
176
+ 10 end
177
+ 11
178
+ 12 t = triangle(3)
179
+ 13 puts t
180
+ (rdb:1) @b{list 1,100}
181
+ [1, 100] in ./triangle.rb
182
+ 1 #!/usr/bin/env ruby
183
+ 2 # Compute the n'th triangle number - the hard way
184
+ 3 # triangle(n) == (n * (n+1)) / 2
185
+ => 4 def triangle(n)
186
+ 5 tri = 0
187
+ 6 0.upto(n) do |i|
188
+ 7 tri += i
189
+ 8 end
190
+ 9 tri
191
+ 10 end
192
+ 11
193
+ 12 t = triangle(3)
194
+ 13 puts t
195
+ (rdb:1)
196
+ @end smallexample
197
+
198
+ @noindent
199
+
200
+ There are lots of command options, but we don't need them for now. See
201
+ @ref{byebug command-line options} for a full list of command options.
202
+
203
+ Position information consists of a filename and line number,
204
+ e.g.@: @code{triangle.rb:4}. We are currently stopped before the first
205
+ executable line of the program; this is line 4 of
206
+ @code{triangle.rb}. If you are used to less dynamic languages and have
207
+ used byebugs for more statically compiled languages like C, C++, or
208
+ Java, it may seem odd to be stopped before a function definition. But
209
+ in Ruby line 4 is executed, the name @code{triangle} (probably) does
210
+ not exist so issuing a method call of @code{triangle} will raise a
211
+ ``method not found'' error.
212
+
213
+ @DBG{}'s prompt is @code{(rdb:@emph{n})}. The @emph{n} is the thread
214
+ number. Here it is 1 which is usually the case for the main thread. If
215
+ the program has died and you are in post-mortem debugging, there is no
216
+ thread number. In this situation, the string @code{post-mortem} is
217
+ used in place of a thread number. If the program has terminated
218
+ normally, the string this position will be @code{ctrl}. The commands
219
+ which are available change depending on the program state.
220
+
221
+ The first command, @code{list} (@pxref{List}), prints 10 lines
222
+ centered around the current line; the current line here is line 4 and
223
+ is marked by @code{=>}, so the range byebug would like to show
224
+ is -1..8. However since there aren't 5 lines before the current line,
225
+ those additional lines---``lines'' -1 and 0---are dropped and we print
226
+ the remaining 8 lines. The @code{list} command can be abbreviated
227
+ with @code{l} which is what we use next. Notice that when we use this
228
+ a second time, we continue listing from the place we last left
229
+ off. The desired range of lines this time is lines 9 to 18; but since
230
+ the program ends at line 13, only the remaining 5 lines are shown.
231
+
232
+ If you want to set how many lines to print by default rather than use
233
+ the initial number of lines, 10, use the @code{set listsize} command
234
+ (@pxref{Listsize}). To see the entire program in one shot, we gave an
235
+ explicit starting and ending line number.
236
+
237
+ If you use a front-end to byebug such as the Emacs interface,
238
+ @c (@pxref{GNU Emacs})
239
+ you probably won't use @code{list} all that much.
240
+
241
+ Now let us step through the program.
242
+
243
+ @smallexample
244
+ (rdb:1) @b{step}
245
+ triangle.rb:12
246
+ t = triangle(3)
247
+ (rdb:1) @b{@key{<RET>}}
248
+ triangle.rb:5
249
+ tri = 0
250
+ (rdb:1) @b{p tri}
251
+ nil
252
+ (rdb:1) @b{step}
253
+ triangle.rb:6
254
+ 0.upto(n) do |i|
255
+ (rdb:1) @b{p tri}
256
+ 0
257
+ @end smallexample
258
+
259
+ The first @kbd{step} command (@pxref{Step}) runs the script one
260
+ executable unit. The second command we entered was just hitting the
261
+ return key; @ttDBG{} remembers the last command you entered was
262
+ @code{step}, so it runs that last command again.
263
+
264
+ One way to print the values of variables uses @code{p}. (Of course,
265
+ there are of course lots of other ways too.). When we look at the
266
+ value of @code{tri} the first time, we see it is @code{nil}. Again we
267
+ are stopped @emph{before} the assignment on line 5, and this variable
268
+ hasn't been set previously. However after issuing another ``step''
269
+ command we see that the value is 0 as expected.
270
+
271
+ However if every time we stop we want to see the value of @code{tri}
272
+ to see how things are going stop, there is a better way by setting a
273
+ display expression (@pxref{DisplayCommands}).
274
+
275
+ @smallexample
276
+ (rdb:1) @b{display tri}
277
+ 1: tri = 0
278
+ @end smallexample
279
+
280
+ Now let us run the program until we return from the function. However
281
+ we'll want to see which lines get run.
282
+
283
+ @smallexample
284
+ (rdb:1) @b{display i}
285
+ 2: i =
286
+ (rdb:1) @b{set linetrace on}
287
+ line tracing is on.
288
+ (rdb:1) @b{finish}
289
+ Tracing(1):triangle.rb:7 tri += i
290
+ 1: tri = 0
291
+ 2: i = 0
292
+ Tracing(1):triangle.rb:7 tri += i
293
+ 1: tri = 0
294
+ 2: i = 1
295
+ Tracing(1):triangle.rb:7 tri += i
296
+ 1: tri = 1
297
+ 2: i = 2
298
+ Tracing(1):triangle.rb:7 tri += i
299
+ 1: tri = 3
300
+ 2: i = 3
301
+ Tracing(1):triangle.rb:9 tri
302
+ 1: tri = 6
303
+ 2: i = 3
304
+ 6
305
+ Tracing(1):triangle.rb:13 puts t
306
+ 1: tri =
307
+ 2: i =
308
+ 1: tri =
309
+ 2: i =
310
+ triangle.rb:13
311
+ puts t
312
+ (rdb:1) @b{quit}
313
+ Really quit? (y/n) @b{y}
314
+ @end smallexample
315
+
316
+ So far, so good. A you can see from the above to get out of the
317
+ byebug, one can issue a @code{quit} command. (@code{q} and
318
+ @code{exit} are just as good. If you want to quit without being
319
+ prompted, suffix the command with an exclamation mark, e.g.\@code{q!}.
320
+
321
+ @node Second Sample Session
322
+ @section Sample Session 2: Delving Deeper (@code{where}, @code{frame}, @code{restart}, @code{autoeval}, @code{break}, @code{ps})
323
+
324
+ In this section we'll introduce breakpoints, the call stack and
325
+ restarting. So far we've been doing pretty good in that we've not
326
+ encountered a bug to fix. Let's try another simple example. Okay
327
+ here's the program.
328
+
329
+ Below we will debug a simple Ruby program to solve the classic Towers
330
+ of Hanoi puzzle. It is augmented by the bane of programming: some
331
+ command-parameter processing with error checking.
332
+
333
+ @smallexample
334
+ $ @b{byebug hanoi.rb}
335
+ hanoi.rb:3 def hanoi(n,a,b,c)
336
+ (rdb:1) @b{list 1,100}
337
+ [1, 100] in ./hanoi.rb
338
+ 1 #!/usr/bin/ruby
339
+ 2
340
+ => 3 def hanoi(n,a,b,c)
341
+ 4 if n-1 > 0
342
+ 5 hanoi(n-1, a, c, b)
343
+ 6 end
344
+ 7 puts "Move disk %s to %s" % [a, b]
345
+ 8 if n-1 > 0
346
+ 9 hanoi(n-1, c, b, a)
347
+ 10 end
348
+ 11 end
349
+ 12
350
+ 13 i_args=ARGV.length
351
+ 14 if i_args > 1
352
+ 15 puts "*** Need number of disks or no parameter"
353
+ 16 exit 1
354
+ 17 end
355
+ 18
356
+ 19 n=3
357
+ 20
358
+ 21 if i_args > 0
359
+ 22 begin
360
+ 23 n = ARGV[0].to_i
361
+ 24 rescue ValueError, msg
362
+ 25 print "** Expecting an integer, got: %s" % ARGV[0].to_s
363
+ 26 exit 2
364
+ 27 end
365
+ 28 end
366
+ 29
367
+ 30 if n < 1 or n > 100
368
+ 31 puts "*** number of disks should be between 1 and 100"
369
+ 32 exit 2
370
+ 33 end
371
+ 34
372
+ 35 hanoi(n, :a, :b, :c)
373
+ (rdb:1)
374
+ @end smallexample
375
+
376
+ Recall in the first section I said that before the @code{def} is run
377
+ the method it names is undefined. Let's check that out. First let's
378
+ see what private methods we can call before running @code{def hanoi}
379
+
380
+ @smallexample
381
+ (rdb:1) @b{set autoeval on}
382
+ autoeval is on.
383
+ (rdb:1) @b{private_methods}
384
+ [:require_relative, :Digest, :default_src_encoding, :debug_program, ...
385
+ @end smallexample
386
+
387
+ The @code{set autoeval} (@pxref{Autoeval}) command causes any commands
388
+ that are not normally understood to be byebug commands to get
389
+ evaluated as though they were Ruby commands. I use this a lot, so I
390
+ set this by putting it the command file @code{.byebugrc},
391
+ @pxref{Command Files}, that gets read when @code{byebug} starts.
392
+
393
+ As showing the list output of @code{private_methods}, I find this kind
394
+ of list unwieldy. What you are supposed to notice here is that
395
+ method @code{hanoi} is not in this list. When you ask
396
+ @code{byebug} for a list of method names via @code{method
397
+ instance}, it doesn't show output in this way; @code{byebug} can
398
+ sort and put into columns lists like this using the print command, @code{ps}.
399
+
400
+
401
+ @smallexample
402
+ (rdb:1) @b{ps private_methods}
403
+ Array debug_program p spawn
404
+ Complex default_src_encoding pp sprintf
405
+ Digest eval print srand
406
+ Float exec printf syscall
407
+ Integer exit proc system
408
+ Pathname exit! process_options test
409
+ Rational fail putc throw
410
+ String fork puts trace_var
411
+ __callee__ format raise trap
412
+ __method__ gem rand untrace_var
413
+ ` gets readline warn
414
+ abort global_variables readlines whence_file
415
+ at_exit initialize remove_instance_variable y
416
+ autoload initialize_copy require
417
+ autoload? iterator? require_relative
418
+ binding lambda select
419
+ block_given? load set_trace_func
420
+ caller local_variables singleton_method_added
421
+ catch loop singleton_method_removed
422
+ dbg_print method_missing singleton_method_undefined
423
+ dbg_puts open sleep
424
+ @end smallexample
425
+
426
+ Now let's see what happens after stepping:
427
+
428
+ @smallexample
429
+ (rdb:1) @b{private_methods.member?(:hanoi)}
430
+ false
431
+ (rdb:1) @b{step}
432
+ hanoi.rb:13
433
+ i_args=ARGV.length
434
+ (rdb:1) @b{private_methods.member?(:hanoi)}
435
+ true
436
+ (rdb:1)
437
+ @end smallexample
438
+
439
+ Okay, now where were we?
440
+
441
+ @smallexample
442
+ (rdb:1) @b{list}
443
+ [8, 17] in ./hanoi.rb
444
+ 8 if n-1 > 0
445
+ 9 hanoi(n-1, c, b, a)
446
+ 10 end
447
+ 11 end
448
+ 12
449
+ => 13 i_args=ARGV.length
450
+ 14 if i_args > 1
451
+ 15 puts "*** Need number of disks or no parameter"
452
+ 16 exit 1
453
+ 17 end
454
+ (rdb:1) @b{ARGV}
455
+ []
456
+ @end smallexample
457
+
458
+ Ooops. We forgot to specify any parameters to this program. Let's try
459
+ again. We can use the @code{restart} command here.
460
+
461
+ @smallexample
462
+ (rdb:1) @b{restart 3}
463
+ Re exec'ing:
464
+ /usr/bin/byebug hanoi.rb 3
465
+ hanoi.rb:3
466
+ def hanoi(n,a,b,c)
467
+ (rdb:1) @b{break 4}
468
+ Breakpoint 1 file hanoi.rb, line 4
469
+ (rdb:1) @b{continue}
470
+ Breakpoint 1 at hanoi.rb:4
471
+ ./hanoi.rb:4 if n-1 > 0
472
+ (rdb:1) @b{display n}
473
+ 1: n = 3
474
+ (rdb:1) @b{display a}
475
+ 2: a = a
476
+ (rdb:1) @b{undisplay 2}
477
+ (rdb:1) @b{display a.inspect}
478
+ 3: a.inspect = :a
479
+ (rdb:1) @b{display b.inspect}
480
+ 4: b.inspect = :b
481
+ (rdb:1) @b{continue}
482
+ Breakpoint 1 at hanoi.rb:4
483
+ 1: n = 2
484
+ 3: a.inspect = :a
485
+ 4: b.inspect = :c
486
+ ./hanoi.rb:4
487
+ if n-1 > 0
488
+ (rdb:1) @b{c}
489
+ Breakpoint 1 at hanoi.rb:4
490
+ 1: n = 1
491
+ 3: a.inspect = :a
492
+ 4: b.inspect = :b
493
+ ./hanoi.rb:4
494
+ if n-1 > 0
495
+ (rdb:1) @b{where}
496
+ --> #0 Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at line hanoi.rb:4
497
+ #1 Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at line hanoi.rb:5
498
+ #2 Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at line hanoi.rb:5
499
+ #3 at line hanoi.rb:35
500
+ (rdb:1)
501
+ @end smallexample
502
+
503
+ In the above we added a new command, @code{break}
504
+ (@pxref{Breakpoints}) which indicates to go into byebug just
505
+ before that line of code is run. And @code{continue} resumes
506
+ execution. Notice the difference between @code{display a} and
507
+ @code{display a.inspect}. An implied string conversion is performed on
508
+ the expression after it is evaluated. To remove a display expression
509
+ we used @code{undisplay} is used. If we give a display number, just
510
+ that display expression is removed.
511
+
512
+ Above we also used a new command @code{where} (@pxref{Backtrace} to
513
+ show the call stack. In the above situation, starting from the bottom
514
+ line we see we called the hanoi from line 35 of the file
515
+ @code{hanoi.rb} and the hanoi method called itself two more times at
516
+ line 5.
517
+
518
+ In the call stack we show the file line position in the same format
519
+ when we stop at a line. Also we see the names of the parameters and
520
+ the types that those parameters @emph{currently} have. It's possible
521
+ that when the program was called the parameter had a different type,
522
+ since the types of variables can change dynamically. You alter the
523
+ style of what to show in the trace (@pxref{Callstyle}).
524
+
525
+ Let's explore a little more. Now were were we?
526
+
527
+ @smallexample
528
+ (rdb:1) @b{list}
529
+ 1 #!/usr/bin/ruby
530
+ 2
531
+ 3 def hanoi(n,a,b,c)
532
+ => 4 if n-1 > 0
533
+ 5 hanoi(n-1, a, c, b)
534
+ 6 end
535
+ 7 puts "Move disk %s to %s" % [a, b]
536
+ 8 if n-1 > 0
537
+ (rdb:1) @b{undisplay}
538
+ Clear all expressions? (y/n) @b{y}
539
+ (rdb:1) @b{i_args}
540
+ NameError Exception: undefined local variable or method `i_args' for main:Object
541
+ (rdb:1) @b{frame -1}
542
+ #3 at line hanoi.rb:35
543
+ (rdb:1) @b{i_args}
544
+ 1
545
+ (rdb:1) @b{p n}
546
+ 3
547
+ (rdb:1) @b{down 2}
548
+ #2 Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at line hanoi.rb:5
549
+ (rdb:1) @b{p n}
550
+ 2
551
+ @end smallexample
552
+
553
+ Notice in the above to get the value of variable @code{n}, I have to
554
+ use a print command like @code{p n}; If I entered just @code{n}, that
555
+ would be taken to mean byebug command ``next''. In the current
556
+ scope, variable @code{i_args} is not defined. However I can change to
557
+ the top-most frame by using the @code{frame} command. Just as with
558
+ arrays, -1 means the last one. Alternatively using frame number 3
559
+ would have been the same thing; so would issuing @code{up 3}.
560
+
561
+ Note that in the outside frame 3, the value of @code{i_args} can be
562
+ shown. Also note that the value of variable @code{n} is different.
563
+
564
+ @node Unit Testing Session
565
+ @section Using byebug in unit testing (@code{byebug/byebug}, @code{Byebug.start})
566
+
567
+ In the previous sessions we've been calling byebug right at the
568
+ outset. I confess that this mode of operation is usually not how I use
569
+ byebug.
570
+
571
+ There are a number of situations where calling byebug at the outset is
572
+ impractical for a couple of reasons.
573
+
574
+ @enumerate
575
+ @item
576
+ The byebug just doesn't work when run at the outset. By necessity
577
+ any debugging changes to the behavior or the program in slight and
578
+ subtle ways, and sometimes this can hinder finding bugs.
579
+ @item
580
+ There's a lot of code which that needs to get run before the part you
581
+ want to inspect. Running this code takes time and you don't want the
582
+ overhead of byebug.
583
+ @end enumerate
584
+
585
+ In this section we'll show how to enter the code in the middle
586
+ of your program, while delving more into byebug operation.
587
+
588
+ In this section we will also use unit testing. Using unit tests will
589
+ greatly reduce the amount of debugging needed, while at the same time,
590
+ will increase the quality of your program.
591
+
592
+ What we'll do is take the @code{triangle} code from the first session
593
+ and write a unit test for that. In a sense we did write a mini-test
594
+ for the program which was basically the last line where we printed the
595
+ value of triangle(3). This test however wasn't automated: the
596
+ implication is that someone would look at the output and verify that
597
+ what was printed is what was expected.
598
+
599
+ And before we can turn that into something that can be
600
+ @code{required}, we probably want to remove that output. However I
601
+ like to keep in that line so that when I look at the file, I have an
602
+ example of how to run it. Therefore we will conditionally run this
603
+ line if that file is invoked directly, but skip it if it is
604
+ not.@footnote{@code{byebug} resets @code{$0} to try to make things
605
+ like this work.}
606
+ @smallexample
607
+ if __FILE__ == $0
608
+ t = triangle(3)
609
+ puts t
610
+ end
611
+ @end smallexample
612
+
613
+ Let's call this file @code{tri2.rb}.
614
+
615
+ Okay, we're now ready to write our unit test. We'll use
616
+ @code{"test/unit"} which comes with the standard Ruby distribution.
617
+ Here's the test code; it should be in the same directory as tri2.rb.
618
+
619
+ @smallexample
620
+ #!/usr/bin/env ruby
621
+ require 'test/unit'
622
+ require_relative './tri2.rb'
623
+
624
+ class TestTri < Test::Unit::TestCase
625
+ def test_basic
626
+ solutions = []
627
+ 0.upto(5) do |i|
628
+ solutions << triangle(i)
629
+ end
630
+ assert_equal([0, 1, 3, 6, 10, 15], solutions,
631
+ 'Testing the first 5 triangle numbers')
632
+ end
633
+ end
634
+ @end smallexample
635
+
636
+ If you run it will work. However if you run @code{byebug} initially,
637
+ you will not get into the test, because @code{test/unit} wants to be
638
+ the main program. So here is a situation where one may need to modify
639
+ the program to add an explicit @emph{entry} into the
640
+ byebug.@footnote{For some versions of rake and @code{byebug} you can
641
+ in fact set a breakpoint after running @code{byebug}
642
+ initially. Personally though I find it much simpler and more reliable
643
+ to modify the code as shown here.}
644
+
645
+ One way to do this is to add the following before the place you want
646
+ to stop:
647
+ @smallexample
648
+ require 'byebug'
649
+ byebug
650
+ @end smallexample
651
+
652
+ Let's add this code just after entering @code{test_basic}:
653
+ @smallexample
654
+ ...
655
+ def test_basic
656
+ @b{require "byebug"}
657
+ @b{byebug}
658
+ solutions = []
659
+ ...
660
+ @end smallexample
661
+
662
+ Now we run the program..
663
+ @smallexample
664
+ $ @b{ruby test-tri.rb}
665
+ Loaded suite test-tri
666
+ Started
667
+ test-tri.rb:9
668
+ solutions = []
669
+ (rdb:1)
670
+ @end smallexample
671
+ and we see that we are stopped at line 9 just before the
672
+ initialization of the list @code{solutions}.
673
+
674
+ Now let's see where we are...
675
+
676
+ @smallexample
677
+ (rdb:1) @b{where}
678
+ --> #0 TestTri.test_basic at line /home/rocky/ruby/test-tri.rb:9
679
+ (rdb:1)
680
+ @end smallexample
681
+
682
+ Something seems wrong here; @code{TestTri.test_basic} indicates that
683
+ we are in class @code{TestTri} in method @code{test_basic}. However we
684
+ don't see the call to this like we did in the last example when we
685
+ used the @code{where} command. This is because byebug really
686
+ didn't spring into existence until after we already entered that
687
+ method, and Ruby doesn't keep call stack information around in a
688
+ way that will give the information we show when running @code{where}.
689
+
690
+ If we want call stack information, we have to turn call-stack tracking
691
+ on @emph{beforehand}. This is done by adding @code{Byebug.start}.
692
+
693
+ Here's what our test program looks like so after we modify it to start
694
+ tracking calls from the outset
695
+
696
+ @smallexample
697
+ #!/usr/bin/env ruby
698
+ require 'test/unit'
699
+ require 'tri2.rb'
700
+ require 'byebug'
701
+ @b{Byebug.start}
702
+
703
+ class TestTri < Test::Unit::TestCase
704
+ def test_basic
705
+ @b{byebug}
706
+ solutions = []
707
+ 0.upto(5) do |i|
708
+ solutions << triangle(i)
709
+ end
710
+ assert_equal([0, 1, 3, 6, 10, 15], solutions,
711
+ "Testing the first 5 triangle numbers")
712
+ end
713
+ end
714
+ @end smallexample
715
+
716
+ Now when we run this:
717
+ @smallexample
718
+ $ @b{ruby test-tri2.rb}
719
+ Loaded suite test-tri2
720
+ Started
721
+ test-tri2.rb:11
722
+ solutions = []
723
+ (rdb:1) @b{where}
724
+ --> #0 TestTri.test_basic at line test-tri2.rb:11
725
+ #1 MiniTest::Unit::TestCase.run(runner#MiniTest::Unit)
726
+ at line /usr/local/lib/ruby/1.9.1/minitest/unit.rb:458
727
+ #2 MiniTest::Unit.run_test_suites
728
+ at line /usr/local/lib/ruby/1.9.1/minitest/unit.rb:426
729
+ #3 MiniTest::Unit.run
730
+ at line /usr/local/lib/ruby/1.9.1/minitest/unit.rb:393
731
+ #4 at line /usr/local/lib/ruby/1.9.1/minitest/unit.rb:334
732
+ (rdb:1)
733
+ @end smallexample
734
+
735
+ Much better. But again let me emphasize that the parameter types are
736
+ those of the corresponding variables that @emph{currently} exist, and
737
+ this might have changed since the time when the call was made.
738
+
739
+ @node Byebug.start with a block
740
+ @section Using the @code{Byebug.start} with a block
741
+
742
+ We saw that @code{Byebug.start()} and @code{Byebug.stop()} allow
743
+ fine-grain control over where byebug tracking should occur.
744
+
745
+ Rather than use an explicit @code{stop()}, you can also pass a block
746
+ to the @code{start()} method. This causes @code{start()} to run and
747
+ then @code{yield} to that block. When the block is finished,
748
+ @code{stop()} is run. In other words, this wraps a
749
+ @code{Byebug.start()} and @code{Byebug.stop()} around the block of
750
+ code. But it also has a side benefit of ensuring that in the presence
751
+ of an uncaught exception @code{stop} is run, without having to
752
+ explicitly use @code{begin} ... @code{ensure Byebug.stop() end}.
753
+
754
+ For example, in Ruby Rails you might want to debug code in one of the
755
+ controllers without causing any slowdown to any other code. And
756
+ this can be done by wrapping the controller in a @code{start()} with a
757
+ block; when the method wrapped this way finishes byebug is
758
+ turned off, and the application proceeds at regular speed.
759
+
760
+ Of course, inside the block you will probably want to enter the
761
+ byebug using @code{Byebug.byebug()}, otherwise there would
762
+ little point in using the @code{start}. For example, you can do this
763
+ in @code{irb}:
764
+
765
+ @smallexample
766
+ $ @b{irb}
767
+ irb(main):001:0> @b{require 'byebug'}
768
+ => true
769
+ irb(main):002:0> @b{def foo}
770
+ irb(main):003:1> @b{x=1}
771
+ irb(main):004:1> @b{puts 'foo'}
772
+ irb(main):005:1> @b{end}
773
+ => nil
774
+ irb(main):006:0> @b{Byebug.start@{byebug; foo@}}
775
+ (irb):3
776
+
777
+ (rdb:1) @b{s}
778
+ (irb):4
779
+
780
+ (rdb:1) @b{p x}
781
+ 1
782
+ (rdb:1) @b{s}
783
+ foo
784
+ => true
785
+ irb(main):007:0>
786
+ @end smallexample
787
+
788
+ There is a counter inside of @code{Byebug.start} method to make sure
789
+ that this works when another @code{Byebug.start} method is called
790
+ inside of outer one. However if you are stopped inside byebug,
791
+ issuing another @code{byebug} call will not have any effect even if
792
+ it is nested inside another @code{Byebug.start}.
793
+
794
+ @node Debugging Oddities
795
+ @section How debugging Ruby may be different than debugging other Languages
796
+
797
+ If you are used to debugging in other languages like C, C++, Perl,
798
+ Java or even Bash@footnote{this is just an excuse to put in a
799
+ shameless plug for my bash byebug @url{http://bashdb.sf.net}}, there
800
+ may be a number of things that seem or feel a little bit different and
801
+ may confuse you. A number of these things aren't oddities of the
802
+ byebug per se, so much as a difference in how Ruby works compared to
803
+ those other languages. Because Ruby works a little differently from
804
+ those other languages, writing a byebug has to also be a little
805
+ different as well if it is to be useful.
806
+
807
+ In this respect, using byebug may help you understand Ruby
808
+ better.
809
+
810
+ We've already seen two examples of such differences. One difference is
811
+ the fact that we stop on method definitions or @code{def}'s and that is
812
+ because these are in fact executable statements. In other compiled
813
+ languages this would not happen because that's already been done when
814
+ you compile the program (or in Perl when it scans in the program). The
815
+ other difference we saw was in our inability to show call stack parameter
816
+ types without having made arrangements for byebug to track
817
+ this. In other languages call stack information is usually available
818
+ without asking assistance of byebug.@footnote{However in C, and
819
+ C++ generally you have to ask the compiler to add such information.}
820
+
821
+ In this section we'll consider some other things that might throw
822
+ off new users to Ruby who are familiar with other languages and
823
+ debugging in them.
824
+
825
+ @menu
826
+ * Stack No Longer Shows Scope Nesting::
827
+ * Bouncing Around in Blocks (e.g. Iterators)::
828
+ * No Parameter Values in a Call Stack::
829
+ * Lines You Can Stop At::
830
+ @end menu
831
+
832
+ @node Stack No Longer Shows Scope Nesting
833
+ @subsection Stack No Longer Shows Scope Nesting
834
+ In the Ruby 1.8 byebug, backtraces will show more stack frames
835
+ that you might find in other languages, such as C. In the Ruby 1.9
836
+ byebug, this is no longer the case.
837
+
838
+ @node Bouncing Around in Blocks (e.g. Iterators)
839
+ @subsection Bouncing Around in Blocks (e.g.@: Iterators)
840
+
841
+ When debugging languages with coroutines like Python and Ruby, a
842
+ method call may not necessarily go to the first statement after the
843
+ method header. It's possible the call will continue after a
844
+ @code{yield} statement from a prior call.
845
+
846
+ @smallexample
847
+ 1 #!/usr/bin/env ruby
848
+ 2 # Enumerator for primes
849
+ 3 class SievePrime
850
+ 4 @@@@odd_primes = []
851
+ 5 def self.next_prime(&block)
852
+ 6 candidate = 2
853
+ 7 yield candidate
854
+ 8 not_prime = false
855
+ 9 candidate += 1
856
+ 10 while true do
857
+ 11 @@@@odd_primes.each do |p|
858
+ 12 not_prime = (0 == (candidate % p))
859
+ 13 break if not_prime
860
+ 14 end
861
+ 15 unless not_prime
862
+ 16 @@@@odd_primes << candidate
863
+ 17 yield candidate
864
+ 18 end
865
+ 19 candidate += 2
866
+ 20 end
867
+ 21 end
868
+ 22 end
869
+ 23 SievePrime.next_prime do |prime|
870
+ 24 puts prime
871
+ 25 break if prime > 10
872
+ 26 end
873
+ @end smallexample
874
+
875
+ @smallexample
876
+ $ @b{byebug primes.rb}
877
+ primes.rb:3
878
+ class SievePrime
879
+ (rdb:1) @b{set linetrace on}
880
+ line tracing is on.
881
+ (rdb:1) @b{step 9}
882
+ Tracing(1):primes.rb:4 @@odd_primes = []
883
+ Tracing(1):primes.rb:5 def self.next_prime(&block)
884
+ Tracing(1):primes.rb:23 SievePrime.next_prime do |prime|
885
+ Tracing(1):primes.rb:6 candidate = 2
886
+ Tracing(1):primes.rb:7 yield candidate
887
+ Tracing(1):primes.rb:24 puts prime
888
+ 2
889
+ Tracing(1):primes.rb:25 break if prime > 10
890
+ Tracing(1):primes.rb:8 not_prime = false
891
+ Tracing(1):primes.rb:9 candidate += 1
892
+ primes.rb:9
893
+ candidate += 1
894
+ (rdb:1)
895
+ @end smallexample
896
+
897
+ The loop between lines 23--26 gets interleaved between those of
898
+ @code{Sieve::next_prime}, lines 6--19 above.
899
+
900
+ A similar kind of thing can occur in debugging programs with many threads.
901
+
902
+ @node No Parameter Values in a Call Stack
903
+ @subsection No Parameter Values in a Call Stack
904
+ In traditional byebugs in a call stack you can generally see the
905
+ names of the parameters and the values that were passed in.
906
+
907
+ Ruby is a very dynamic language and it tries to be efficient within
908
+ the confines of the language definition. Values generally aren't taken
909
+ out of a variable or expression and pushed onto a stack. Instead a new
910
+ scope created and the parameters are given initial values. Parameter
911
+ passing is by @emph{reference}, not by value as it is say Algol, C, or
912
+ Perl. During the execution of a method, parameter values can
913
+ change---and often do. In fact even the @emph{class} of the object can
914
+ change.
915
+
916
+ So at present, the name of the parameter shown. The call-style setting
917
+ @pxref{Callstyle} can be used to set whether the name is shown or the
918
+ name and the @emph{current} class of the object.
919
+
920
+ It has been contemplated that a style might be added which saves on
921
+ call shorter ``scalar'' types of values and the class name.
922
+
923
+ @node Lines You Can Stop At
924
+ @subsection Lines You Can Stop At
925
+ As with the duplicate stops per control (e.g.@: @code{if} statement),
926
+ until tools like byebugs get more traction among core ruby
927
+ developers there are going to be weirdness. Here we describe the
928
+ stopping locations which effects the breakpoint line numbers you can
929
+ stop at.
930
+
931
+ Consider the following little Ruby program.
932
+
933
+ @smallexample
934
+ 'Yes it does' =~ /
935
+ (Yes) \s+
936
+ it \s+
937
+ does
938
+ /ix
939
+ puts $1
940
+ @end smallexample
941
+
942
+ The stopping points that Ruby records are the last two lines, lines 5
943
+ and 6.
944
+
945
+ Inside @code{byebug} you an get a list of stoppable lines for a
946
+ file using the @code{info file} command with the attribute
947
+ @code{breakpoints}.
948
+
949
+ @ifset FINISHED
950
+ To be continued...
951
+
952
+ @itemize @bullet
953
+ @item more complex example with objects, pretty printing and irb.
954
+ @item line tracing and non-interactive tracing.
955
+ @item mixing in Byebug.debug with byebug
956
+ @item post-mortem debugging and setting up for that
957
+ @item threading?
958
+ @item references to videos
959
+ @end itemize
960
+ @end ifset
961
+
962
+ @node Invocation
963
+ @chapter Getting in and out
964
+
965
+ @menu
966
+ * Starting byebug:: How to enter byebug
967
+ * Command Files:: Command files
968
+ * Quitting byebug:: How to leave byebug (quit, kill)
969
+ * Calling from Program:: Calling byebug from inside your program
970
+ @end menu
971
+
972
+ It is also possible to enter byebug when you have an uncaught
973
+ exception. See See also @ref{Post-Mortem Debugging}.
974
+
975
+ @node Starting byebug
976
+ @section Starting byebug
977
+
978
+ Although one can enter @DBG{} via Emacs (described in a later section)
979
+ and possibly others interfaces, probably the most familiar thing to do
980
+ is invoke byebug from a command line.
981
+
982
+ A wrapper shell script called @code{byebug} basically @code{require}'s
983
+ the gem package @code{byebug} and then loads @code{byebug}.
984
+
985
+ @smallexample
986
+ byebug [byebug-options] [--] @var{ruby-script} @var{ruby-script-arguments...}
987
+ @end smallexample
988
+
989
+ If you don't need to pass dash options to your program which might get
990
+ confused with byebug options, then you don't need to add the
991
+ @option{--}.
992
+
993
+ To get a brief list of options and descriptions, use the @code{--help}
994
+ option.
995
+
996
+ @smallexample
997
+ $ @b{byebug --help}
998
+ byebug @value{BYEBUG_VERSION}
999
+ Usage: byebug [options] <script.rb> -- <script.rb parameters>
1000
+
1001
+ Options:
1002
+ -A, --annotate LEVEL Set annotation level
1003
+ -c, --client Connect to remote byebug
1004
+ --cport PORT Port used for control commands
1005
+ -d, --debug Set $DEBUG=true
1006
+ --emacs Activates full Emacs support
1007
+ --emacs-basic Activates basic Emacs mode
1008
+ -h, --host HOST Host name used for remote debugging
1009
+ -I, --include PATH Add PATH to $LOAD_PATH
1010
+ --keep-frame-binding Keep frame bindings
1011
+ -m, --post-mortem Activate post-mortem mode
1012
+ --no-control Do not automatically start control thread
1013
+ --no-quit Do not quit when script finishes
1014
+ --no-rewrite-program Do not set $0 to the program being debugged
1015
+ --no-stop Do not stop when script is loaded
1016
+ -nx Not run byebug initialization files (e.g. .byebugrc
1017
+ -p, --port PORT Port used for remote debugging
1018
+ -r, --require SCRIPT Require the library, before executing your script
1019
+ --restart-script FILE Name of the script file to run. Erased after read
1020
+ --script FILE Name of the script file to run
1021
+ -s, --server Listen for remote connections
1022
+ -w, --wait Wait for a client connection, implies -s option
1023
+ -x, --trace Turn on line tracing
1024
+
1025
+ Common options:
1026
+ --verbose Turn on verbose mode
1027
+ --help Show this message
1028
+ --version Print the version
1029
+ -v Print version number, then turn on verbose mode
1030
+ @end smallexample
1031
+
1032
+ Options for the @code{byebug} are shown in the following list.
1033
+
1034
+ @menu
1035
+ * byebug command-line options:: Options you can pass to byebug
1036
+ * byebug default options:: How to Set Default Command-Line Options
1037
+ @end menu
1038
+
1039
+ @node byebug command-line options
1040
+ @subsection Options you can pass to byebug
1041
+
1042
+ You can run @DBG{} in various alternative modes---for example, as a
1043
+ program that interacts directly with the program in the same process
1044
+ on the same computer or via a socket to another process possibly on a
1045
+ different computer.
1046
+
1047
+ Many options appear as a long option name, such as @option{--help}, and
1048
+ a short one letter option name, such as @option{-h}. A double dash
1049
+ (@option{--} is used to separate options which go to @code{byebug} from
1050
+ options that are intended to go to your Ruby script. Options (if any)
1051
+ to @code{byebug} should come first. If there is no possibility of the
1052
+ Ruby script to be debugged getting confused with @code{byebug}'s
1053
+ option the double dash can be omitted.
1054
+
1055
+ @table @code
1056
+ @item --help
1057
+ @cindex @option{-h}
1058
+ @cindex @option{--help}
1059
+ This option causes @ttDBG{} to print some basic help and exit.
1060
+
1061
+ @item -v | --version
1062
+ @cindex @option{-v}
1063
+ This option causes @ttDBG{} to print its version number and exit.
1064
+
1065
+ @item -A | --annotate @var{level}
1066
+ @cindex @option{-A}
1067
+ @cindex @option{--annotation} @var{level}
1068
+ Set gdb-style annotation @var{level}, a number. Additional information is output
1069
+ automatically when program state is changed. This can be used by
1070
+ front-ends such as GNU Emacs to post this updated information without
1071
+ having to poll for it.
1072
+ @item -c | --client
1073
+ @cindex @option{-c}
1074
+ @cindex @option{--client}
1075
+ Connect to remote byebug. The remote byebug should have been set
1076
+ up previously our you will get a connection error and @code{byebug}
1077
+ will terminate.
1078
+
1079
+ @item --cport @var{port}
1080
+ @cindex @option{--cport} @var{port}
1081
+ Port used for control commands.
1082
+
1083
+ @item --debug
1084
+ @cindex @option{--debug}
1085
+ Set @code{$DEBUG} to @code{true}. This option is compatible with
1086
+ Ruby's.
1087
+
1088
+ @item --emacs
1089
+ Activates GNU Emacs mode.
1090
+ @c @pxref{GNU Emacs}.
1091
+ Byebug output is tagged in such a way to allow GNU Emacs to track
1092
+ where you are in the code.
1093
+
1094
+ @item --emacs-basic
1095
+ Activates full GNU Emacs mode.
1096
+ @c (@pxref{GNU Emacs}).
1097
+ This is the equivalent of setting the options @option{--emacs-basic},
1098
+ @code{annotate=3}, @option{--no-stop}, @option{-no-control} and
1099
+ @option{--post-mortem}.
1100
+
1101
+ @item -h | --host @var{host-address}
1102
+ Connect host address for remote debugging.
1103
+
1104
+ @item -I --include @var{PATH}
1105
+ @cindex @option{-I} @var{PATH}
1106
+ @cindex @option{--include} @var{PATH}
1107
+ Add @var{PATH} to @code{$LOAD_PATH}
1108
+
1109
+ @item --keep-frame-binding
1110
+ @cindex @option{--keep-frame-binding}
1111
+ Bindings are used to set the proper environment in evaluating
1112
+ expression inside byebug. Under normal circumstances, I don't
1113
+ believe most people will ever need this option.
1114
+
1115
+ By default, byebug doesn't create binding object for each frame
1116
+ when the frame is created, i.e. when a call is performed. Creating a
1117
+ binding is an expensive operation and has been a major source of
1118
+ performance problems.
1119
+
1120
+ Instead, byebug creates a binding when there is a need to
1121
+ evaluate expressions. The artificial binding that is created might be
1122
+ different from the real one. In particular, in performing constant
1123
+ and module name resolution.
1124
+
1125
+ However it's still possible to restore the old, slower behavior by
1126
+ using this option or by setting @code{Byebug.keep_frame_binding =
1127
+ true}. There are two possibilities for which you might want to use
1128
+ this option.
1129
+
1130
+ First, if you think there's a bug in the evaluation of variables, you
1131
+ might want to set this to see if this corrects things.
1132
+
1133
+ Second, since the internal structures that are used here @code{FRAME}
1134
+ and @code{SCOPE} are not part of the Ruby specification, it is
1135
+ possible they can change with newer releases; so here this option this
1136
+ may offer a remedy. (But you'll probably also have to hack the C code
1137
+ since it's likely under this scenario that byebug will no longer
1138
+ compile.) In fact, in Ruby 1.9 these structures have changed and that
1139
+ is partly why this byebug doesn't work on Ruby 1.9.
1140
+
1141
+ @item -m | --post-mortem
1142
+ @cindex @option{-m}
1143
+ @cindex @option{--post-mortem}
1144
+ If your program raises an exception that isn't caught you can enter
1145
+ byebug for inspection of what went wrong. You may also want to
1146
+ use this option in conjunction with @option{--no-stop}. See also
1147
+ @ref{Post-Mortem Debugging}.
1148
+
1149
+ @item --no-control
1150
+ @cindex @option{--no-control}
1151
+ Do not automatically start control thread.
1152
+
1153
+ @item --no-quit
1154
+ @cindex @option{--no-quit}
1155
+ Restart byebug when your program terminates normally.
1156
+
1157
+ @item --no-rewrite-program
1158
+ @cindex @option{--no-rewrite-program}
1159
+ Normally @code{byebug} will reset the program name @code{$0} from its
1160
+ name to the debugged program, and set the its name in variable
1161
+ @code{$RDEBUG_0}. In the unlikely even you don't want this use this option.
1162
+
1163
+ @item --no-stop
1164
+ @cindex @option{--no-stop}
1165
+ Normally the @code{byebug} stops before executing the first
1166
+ statement. If instead you want it to start running initially and will
1167
+ perhaps break it later in the running, use this options.
1168
+
1169
+ @item -p | --port @var{port}
1170
+ @cindex @option{-p} @var{port}
1171
+ @cindex @option{--port} @var{port}
1172
+ Port used for remote debugging.
1173
+
1174
+ @item -r | --require @var{library}
1175
+ @cindex @option{-r}
1176
+ @cindex @option{--require}
1177
+ Require the library, before executing your script. However if the
1178
+ library happened to be @code{debug}, we'll just ignore the require
1179
+ (since we're already a byebug). This option is compatible with Ruby's.
1180
+
1181
+ @item --script @var{file}
1182
+ @cindex @option{--script}
1183
+ Require the library, before executing your script. However if the
1184
+ library hap-pend to be @code{debug}, we'll just ignore the require
1185
+ (since we're already a byebug). This option is compatible with Ruby's.
1186
+
1187
+ @item -s | --server
1188
+ @cindex @option{-s}
1189
+ @cindex @option{--server}
1190
+ Debug the program but listen for remote connections on the default
1191
+ port or port set up via the @option{--port} option. See also @option{--wait}.
1192
+
1193
+ @item -w | --wait
1194
+ @cindex @option{-w}
1195
+ @cindex @option{--wait}
1196
+ Debug the program but stop waiting for a client connection first. This
1197
+ option automatically sets @option{--server} option.
1198
+
1199
+ @item -x | --trace
1200
+ @cindex @option{-x}
1201
+ @cindex @option{--trace}
1202
+ Turn on line tracing. Running @command{byebug --trace @emph{rubyscript.rb}}
1203
+ is much like running: @command{ruby -rtracer @emph{rubyscript.rb}}
1204
+
1205
+ If all you want to do however is get a linetrace, @code{tracer}, not
1206
+ @code{byebug}, may be faster:
1207
+ @smallexample
1208
+ $ @b{time ruby -rtracer gcd.rb 34 21 > /dev/null}
1209
+
1210
+ real 0m0.266s
1211
+ user 0m0.008s
1212
+ sys 0m0.000s
1213
+ $ @b{time byebug --trace gcd.rb 34 21 > /dev/null}
1214
+
1215
+ real 0m0.875s
1216
+ user 0m0.448s
1217
+ sys 0m0.056s
1218
+ $
1219
+ @end smallexample
1220
+
1221
+ @end table
1222
+
1223
+ @node byebug default options
1224
+ @subsection How to Set Default Command-Line Options
1225
+
1226
+ @DBG{} has many command-line options; it seems that some people want
1227
+ to set them differently from the our defaults. For example, some
1228
+ people may want @option{--no-quit --no-control} to be the default
1229
+ behavior. One could write a wrapper script or set a shell alias to
1230
+ handle this. @DBG{} has another way to do this as well. Before
1231
+ processing command options if the file @code{$HOME/.rdboptrc} is found
1232
+ (or, on Windows, @code{$HOME/rdbopt.ini}, it is loaded.
1233
+ If you want to set the defaults in some other way, you
1234
+ can put Ruby code here and set variable @code{options} which is an
1235
+ OpenStruct. For example here's how you'd set @option{-no-quit} and
1236
+ change the default control port to 5000.
1237
+
1238
+ @smallexample
1239
+ # This file contains how you want the default options to byebug
1240
+ # to be set. Any Ruby code can be put here.
1241
+ #
1242
+ # byebug # Uncomment if you want to debug byebug!
1243
+ options.control = false
1244
+ options.port = 5000
1245
+ puts "rocky's rdboptrc run"
1246
+ @end smallexample
1247
+
1248
+ Here are the default values in @code{options}
1249
+ @smallexample
1250
+ #<OpenStruct server=false, client=false, frame_bind=false, cport=8990, tracing=false, nx=false, post_mortem=false, port=8989, verbose_long=false, annotate=nil, control=true, restart_script=nil, quit=true, no_rewrite_program=false, stop=true, script=nil, host=nil, wait=false>
1251
+ @end smallexample
1252
+
1253
+
1254
+ @node Command Files
1255
+ @section Command files
1256
+
1257
+ @cindex command files
1258
+ A command file for @DBG{} is a file of lines that are @DBG{}
1259
+ commands. Comments (lines starting with @kbd{#}) may also be included.
1260
+ An empty line in a command file does nothing; it does not mean to repeat
1261
+ the last command, as it would from the terminal.
1262
+
1263
+ @cindex init file
1264
+ @cindex @file{.byebugrc}
1265
+ When you start @value{DBG}, it automatically executes commands from its
1266
+ @dfn{init files}, normally called @file{.byebugrc}.
1267
+
1268
+ On some configurations of @value{DBG}, the init file may be known by a
1269
+ different name. In particular on MS-Windows (but not cygwin)
1270
+ @file{byebug.ini} is used.
1271
+
1272
+ During startup, @DBG{} does the following:
1273
+
1274
+ @enumerate
1275
+ @item
1276
+ Processes command line options and operands.
1277
+
1278
+ @item
1279
+ Reads the init file in your current directory, if any, and failing
1280
+ that the home directory. The home directory is the directory named in
1281
+ the @code{HOME} or @code{HOMEPATH} environment variable.
1282
+
1283
+ Thus, you can have more than one init file, one generic in your home
1284
+ directory, and another, specific to the program you are debugging, in
1285
+ the directory where you invoke @DBG{}.
1286
+
1287
+ @item
1288
+ Reads command files specified by the @samp{--script} option.
1289
+ @end enumerate
1290
+
1291
+ You can also request the execution of a command file with the
1292
+ @code{source} command, @pxref{Source}.
1293
+
1294
+ @node Quitting byebug
1295
+ @section Quitting byebug
1296
+
1297
+ @cindex interrupt
1298
+ An interrupt (often @kbd{C-c}) does not exit from @value{DBG}, but
1299
+ rather terminates the action of any @DBG command that is in
1300
+ progress and returns to @value{DBG} command level. Inside a byebug
1301
+ command interpreter, use @code{quit} command (@pxref{Control, ,Quitting
1302
+ byebug}).
1303
+
1304
+ There way to terminate byebug is to use the @code{kill}
1305
+ command. This does more forceful @code{kill -9}. It can be used in
1306
+ cases where @code{quit} doesn't work.
1307
+
1308
+ @node Calling from Program
1309
+ @section Calling byebug from inside your Ruby program
1310
+
1311
+ Running a program from byebug adds a bit of overhead and slows
1312
+ down your program a little.
1313
+
1314
+ Furthermore, by necessity, byebugs change the operation of the
1315
+ program they are debugging. And this can lead to unexpected and
1316
+ unwanted differences. It has happened so often that the term
1317
+ ``Heisenbugs'' (see @url{http://en.wikipedia.org/wiki/Heisenbug}) was
1318
+ coined to describe the situation where the addition of the use of a
1319
+ byebug (among other possibilities) changes behavior of the program
1320
+ so that the bug doesn't manifest itself anymore.
1321
+
1322
+ There is another way to get into byebug which adds no overhead
1323
+ or slowdown until you reach the point at which you want to start
1324
+ debugging. However here you must change the script and make an
1325
+ explicit call to byebug. Because byebug isn't involved
1326
+ before the first call, there is no overhead and the script will run
1327
+ at the same speed as if there were no byebug.
1328
+
1329
+ There are three parts to calling byebug from inside the script,
1330
+ ``requiring'' byebug code, telling byebug to start
1331
+ tracking things and then making the call calling byebug to
1332
+ stop.
1333
+
1334
+ To get byebug class accessible from your Ruby program:
1335
+
1336
+ @smallexample
1337
+ require 'byebug'
1338
+ @end smallexample
1339
+ After @code{require 'byebug'}, it's possible to set some of the
1340
+ byebug variables influence preferences. For example if you want to
1341
+ have @ttDBG run a @code{list} command every time it stops you set the
1342
+ variable @code{Byebug.settings[:autolist]}. @pxref{Byebug.settings} has a
1343
+ list of variable settings and the default values. Byebug settings
1344
+ can also be set in @code{.byebugrc} as byebug
1345
+ commands. @pxref{Command Files}
1346
+
1347
+ To tell byebug to start tracking things:
1348
+
1349
+ @smallexample
1350
+ Byebug.start
1351
+ @end smallexample
1352
+
1353
+ There is also a @code{Byebug.stop} to turn off byebug tracking. If
1354
+ speed is crucial, you may want to start and stop this around certain
1355
+ sections of code. Alternatively, instead of issuing an explicit
1356
+ @code{Byebug.stop} you can add a block to the @code{Byebug.start}
1357
+ and debugging is turned on for that block. If the block of code raises
1358
+ an uncaught exception that would cause the block to terminate, the
1359
+ @code{stop} will occur. See @ref{Byebug.start with a block}.
1360
+
1361
+ And finally to enter byebug:
1362
+
1363
+ @smallexample
1364
+ byebug
1365
+ @end smallexample
1366
+
1367
+ As indicated above, when @code{byebug} is run a @code{.byebugrc}
1368
+ profile is read if that file exists.
1369
+
1370
+ You may want to do enter byebug at several points in the program
1371
+ where there is a problem you want to investigate. And since
1372
+ @code{byebug} is just a method call it's possible enclose it in a
1373
+ conditional expression, for example:
1374
+ @smallexample
1375
+ byebug if 'bar' == foo and 20 == iter_count
1376
+ @end smallexample
1377
+
1378
+ Although each step does a very specific thing which offers great
1379
+ flexibility, in order to make getting into byebug easier the
1380
+ three steps have been rolled into one command:
1381
+ @smallexample
1382
+ require "byebug/byebug"
1383
+ @end smallexample
1384
+
1385
+ @node Byebug Command Reference
1386
+ @chapter @code{byebug} Command Reference
1387
+
1388
+ @menu
1389
+ * Command Interfaces:: The kinds of interface used to interact with byebug
1390
+ * Command Syntax:: How to give commands to byebug
1391
+ * Command Output:: How byebug presents its output
1392
+ * Help:: How to ask for help (help)
1393
+ * Control:: Controlling byebug (quit, restart, interrupt)
1394
+ * DisplayCommands:: Executing expressions on stop (display, undisplay)
1395
+ * PrintCommands:: Evaluating and Printing Expressions (p, pp, ps, pp, irb)
1396
+ * PrintVars:: Printing Variables (var)
1397
+ * List:: Examining Program Source Files (list)
1398
+ * Edit:: Editing source files (edit)
1399
+ * FrameCommands:: Examining the stack frame (where, up, down, frame)
1400
+ * Stopping:: Stopping and continuing (break, watch, step, cont...)
1401
+ * byebug settings:: byebug-settings (set args, set autoeval, ...)
1402
+ * Program Information:: Program Status (info)
1403
+ @end menu
1404
+
1405
+ @node Command Interfaces
1406
+ @section Command Interfaces
1407
+ There are several ways one can talk to @code{byebug} and get
1408
+ results. The simplest way is via a command-line interface directly
1409
+ talking to byebug. This is referred to below as a ``Local
1410
+ Interface''. It's also possible to run byebug and set up a port
1411
+ by which some other process can connect and control the debug
1412
+ session. This is called a ``Remote Interface''. When you want to gain
1413
+ access to a remote interface you need to run @code{byebug} using a
1414
+ ``Control Interface''. This interface might not be the same process as
1415
+ the process running the debugged program and might not even be
1416
+ running on the same computer.
1417
+
1418
+ Other front-ends may use one of these and build on top and provide
1419
+ other (richer) interfaces. Although many of the commands are available
1420
+ on all interfaces some are not. Most of the time in this manual when
1421
+ we talk about issuing commands describing the responses elicited,
1422
+ we'll assume we are working with the local interface.
1423
+
1424
+ @node Command Syntax
1425
+ @section Command Syntax
1426
+ Usually a command is put on a single line. There is no limit on how long
1427
+ it can be. It starts with a command name, which is followed by
1428
+ arguments whose meaning depends on the command name. For example, the
1429
+ command @code{step} accepts an argument which is the number of times to
1430
+ step, as in @code{step 5}. You can also use the @code{step} command with no
1431
+ arguments. Some commands do not allow any arguments.
1432
+
1433
+ Multiple commands can be put on a line by separating each with a
1434
+ semicolon (@code{;}). You can disable the meaning of a semicolon to
1435
+ separate commands by escaping it with a backslash.
1436
+
1437
+ For example, if you have @code{autoeval} (@ref{Autoeval}) set, you
1438
+ might want to enter the following code to compute the 5th Fibonacci
1439
+ number:
1440
+ @smallexample
1441
+ # Compute the 5 Fibonaci number
1442
+ (rdb:1) set autoeval on
1443
+ (rdb:1) fib1=0; fib2=1; 5.times @{|temp| temp=fib1; fib1=fib2; fib2 += temp @}
1444
+ SyntaxError Exception: compile error
1445
+ /usr/bin/irb:10: syntax error, unexpected $end, expecting '@}'
1446
+ 5.times @{|temp| temp=fib1
1447
+ ^
1448
+ (rdb:1) fib1=0\; fib2=1\; 5.times @{|temp| temp=fib1\; fib1=fib2\; fib2 += temp @}
1449
+ 5
1450
+ (rdb:1) fib2
1451
+ fib2
1452
+ 8
1453
+ @end smallexample
1454
+ You might also consider using the @code{irb} command, @ref{irb}, and
1455
+ then you won't have to escape semicolons.
1456
+
1457
+ A blank line as input (typing just @key{<RET>}) means to repeat the
1458
+ previous command.
1459
+
1460
+ In the ``local'' interface, the Ruby Readline module is used. It
1461
+ handles line editing and retrieval of previous commands. Up arrow, for
1462
+ example moves to the previous byebug command; down arrow moves to
1463
+ the next more recent command (provided you are not already at the last
1464
+ command). Command history is saved in file @code{.byebug_hist}. A
1465
+ limit is put on the history size. You can see this with the @code{show
1466
+ history size} command. See @ref{History} for history parameters.
1467
+
1468
+ @node Command Output
1469
+ @section Command Output
1470
+
1471
+ In the command-line interface, when @code{byebug} is waiting for
1472
+ input it presents a prompt of the form
1473
+ @code{(rdb:}@emph{x}@code{)}. If debugging locally, @emph{x} will be
1474
+ the thread number. Usual the main thread is 1, so often you'll see
1475
+ @code{(rdb:1)}. In the control interface though @emph{x} will be
1476
+ @code{ctrl} and in post-mortem debugging @code{post-mortem}.
1477
+
1478
+ In the local interface, whenever @code{byebug} gives an error
1479
+ message such as for an invalid command, or an invalid location
1480
+ position, it will generally preface the message with
1481
+ @code{***}. However if annotation mode is on that the message is put
1482
+ in a @code{begin-error} annotation and no @code{***} appears.
1483
+
1484
+ @node Help
1485
+ @section Getting help (@samp{help})
1486
+ @cindex on-line documentation
1487
+ @menu
1488
+ * Help for Subcommands::
1489
+ @end menu
1490
+
1491
+ Once inside @code{byebug} you can always ask it for information on
1492
+ its commands, using the command @code{help}.
1493
+
1494
+ @table @code
1495
+ @kindex h @r{(@code{help})}
1496
+ @kindex help @ovar{command-name}
1497
+ @item help
1498
+ @itemx h
1499
+ You can use @code{help} (abbreviated @code{h}) with no arguments to
1500
+ display a short list of named classes of commands:
1501
+
1502
+ @flushleft
1503
+ @smallexample
1504
+ (rdb:1) @b{help}
1505
+ byebug help v@value{BYEBUG_VERSION}
1506
+ Type 'help <command-name>' for help on a specific command
1507
+
1508
+ Available commands:
1509
+ backtrace delete enable help list ps save thread where
1510
+ break disable eval info method putl set trace
1511
+ catch display exit irb next quit show undisplay
1512
+ condition down finish jump p reload source up
1513
+ continue edit frame kill pp restart step var
1514
+ @end smallexample
1515
+ @end flushleft
1516
+ @c the above line break eliminates huge line overfull...
1517
+
1518
+ @end table
1519
+
1520
+ @table @code
1521
+ @item help @var{command}
1522
+ With a command name as @code{help} argument, @DBG displays short
1523
+ information on how to use that command.
1524
+
1525
+ @smallexample
1526
+ (rdb:1) @b{help list}
1527
+ byebug help v@value{BYEBUG_VERSION}
1528
+ l[ist] list forward
1529
+ l[ist] - list backward
1530
+ l[ist] = list current line
1531
+ l[ist] nn-mm list given lines
1532
+ * NOTE - to turn on autolist, use 'set autolist'
1533
+ (rdb:1)
1534
+ @end smallexample
1535
+ @end table
1536
+
1537
+ @node Help for Subcommands
1538
+ @subsection Help on Subcommands
1539
+ A number of commands have many sub-parameters or
1540
+ @emph{subcommands}. These include @code{info}, @code{set},
1541
+ @code{show}, @code{enable} and @code{disable}.
1542
+
1543
+ When you ask for help for one of these commands, you will get help for
1544
+ all of the subcommands that that command offers. Sometimes you may
1545
+ want help that subcommand and to do this just follow the command with
1546
+ its subcommand name. For example @code{help set annotate} will just
1547
+ give help about the annotate command. Furthermore it will give longer
1548
+ help than the summary information that appears when you ask for
1549
+ help. You don't need to list the full subcommand name, but just enough
1550
+ of the letters to make that subcommand distinct from others will
1551
+ do. For example, @code{help set an} is the same as @code{help set annotate}.
1552
+
1553
+ Some examples follow.
1554
+ @example
1555
+ (rdb:1) @b{help info}
1556
+ Generic command for showing things about the program being debugged.
1557
+ --
1558
+ List of info subcommands:
1559
+ --
1560
+ info args -- Argument variables of current stack frame
1561
+ info breakpoints -- Status of user-settable breakpoints
1562
+ info catch -- Exceptions that can be caught in the current stack frame
1563
+ info display -- Expressions to display when program stops
1564
+ info file -- Info about a particular file read in
1565
+ info files -- File names and timestamps of files read in
1566
+ info global_variables -- Global variables
1567
+ info instance_variables -- Instance variables of the current stack frame
1568
+ info line -- Line number and file name of current position in source file
1569
+ info locals -- Local variables of the current stack frame
1570
+ info program -- Execution status of the program
1571
+ info stack -- Backtrace of the stack
1572
+ info thread -- List info about thread NUM
1573
+ info threads -- information of currently-known threads
1574
+ info variables -- Local and instance variables of the current stack frame
1575
+ @end example
1576
+
1577
+ @example
1578
+ (rdb:1) @b{help info breakpoints}
1579
+ Status of user-settable breakpoints.
1580
+ Without argument, list info about all breakpoints. With an
1581
+ integer argument, list info on that breakpoint.
1582
+ @end example
1583
+
1584
+ @example
1585
+ (rdb:1) @b{help info br}
1586
+ Status of user-settable breakpoints.
1587
+ Without argument, list info about all breakpoints. With an
1588
+ integer argument, list info on that breakpoint.
1589
+ @end example
1590
+
1591
+ @node Control
1592
+ @section Controlling byebug (@samp{quit}, @samp{restart}, @samp{interrupt}, @samp{source})
1593
+
1594
+ @menu
1595
+ * Quit:: Quitting byebug (quit)
1596
+ * Restart:: Restarting Script execution (restart)
1597
+ * Interrupt:: Interrupting byebug (interrupt)
1598
+ * Source:: Running Byebug commands (source)
1599
+ @end menu
1600
+
1601
+ @node Quit
1602
+ @subsection Quit (@samp{quit})
1603
+ @table @code
1604
+ @kindex quit @r{[}unconditionally@r{]}
1605
+ @kindex q @r{(@code{quit})}
1606
+ @item quit @r{[}unconditionally@r{]}
1607
+ @item exit
1608
+ @itemx q
1609
+
1610
+ To exit @value{DBG}, use the @code{quit} command (abbreviated
1611
+ @code{q}), or alias @code{exit}.
1612
+
1613
+ A simple @code{quit} tries to terminate all threads in effect.
1614
+
1615
+ Normally if you are in an interactive session, this command will
1616
+ prompt to ask if you really want to quit. If you don't want any
1617
+ questions asked, enter the ``unconditionally''.
1618
+
1619
+ @end table
1620
+
1621
+ @node Restart
1622
+ @subsection Restart (@samp{restart})
1623
+ @table @code
1624
+ @kindex restart @r{[}@var{program args}@r{]}
1625
+ @kindex R @r{(@code{restart})}
1626
+ @item restart
1627
+ @itemx R
1628
+
1629
+ Restart the program. This is a re-exec - all byebug state is
1630
+ lost. If command arguments are passed those are used. Otherwise the
1631
+ last program arguments used in the last invocation are used.
1632
+
1633
+ In not all cases will you be able to restart the program. First, the
1634
+ program should have been invoked at the outset rather than having been
1635
+ called from inside your program or invoked as a result of post-mortem
1636
+ handling.
1637
+
1638
+ Also, since this relies on the the OS @code{exec} call, this command
1639
+ is available only if your OS supports that @code{exec}; OSX for
1640
+ example does not (yet).
1641
+ @end table
1642
+
1643
+ @node Interrupt
1644
+ @subsection Interrupt (@samp{interrupt})
1645
+ @table @code
1646
+ @kindex interrupt
1647
+ @kindex i
1648
+ @item interrupt
1649
+ @itemx i
1650
+ Interrupt the program. Useful if there are multiple threads running.
1651
+ @end table
1652
+
1653
+ @node Source
1654
+ @subsection Running Byebug Commands (@samp{source})
1655
+ @table @code
1656
+ @kindex source @var{filename}
1657
+ @item source @var{filename}
1658
+ Execute the command file @var{filename}.
1659
+
1660
+ The lines in a command file are executed sequentially. They are not
1661
+ printed as they are executed. If there is an error, execution
1662
+ proceeds to the next command in the file. For information about
1663
+ command files that get run automatically on startup, @pxref{Command Files}.
1664
+ @end table
1665
+
1666
+ @node DisplayCommands
1667
+ @section Executing expressions on stop (@samp{display}, @samp{undisplay})
1668
+ @cindex automatic display
1669
+ @cindex display of expressions
1670
+
1671
+ If you find that you want to print the value of an expression
1672
+ frequently (to see how it changes), you might want to add it to the
1673
+ @dfn{automatic display list} so that @value{DBG} evaluates a statement
1674
+ each time your program stops or the statement is shown in line tracing.
1675
+ Each expression added to the list is given a number to identify it; to
1676
+ remove an expression from the list, you specify that number. The
1677
+ automatic display looks like this:
1678
+
1679
+ @smallexample
1680
+ (rdb:1) display n
1681
+ 1: n = 3
1682
+ @end smallexample
1683
+
1684
+ @noindent
1685
+ This display shows item numbers, expressions and their current values.
1686
+ If the expression is undefined or illegal the expression will be
1687
+ printed but no value will appear.
1688
+
1689
+ @smallexample
1690
+ (rdb:1) display undefined_variable
1691
+ 2: undefined_variable =
1692
+ (rdb:1) display 1/0
1693
+ 3: 1/0 =
1694
+ @end smallexample
1695
+
1696
+ Note: this command uses @code{to_s} to in expressions; for example an
1697
+ array @code{[1, 2]} will appear as @code{12}. For some datatypes like
1698
+ an Array, you may want to call the @code{inspect} method, for example
1699
+ @code{display ARGV.inspect} rather than @code{display ARGV}.
1700
+
1701
+ @table @code
1702
+ @kindex display @ovar{expr}
1703
+ @item display @var{expr}
1704
+ Add the expression @var{expr} to the list of expressions to display
1705
+ each time your program stops or a line is printed when linetracing is
1706
+ on (@pxref{DisplayCommands}).
1707
+
1708
+ @item display
1709
+ Display the current values of the expressions on the list, just as is
1710
+ done when your program stops.
1711
+
1712
+ @kindex undisplay @ovar{num}
1713
+ @item undisplay @ovar{num}
1714
+ @itemx delete display @var{num}
1715
+ Remove item number @var{num} from the list of expressions to display.
1716
+
1717
+ @kindex info display
1718
+ @item info display
1719
+ Show all display expressions
1720
+
1721
+ @ifset GDB_COMPLETED
1722
+ @code{undisplay} does not repeat if you press @key{RET} after using it.
1723
+ (Otherwise you would just get the error @samp{No display number @dots{}}.)
1724
+ @end ifset
1725
+
1726
+ @kindex disable display
1727
+ @item disable display @var{dnums}@dots{}
1728
+ Disable the display of item numbers @var{dnums}. A disabled display
1729
+ item is not printed automatically, but is not forgotten. It may be
1730
+ enabled again later.
1731
+
1732
+ @kindex enable display
1733
+ @item enable display @var{dnums}@dots{}
1734
+ Enable display of item numbers @var{dnums}. It becomes effective once
1735
+ again in auto display of its expression, until you specify otherwise.
1736
+
1737
+ @end table
1738
+
1739
+ @node PrintCommands
1740
+ @section Evaluating and Printing Expressions (@samp{p}, @samp{pp}, @samp{putl}, @samp{ps}, @samp{irb})
1741
+
1742
+ One way to examine and change data in your script is with the
1743
+ @code{eval} command (abbreviated @code{p}). A similar command is
1744
+ @code{pp} which tries to pretty print the result. Finally @code{irb} is
1745
+ useful when you anticipate examining or changing a number of things,
1746
+ and prefer not to have to preface each command, but rather work as one
1747
+ does in @code{irb}.
1748
+
1749
+ @menu
1750
+ * eval:: eval or print an expression (eval, p)
1751
+ * pp:: pretty print an expression (pp, ps, putl)
1752
+ * irb:: running irb using the current context
1753
+ @end menu
1754
+
1755
+ @node eval
1756
+ @subsection Printing an expression (@samp{eval}, @samp{p})
1757
+ @table @code
1758
+ @kindex eval @var{expr}
1759
+ @kindex p @r{(@code{eval})}
1760
+ @item eval @var{expr}
1761
+ @itemx p @var{expr}
1762
+
1763
+ Use @code{eval} or @code{p} to evaluate a Ruby expression, @var{expr},
1764
+ same as you would if you were in @code{irb}. If there are many expressions
1765
+ you want to look at, you may want to go into irb from byebug.
1766
+ @smallexample
1767
+ @group
1768
+ (rdb:p) p n
1769
+ 3
1770
+ (rdb:1) p "the value of n is #@{n@}"
1771
+ "the value of n is 3"
1772
+ (rdb:1)
1773
+ @end group
1774
+ @end smallexample
1775
+ @end table
1776
+
1777
+ @node pp
1778
+ @subsection Pretty-Printing an expression (@samp{pp}, @samp{putl}, @samp{ps}))
1779
+ @table @code
1780
+ @item pp
1781
+ @kindex pp @var{expr}
1782
+ Evaluates and pretty-prints @var{expr}
1783
+ @smallexample
1784
+ @group
1785
+ (rdb:1) @b{p $LOAD_PATH}
1786
+ ["/home/rocky/lib/ruby", "/usr/lib/ruby/site_ruby/1.8", "/usr/lib/ruby/site_ruby/1.8/i586-linux", "/usr/lib/ruby/1.8"]
1787
+ (rdb:1) @b{pp $LOAD_PATH}
1788
+ ["/home/rocky/lib/ruby",
1789
+ "/usr/lib/ruby/site_ruby/1.8",
1790
+ "/usr/lib/ruby/site_ruby/1.8/i586-linux",
1791
+ "/usr/lib/ruby/1.8"]
1792
+ @end group
1793
+ @end smallexample
1794
+ @kindex putl
1795
+ @item putl
1796
+ If the value you want to print is an array, sometimes a columnized
1797
+ list looks nicer:
1798
+ @smallexample
1799
+ @group
1800
+ (rdb:1) @b{putl $LOAD_PATH}
1801
+ /home/rocky/lib/ruby /usr/lib/ruby/site_ruby/1.8
1802
+ /usr/lib/ruby/site_ruby/1.8/i586-linux /usr/lib/ruby/1.8
1803
+ @end group
1804
+ @end smallexample
1805
+
1806
+ Note however that entries are sorted to run down first rather than
1807
+ across. So in the example above the second entry in the list is
1808
+ @code{/usr/lib/ruby/site_ruby/1.8/i586-linux} and the @emph{third} entry is
1809
+ @code{/usr/lib/ruby/site_ruby/1.8}.
1810
+
1811
+ If the value is not an array @code{putl} will just call pretty-print.
1812
+ @kindex ps
1813
+ @item ps
1814
+ Sometimes you may want to print the array not only columnized, but
1815
+ sorted as well. The list of byebug help commands appears this way,
1816
+ and so does the output of the @code{method} commands.
1817
+
1818
+ @smallexample
1819
+ @group
1820
+ (rdb:1) ps Kernel.private_methods
1821
+ Digest initialize y
1822
+ Pathname initialize_copy
1823
+ Rational location_of_caller
1824
+ active_gem_with_options method_added
1825
+ alias_method method_removed
1826
+ append_features method_undefined
1827
+ attr module_function
1828
+ attr_accessor private
1829
+ attr_reader protected
1830
+ attr_writer public
1831
+ class_variable_get remove_class_variable
1832
+ class_variable_set remove_const
1833
+ define_method remove_instance_variable
1834
+ extend_object remove_method
1835
+ extended singleton_method_added
1836
+ gcd singleton_method_removed
1837
+ gem_original_require singleton_method_undefined
1838
+ include timeout
1839
+ included undef_method
1840
+ @end group
1841
+ @end smallexample
1842
+
1843
+ If the value is not an array, @code{ps} will just call pretty-print.
1844
+ See also the @code{methods}.
1845
+ @end table
1846
+
1847
+ @node irb
1848
+ @subsection Run irb (@samp{irb})
1849
+ @table @code
1850
+ @kindex irb
1851
+ @item irb
1852
+ Run an interactive ruby session (@code{irb}) with the bindings
1853
+ environment set to the state you are in the program.
1854
+
1855
+ When you leave irb and go back to byebug command prompt we show
1856
+ again the file, line and text position of the program in the same way
1857
+ as when entered byebug. If you issue a @command{list} without
1858
+ location information, the default location used is the current line
1859
+ rather than the position may have gotten updated via a prior
1860
+ @command{list} command.
1861
+ @smallexample
1862
+ triangle.rb:4
1863
+ def triangle(n)
1864
+ (rdb:1) @b{list}
1865
+ [-1, 8] in /home/rocky/ruby/triangle.rb
1866
+ 1 #!/usr/bin/env ruby
1867
+ 2 # Compute the n'th triangle number - the hard way
1868
+ 3 # triangle(n) == (n * (n+1)) / 2
1869
+ => 4 def triangle(n)
1870
+ 5 tri = 0
1871
+ 6 0.upto(n) do |i|
1872
+ 7 tri += i
1873
+ 8 end
1874
+ @b{irb}
1875
+ >> @b{(0..6).inject@{|sum, i| sum +=i@}}
1876
+ => 21
1877
+ >> @b{exit}
1878
+ triangle.rb:4
1879
+ def triangle(n)
1880
+ (rdb:1) @b{list # Note we get the same line range as before going into irb}
1881
+ [-1, 8] in /home/rocky/ruby/triangle.rb
1882
+ 1 #!/usr/bin/env ruby
1883
+ 2 # Compute the n'th triangle number - the hard way
1884
+ 3 # triangle(n) == (n * (n+1)) / 2
1885
+ => 4 def triangle(n)
1886
+ 5 tri = 0
1887
+ 6 0.upto(n) do |i|
1888
+ 7 tri += i
1889
+ 8 end
1890
+ @end smallexample
1891
+
1892
+ @end table
1893
+
1894
+ @node PrintVars
1895
+ @section Printing Variables (@samp{var}, @samp{method})
1896
+
1897
+ @table @code
1898
+ @item var const @var{object}
1899
+ @kindex var const @var{expr}
1900
+ Show the constants of @var{object}. This is basically listing
1901
+ variables and their values in @var{object}@code{.constant}.
1902
+ @item var instance @var{object}
1903
+ @kindex var instance @var{expr}
1904
+ Show the instance variables of @var{object}. This is basically listing
1905
+ @var{object}@code{.instance_variables}.
1906
+ @item info instance_variables
1907
+ @kindex info instance_variables
1908
+ Show instance_variables of @code{@@self}
1909
+ @item info locals
1910
+ @kindex info locals
1911
+ Show local variables
1912
+ @item info globals
1913
+ @kindex info globals
1914
+ Show global variables
1915
+ @item info variables
1916
+ @kindex info variables
1917
+ Show local and instance variables of @code{@@self}
1918
+ @item method instance @var{object}
1919
+ @kindex method instance @var{object}
1920
+ Show methods of @var{object}. Basically this is the same as running
1921
+ @code{ps object.instance_methods(false)} on @var{object}.
1922
+ @item method iv @var{object}
1923
+ @kindex method iv @var{object}
1924
+ Show method instance variables of @var{object}. Basically this is the same as running
1925
+ @smallexample
1926
+ obj.instance_variables.each do |v|
1927
+ puts "%s = %s\n" % [v, obj.instance_variable_get(v)]
1928
+ end
1929
+ @end smallexample
1930
+ on @var{object}.
1931
+ @item signature @var{object}
1932
+ @kindex method signature @var{object}
1933
+ Show procedure signature of method @var{object}.
1934
+ @emph{This command is available only if the nodewrap is installed.}
1935
+ @smallexample
1936
+ def mymethod(a, b=5, &bock)
1937
+ end
1938
+ (rdb:1) @b{method sig mymethod}
1939
+ Mine#mymethod(a, b=5, &bock)
1940
+ @end smallexample
1941
+ on @var{object}.
1942
+ @item method @var{class-or-module}
1943
+ @kindex method @var{class-or-module}
1944
+ Show methods of the class or module, @var{class-or-module}. Basically
1945
+ this is the same as running @code{ps object.methods} on @var{class-or-module}.
1946
+ on @var{class-or-module}.
1947
+ @end table
1948
+
1949
+ @node List
1950
+ @section Examining Program Source Files (@samp{list})
1951
+
1952
+ @cindex current line
1953
+ @value{DBG} can print parts of your script's source. When your script
1954
+ stops, @value{DBG} spontaneously prints the line where it stopped and
1955
+ the text of that line. Likewise, when you select a stack frame
1956
+ (@pxref{Selection}) @value{DBG} prints the line where execution in
1957
+ that frame has stopped. Implicitly there is a default line
1958
+ location. Each time a list command is run that implicit location is
1959
+ updated, so that running several list commands in succession shows a
1960
+ contiguous block of program text.
1961
+
1962
+ You can print other portions of source files by giving an explicit
1963
+ position as a parameter to the list command.
1964
+
1965
+ If you use @value{DBG} through its Emacs interface, you may prefer to
1966
+ use Emacs facilities to view source.
1967
+ @c @pxref{GNU Emacs}.
1968
+
1969
+ @kindex list @ovar{line-number}
1970
+ @kindex l @r{(@code{list})}
1971
+ To print lines from a source file, use the @code{list} command
1972
+ (abbreviated @code{l}). By default, ten lines are printed. Fewer may
1973
+ appear if there fewer lines before or after the current line to center
1974
+ the listing around.
1975
+
1976
+ There are several ways to specify what part of the file you want to print.
1977
+ Here are the forms of the @code{list} command.
1978
+
1979
+ @table @code
1980
+ @item list @var{line-number}
1981
+ @itemx l @var{line-number}
1982
+ Print lines centered around line number @var{line-number} in the
1983
+ current source file.
1984
+
1985
+ @item list
1986
+ @itemx l
1987
+ Print more lines. If the last lines printed were printed with a
1988
+ @code{list} command, this prints lines following the last lines
1989
+ printed; however, if the last line printed was a solitary line printed
1990
+ as part of displaying a stack frame (@pxref{Frames}), this prints lines
1991
+ centered around that line.
1992
+
1993
+ @item list -
1994
+ @itemx l -
1995
+ Print lines just before the lines last printed.
1996
+ @item list @var{first}-@var{last}
1997
+ Print lines between @var{first} and @var{last} inclusive.
1998
+
1999
+ @item list =
2000
+ Print lines centered around where the script is stopped.
2001
+ @end table
2002
+
2003
+ Repeating a @code{list} command with @key{RET} discards the argument, so it is
2004
+ equivalent to typing just @code{list}. This is more useful than listing the
2005
+ same lines again. An exception is made for an argument of @samp{-}; that
2006
+ argument is preserved in repetition so that each repetition moves up in the
2007
+ source file.
2008
+
2009
+ @node Edit
2010
+ @section Editing Source files (@samp{edit})
2011
+
2012
+ To edit the lines in a source file, use the @code{edit} command. The editing
2013
+ program of your choice is invoked with the current line set to the active line
2014
+ in the program. Alternatively, you can give a line specification to specify
2015
+ what part of the file you want to print if you want to see other parts of the
2016
+ program.
2017
+
2018
+ You can customize to use any editor you want by using the @code{EDITOR}
2019
+ environment variable. The only restriction is that your editor (say @code{ex})
2020
+ recognizes the following command-line syntax:
2021
+ @smallexample
2022
+ ex +@var{number} file
2023
+ @end smallexample
2024
+ The optional numeric value +@var{number} specifies the number of the line in the
2025
+ file where to start editing. For example, to configure @value{DBG} to use the
2026
+ @code{vi} editor, you could use these commands with the @code{sh} shell:
2027
+ @smallexample
2028
+ EDITOR=/usr/bin/vi
2029
+ export EDITOR
2030
+ gdb @dots{}
2031
+ @end smallexample
2032
+ or in the @code{csh} shell,
2033
+ @smallexample
2034
+ setenv EDITOR /usr/bin/vi
2035
+ gdb @dots{}
2036
+ @end smallexample
2037
+
2038
+ @table @code
2039
+ @kindex edit @ovar{line-specification}
2040
+ @item edit @ovar{line specification}
2041
+ Edit line specification using the editor specified by the
2042
+ @code{EDITOR} environment variable.
2043
+ @end table
2044
+
2045
+ @node FrameCommands
2046
+ @section Examining the Stack Frame (@samp{where}, @samp{up}, @samp{down}, @samp{frame})
2047
+
2048
+ When your script has stopped, one thing you'll probably want to know
2049
+ is where it stopped and some idea of how it got there.
2050
+
2051
+ @cindex call stack
2052
+ Each time your script performs a function or sends a message to a
2053
+ method, or enters a block, information about this action is saved.
2054
+ The frame stack then is this a history of the blocks that got you to
2055
+ the point that you are currently stopped at.@footnote{More accurately
2056
+ we should call this a ``block stack''; but we'll use the name that is
2057
+ more commonly used. And internally in Ruby, there is ``FRAME''
2058
+ structure which is yet slightly different.}
2059
+
2060
+ @cindex selected block
2061
+ One entry in call stack is @dfn{selected} by @DBG{} and many
2062
+ @DBG commands refer implicitly to the selected block. In
2063
+ particular, whenever you ask @DBG to list lines without giving
2064
+ a line number or location the value is found in the selected frame.
2065
+ There are special @DBG commands to select whichever frame you
2066
+ are interested in. @xref{Selection, ,Selecting a frame}.
2067
+
2068
+ When your program stops, @DBG{} automatically selects the
2069
+ currently executing frame and describes it briefly, similar to the
2070
+ @code{frame} command.
2071
+
2072
+ After switching frames, when you issue a @code{list} command without
2073
+ any position information, the position used is location in the frame
2074
+ that you just switched between, rather than a location that got
2075
+ updated via a prior @code{list} command.
2076
+
2077
+ @menu
2078
+ * Frames:: Stack frames
2079
+ * Backtrace:: Backtraces (where)
2080
+ * Selection:: Selecting a frame (up, down, frame)
2081
+
2082
+ @end menu
2083
+
2084
+ @node Frames
2085
+ @subsection Stack frames
2086
+
2087
+ @cindex frame, definition
2088
+ @cindex stack frame
2089
+ The block stack is divided up into contiguous pieces called @dfn{stack
2090
+ frames}, @dfn{frames}, or @dfn{blocks} for short; each frame/block has
2091
+ a scope associated with it; It contains a line number and the
2092
+ source-file name that the line refers. If the frame/block is the beginning
2093
+ of a method or function it also contains the function name.
2094
+
2095
+ @cindex initial frame
2096
+ @cindex outermost frame
2097
+ @cindex innermost frame
2098
+ When your script is started, the stack has only one frame, that of the
2099
+ function @code{main}. This is called the @dfn{initial} frame or the
2100
+ @dfn{outermost} frame. Each time a function is called, a new frame is
2101
+ made. Each time a function returns, the frame for that function invocation
2102
+ is eliminated. If a function is recursive, there can be many frames for
2103
+ the same function. The frame for the function in which execution is
2104
+ actually occurring is called the @dfn{innermost} frame. This is the most
2105
+ recently created of all the stack frames that still exist.
2106
+
2107
+ @cindex frame number
2108
+ @value{DBG} assigns numbers to all existing stack frames, starting with
2109
+ zero for the innermost frame, one for the frame that called it,
2110
+ and so on upward. These numbers do not really exist in your script;
2111
+ they are assigned by @value{DBG} to give you a way of designating stack
2112
+ frames in @value{DBG} commands.
2113
+
2114
+ @node Backtrace
2115
+ @subsection Backtraces (@samp{where})
2116
+
2117
+ @cindex backtraces
2118
+ @cindex tracebacks
2119
+ @cindex stack traces
2120
+ A backtrace is essentially the same as the call stack: a summary of
2121
+ how your script got where it is. It shows one line per frame, for
2122
+ many frames, starting with the place that you are stopped at (frame
2123
+ zero), followed by its caller (frame one), and on up the stack.
2124
+
2125
+ @table @code
2126
+ @kindex where
2127
+ @kindex w @r{(@code{where})}
2128
+ @itemx where
2129
+ Print the entire stack frame; @code{info stack} is an alias for this command.
2130
+ Each frame is numbered and can be referred to in the @code{frame}
2131
+ command; @code{up} and @code{down} add or subtract respectively to
2132
+ frame numbers shown. The position of the current frame is marked with
2133
+ @code{-->}.
2134
+
2135
+ @smallexample
2136
+ (rdb:1) where
2137
+ --> #0 Object.gcd(a#Fixnum, b#Fixnum) at line /tmp/gcd.rb:6
2138
+ #1 at line /tmp/gcd.rb:19
2139
+ @end smallexample
2140
+
2141
+ @ifset FINISHED
2142
+ @item backtrace @var{n}
2143
+ @itemx bt @var{n}
2144
+ @itemx where @var{n}
2145
+ @itemx T @var{n}
2146
+ Similar, but print only the innermost @var{n} frames.
2147
+
2148
+ @item backtrace -@var{n}
2149
+ @itemx bt -@var{n}
2150
+ @itemx where -@var{n}
2151
+ @itemx T -@var{n}
2152
+ Similar, but print only the outermost @var{n} frames.
2153
+ @end ifset
2154
+ @end table
2155
+
2156
+ @node Selection
2157
+ @subsection Selecting a frame (@samp{up}, @samp{down}, @samp{frame})
2158
+
2159
+ Commands for listing source code in your script work on whichever
2160
+ stack frame is selected at the moment. Here are the commands for
2161
+ selecting a stack frame; all of them finish by printing a brief
2162
+ description of the stack frame just selected.
2163
+
2164
+ @table @code
2165
+ @kindex up @ovar{n}
2166
+ @item up @ovar{n}
2167
+ Move @var{n} frames up the stack. For positive numbers @var{n}, this
2168
+ advances toward the outermost frame, to higher frame numbers, to
2169
+ frames that have existed longer. Using a negative @var{n} is the same thing
2170
+ as issuing a @code{down} command of the absolute value of the @var{n}.
2171
+ Using zero for @var{n} does no frame adjustment, but since the current
2172
+ position is redisplayed, it may trigger a resynchronization if there is
2173
+ a front end also watching over things.
2174
+
2175
+ @var{n} defaults to one. You may abbreviate @code{up} as @code{u}.
2176
+
2177
+ @kindex down @ovar{n}
2178
+ @item down @ovar{n}
2179
+ Move @var{n} frames down the stack. For positive numbers @var{n}, this
2180
+ advances toward the innermost frame, to lower frame numbers, to frames
2181
+ that were created more recently. Using a negative @var{n} is the same
2182
+ as issuing a @code{up} command of the absolute value of the @var{n}.
2183
+ Using zero for @var{n} does no frame adjustment, but since the current
2184
+ position is redisplayed, it may trigger a resynchronization if there is
2185
+ a front end also watching over things.
2186
+
2187
+ @var{n} defaults to one.
2188
+ @end table
2189
+
2190
+ @table @code
2191
+ @kindex frame @r{[}@ovar{n} @r{[}thread @var{thread-num}@r{]}@r{]}
2192
+ @cindex current stack frame
2193
+ @item frame @ovar{n} @r{[}thread @var{thread-num}@r{]}
2194
+ The @code{frame} command allows you to move from one stack frame to
2195
+ another, and to print the stack frame you select. @var{n} is the the
2196
+ stack frame number or 0 if no frame number is given; @code{frame 0}
2197
+ then will always show the current and most recent stack frame.
2198
+
2199
+ If a negative number is given, counting is from the other end of the
2200
+ stack frame, so @code{frame -1} shows the least-recent, outermost or
2201
+ most ``main'' stack frame.
2202
+
2203
+ Without an argument, @code{frame} prints the current stack
2204
+ frame. Since the current position is redisplayed, it may trigger a
2205
+ resynchronization if there is a front end also watching over
2206
+ things.
2207
+
2208
+ If a thread number is given then we set the context for evaluating
2209
+ expressions to that frame of that thread.
2210
+ @end table
2211
+
2212
+ @node Stopping
2213
+ @section Stopping and Resuming Execution
2214
+
2215
+ One important use of a debugger is to stop your program @emph{before} it
2216
+ terminates, so that if your script runs into trouble you can investigate and
2217
+ find out why. However should your script accidentally continue to termination,
2218
+ it can be arranged for @value{DBG} to not to leave byebug without your explicit
2219
+ instruction. That way, you can restart the program using the same command
2220
+ arguments.
2221
+
2222
+ Inside @value{DBG}, your script may stop for any of several reasons, such as a
2223
+ signal, a breakpoint, or reaching a new line after a byebug command such as
2224
+ @code{step}. You may then examine and change variables, set new breakpoints or
2225
+ remove old ones, and then continue execution.
2226
+
2227
+ @menu
2228
+ * Breakpoints:: Breakpoints (break, catch, delete)
2229
+ * Disabling:: Disabling breakpoints (disable, enable)
2230
+ * Conditions:: Break conditions (condition)
2231
+ * Resuming Execution:: Resuming execution (continue, step, next, finish)
2232
+ @end menu
2233
+
2234
+ @node Breakpoints
2235
+ @subsection Breakpoints (@samp{break}, @samp{catch}, @samp{delete})
2236
+
2237
+ @cindex breakpoints
2238
+ A @dfn{breakpoint} makes your script stop whenever a certain point in
2239
+ the program is reached. For each breakpoint, you can add conditions to
2240
+ control in finer detail whether your script stops.
2241
+
2242
+ You specify the place where your script should stop with the
2243
+ @code{break} command and its variants.
2244
+
2245
+ @cindex breakpoint numbers
2246
+ @cindex numbers for breakpoints
2247
+ @value{ttDBG} assigns a number to each breakpoint when
2248
+ you create it; these numbers are successive integers starting with
2249
+ one. In many of the commands for controlling various features of
2250
+ breakpoints you use the breakpoint number to say which breakpoint you
2251
+ want to change. Each breakpoint may be @dfn{enabled} or
2252
+ @dfn{disabled}; if disabled, it has no effect on your script until you
2253
+ enable it again.
2254
+
2255
+
2256
+ @table @code
2257
+ @kindex break @ovar{location}
2258
+ @kindex b @r{(@code{break})}
2259
+ @item break
2260
+ Set a breakpoint at the current line.
2261
+
2262
+ @item break @var{linenum}
2263
+ Set a breakpoint at line @var{linenum} in the current source file.
2264
+ The current source file is the last file whose source text was printed.
2265
+ The breakpoint will stop your script just before it executes any of the
2266
+ code on that line.
2267
+
2268
+ @item break @var{filename}:@var{linenum}
2269
+ Set a breakpoint at line @var{linenum} in source file @var{filename}.
2270
+
2271
+ What may be a little tricky when specifying the filename is getting
2272
+ the name recognized by byebug. If you get a message the message
2273
+ ``@code{No source file named ...}'', then you may need to qualify the
2274
+ name more fully. To see what files are loaded you can use the @code{info
2275
+ files} or @code{info file} commands. If you want the name @code{byebug} thinks
2276
+ of as the current file, use @code{info line}.
2277
+
2278
+ Here's an example:
2279
+ @example
2280
+ $ @b{byebug ~/ruby/gcd.rb 3 5}
2281
+ /home/rocky/ruby/gcd.rb:4 # Note this is the file name
2282
+ def gcd(a, b)
2283
+ (rdb:1) @b{break gcd.rb:6}
2284
+ *** No source file named gcd.rb
2285
+ (rdb:1) @b{info line}
2286
+ Line 4 of "/home/rocky/ruby/gcd.rb"
2287
+ (rdb:1) @b{break /home/rocky/ruby/gcd.rb:6}
2288
+ Breakpoint 1 file /home/rocky/ruby/gcd.rb, line 6
2289
+ (rdb:1) @b{break ~/ruby/gcd.rb:10} # tilde expansion also works
2290
+ Breakpoint 2 file /home/rocky/ruby/gcd.rb, line 10
2291
+ (rdb:1) @b{info file gcd.rb}
2292
+ File gcd.rb is not cached
2293
+ (rdb:1) @b{info file /home/rocky/ruby/gcd.rb}
2294
+ File /home/rocky/ruby/gcd.rb
2295
+ 19 lines
2296
+ @end example
2297
+
2298
+ @item break @var{class}:@var{method}
2299
+ Set a breakpoint in class @var{class} method @var{method}. You can
2300
+ also use a period @code{.} instead of a colon @code{:}. Note that two
2301
+ colons @code{::} are not used. Also note a class @emph{must} be
2302
+ specified here. If the method you want to stop in is in the main class
2303
+ (i.e. the class that @code{self} belongs to at the start of the
2304
+ program), then use the name @code{Object}.
2305
+
2306
+ @kindex catch @ovar{exception} @r{[} on | 1 | off | 0 @r{]}
2307
+ @kindex cat @r{(@code{catch})}
2308
+ @item catch @ovar{exception} @r{[} on | 1 | off | 0 @r{]}
2309
+ Set catchpoint to an exception. Without an exception name show catchpoints.
2310
+
2311
+ With an ``on'' or ``off'' parameter, turn handling the exception on or
2312
+ off. To delete all exceptions type ``catch off''.
2313
+
2314
+ @cindex delete breakpoints
2315
+ @kindex delete @ovar{breakpoints}
2316
+ @kindex del @r{(@code{delete})}
2317
+ @item delete @ovar{breakpoints}
2318
+ Delete the breakpoints specified as arguments.
2319
+
2320
+ If no argument is specified, delete all breakpoints (@DBG asks
2321
+ confirmation. You can abbreviate this command as @code{del}.
2322
+ @kindex info breakpoints
2323
+ @cindex @code{$_} and @code{info breakpoints}
2324
+ @item info breakpoints @ovar{n}
2325
+ @itemx info break @ovar{n}
2326
+ Print a table of all breakpoints set and not deleted, with the
2327
+ following columns for each breakpoint:
2328
+
2329
+ @table @emph
2330
+ @item Breakpoint Numbers (@samp{Num})
2331
+ @item Enabled or Disabled (@samp{Enb})
2332
+ Enabled breakpoints are marked with @samp{1}. @samp{0} marks breakpoints
2333
+ that are disabled (not enabled).
2334
+ @item File and Line (@samp{file:line})
2335
+ The filename and line number inside that file where of breakpoint in
2336
+ the script. The file and line are separated with a colon.
2337
+ @item Condition
2338
+ A condition (an arithmetic expression) which when true causes the
2339
+ breakpoint to take effect.
2340
+ @end table
2341
+ @noindent
2342
+ If a breakpoint is conditional, @code{info break} shows the condition on
2343
+ the line following the affected breakpoint; breakpoint commands, if any,
2344
+ are listed after that.
2345
+
2346
+ @code{info break} with a breakpoint number @var{n} as argument lists
2347
+ only that breakpoint.
2348
+
2349
+ Examples:
2350
+ @example
2351
+ (rdb:1) @b{info break}
2352
+ Breakpoints at following places:
2353
+ Num Enb What
2354
+ 1 y gcd.rb:3
2355
+ 2 y gcb.rb:28 if n > 1
2356
+ (rdb:1) @b{info break 2}
2357
+ 2 y gcb.rb:28 if n > 1
2358
+ @end example
2359
+ @end table
2360
+
2361
+ @node Disabling
2362
+ @subsection Disabling breakpoints (@samp{disable}, @samp{enable})
2363
+
2364
+ Rather than deleting a breakpoint, you might
2365
+ prefer to @dfn{disable} it. This makes the breakpoint inoperative as if
2366
+ it had been deleted, but remembers the information on the breakpoint so
2367
+ that you can @dfn{enable} it again later.
2368
+
2369
+ You disable and enable breakpoints and catchpoints with the
2370
+ @code{enable} and @code{disable} commands, optionally specifying one
2371
+ or more breakpoint numbers as arguments. Use @code{info break} to
2372
+ print a list of breakpoints and catchpoints if you do not know which
2373
+ numbers to use.
2374
+
2375
+ A breakpoint or catchpoint can have any different
2376
+ states of enablement:
2377
+
2378
+ @itemize @bullet
2379
+ @item
2380
+ Enabled. The breakpoint stops your program. A breakpoint set
2381
+ with the @code{break} command starts out in this state.
2382
+ @item
2383
+ Disabled. The breakpoint has no effect on your program.
2384
+ @end itemize
2385
+
2386
+ You can use the following commands to enable or disable breakpoints
2387
+ and catchpoints:
2388
+
2389
+ @table @code
2390
+ @kindex disable breakpoints
2391
+ @item disable @var{breakpoints}
2392
+ Disable the specified breakpoints---or all breakpoints, if none are
2393
+ listed. A disabled breakpoint has no effect but is not forgotten. All
2394
+ options such as ignore-counts, conditions and commands are remembered in
2395
+ case the breakpoint is enabled again later. You may abbreviate
2396
+ @code{disable} as @code{dis}.
2397
+
2398
+ @kindex enable breakpoints
2399
+ @item enable @var{breakpoints}
2400
+ Enable the specified breakpoints (or all defined breakpoints). They
2401
+ become effective once again in stopping your program.
2402
+
2403
+ @end table
2404
+
2405
+ Breakpoints that you set are initially enabled; subsequently, they become
2406
+ disabled or enabled only when you use one of the commands above. (The command
2407
+ @code{until} can set and delete a breakpoint of its own, but it does not change
2408
+ the state of your other breakpoints; see @ref{Resuming Execution}.)
2409
+
2410
+ @node Conditions
2411
+ @subsection Break conditions (@samp{condition})
2412
+ @cindex conditional breakpoints
2413
+ @cindex breakpoint conditions
2414
+
2415
+ The simplest sort of breakpoint breaks every time your script reaches
2416
+ a specified place. You can also specify a @dfn{condition} for a
2417
+ breakpoint. A condition is just a Ruby expression.
2418
+
2419
+ Break conditions can be specified when a breakpoint is set, by using
2420
+ @samp{if} in the arguments to the @code{break} command. A breakpoint
2421
+ with a condition evaluates the expression each time your script
2422
+ reaches it, and your script stops only if the condition is
2423
+ @emph{true}. They can also be changed at any time
2424
+ with the @code{condition} command.
2425
+
2426
+ @ifset FINISHED
2427
+ You can also use the @code{if} keyword with the @code{watch} command.
2428
+ The @code{catch} command does not recognize the @code{if} keyword;
2429
+ @code{condition} is the only way to impose a further condition on a
2430
+ catchpoint.
2431
+ @end ifset
2432
+
2433
+ @table @code
2434
+ @kindex condition
2435
+ @item condition @var{bnum} @var{expression}
2436
+ Specify @var{expression} as the break condition for breakpoint
2437
+ @var{bnum}. After you set a condition, breakpoint @var{bnum} stops
2438
+ your program only if the value of @var{expression} is true (nonzero).
2439
+
2440
+ @item condition @var{bnum}
2441
+ Remove the condition from breakpoint number @var{bnum}. It becomes
2442
+ an ordinary unconditional breakpoint.
2443
+ @end table
2444
+
2445
+ @ifset FINISHED
2446
+ When you use @code{condition}, @DBG checks @var{expression}
2447
+ immediately for syntactic correctness, and to determine whether
2448
+ symbols in it have referents in the context of your breakpoint. If
2449
+ @var{expression} uses symbols not referenced in the context of the
2450
+ breakpoint, @DBG prints an error message:
2451
+
2452
+ @example
2453
+ No symbol "foo" in current context.
2454
+ @end example
2455
+ @end ifset
2456
+
2457
+ @noindent
2458
+ The byebug does not actually evaluate @var{expression} at the time
2459
+ the @code{condition} command (or a command that sets a breakpoint with
2460
+ a condition, like @code{break if @dots{}}) is given, however.
2461
+
2462
+ Examples;
2463
+ @example
2464
+ condition 1 x>5 # Stop on breakpoint 0 only if x>5 is true.
2465
+ condition 1 # Change that! Unconditionally stop on breakpoint 1.
2466
+ @end example
2467
+
2468
+ @node Resuming Execution
2469
+ @subsection Resuming Execution (@samp{step}, @samp{next}, @samp{finish}, @samp{continue}, @samp{jump})
2470
+
2471
+ A typical technique for using stepping is to set a breakpoint (
2472
+ @pxref{Breakpoints}) at the beginning of the function or the section of your
2473
+ script where a problem is believed to lie, run your script until it stops at
2474
+ that breakpoint, and then step through the suspect area, examining the variables
2475
+ that are interesting, until you see the problem happen.
2476
+
2477
+ @cindex stepping
2478
+ @cindex continuing
2479
+ @cindex resuming execution
2480
+ @dfn{Continuing} means resuming program execution until your script completes
2481
+ normally. In contrast, @dfn{stepping} means executing just one more ``step'' of
2482
+ your script, where ``step'' may mean one line of source code. Either when
2483
+ continuing or when stepping, your script may stop even sooner, due to a
2484
+ breakpoint or a signal.
2485
+
2486
+ @menu
2487
+ * Step:: running the next statement (step)
2488
+ * Next:: running the next statement skipping over functions (next)
2489
+ * Finish:: running until the return of a function or ``source'' (finish)
2490
+ * Continue:: continuing execution (continue)
2491
+ * Jump:: jumping to a new line (jump)
2492
+ @end menu
2493
+
2494
+ @node Step
2495
+ @subsubsection Step (@samp{step})
2496
+
2497
+ @table @code
2498
+ @kindex step @r{[}+@r{]} @ovar{count}
2499
+ @kindex s @r{(@code{step})}
2500
+ @item step @r{[}+-@r{]} @ovar{count}
2501
+ Continue running your program until the next logical stopping point and return
2502
+ control to @value{DBG}. This command is abbreviated @code{s}.
2503
+
2504
+ Just like int the programming language Lisp, Ruby tends to be implemented in a
2505
+ highly expression-oriented manner. Therefore things that in other languages may
2506
+ appear to be a single statement are implemented in Ruby as several expressions.
2507
+ For example, in an ``if'' statement or loop statement a stop is made after the
2508
+ expression is evaluated but before the test on the expression is made.
2509
+
2510
+ So it is common that some lines in the program will have several stopping points
2511
+ whereas in other debuggers of other languages there would be only one. Or you
2512
+ may have several statements listed on a single line.
2513
+
2514
+ When stepping it is not uncommon to want to go to a different line on each step.
2515
+ If you want to make sure that on a step you go to a @emph{different} position,
2516
+ add a plus sign (@samp{+}).
2517
+
2518
+ @emph{Note: step+ with a number count is not the same as issuing count step+
2519
+ commands. Instead it uses count-1 step commands followed by a step+ command. For
2520
+ example, @code{step+ 3} is the same as @code{step; step; step+}, not
2521
+ @code{step+; step+; step+}}
2522
+
2523
+ If you find yourself generally wanting to use @code{step+} rather than
2524
+ @code{step}, you may want to consider using @code{set forcestep},
2525
+ (@pxref{Forcestep}).
2526
+
2527
+ If you have @code{forcestep} set on but want to temporarily disable it for the
2528
+ next step command, append a minus, or @code{step-}.
2529
+
2530
+ With a count, @code{step} will continue running as normal, but do so @var{count}
2531
+ times. If a breakpoint is reached, or a signal not related to stepping occurs
2532
+ before @var{count} steps, stepping stops right away.
2533
+ @end table
2534
+
2535
+ @node Next
2536
+ @subsubsection Next (@samp{next})
2537
+ @table @code
2538
+ @kindex next @r{[}+-@r{]} @ovar{count}
2539
+ @kindex n @r{(@code{next})}
2540
+ @item next @r{[}+@r{]} @ovar{count}
2541
+ This is similar to @code{step}, but function or method calls that appear within
2542
+ the line of code are executed without stopping. As with step, if you want to
2543
+ make sure that on a step you go to a @emph{different} position, add a plus sign
2544
+ (@samp{+}). Similarly, appending a minus disables a @code{forcestep}
2545
+ temporarily, and an argument @var{count} is a repeat count, as for @code{step}.
2546
+ @end table
2547
+
2548
+ @node Finish
2549
+ @subsubsection Finish (@samp{finish})
2550
+ @table @code
2551
+ @kindex finish @ovar{frame-number}
2552
+ @item finish @ovar{frame-number}
2553
+ Execute until selected stack frame returns. If no frame number is given, we run
2554
+ until the currently selected frame returns. The currently selected frame starts
2555
+ out the most-recent frame or 0 if no frame positioning (e.g@: @code{up},
2556
+ @code{down} or @code{frame}) has been performed. If a frame number is given we
2557
+ run until @var{frame} frames returns.
2558
+
2559
+ If you want instead to terminate the program and byebug entirely, use
2560
+ @code{quit} (@pxref{Quitting byebug, ,Quitting byebug}).
2561
+
2562
+ @end table
2563
+
2564
+ @node Continue
2565
+ @subsubsection Continue (@samp{continue})
2566
+ @table @code
2567
+ @kindex continue @ovar{line-specification}
2568
+ @kindex c @r{(@code{continue})}
2569
+ @item continue @ovar{line-specification}
2570
+ @itemx c @ovar{line-specification}
2571
+ Resume program execution, at the address where your script last
2572
+ stopped; any breakpoints set at that address are bypassed.
2573
+
2574
+ The optional argument @var{line-specification} allows you to specify a
2575
+ line number to set a one-time breakpoint which is deleted when that
2576
+ breakpoint is reached.
2577
+
2578
+ Should the program stop before that breakpoint is reached, for
2579
+ example, perhaps another breakpoint is reached first, in
2580
+ a listing of the breakpoints you won't see this entry in the list of
2581
+ breakpoints.
2582
+ @end table
2583
+
2584
+ @node Jump
2585
+ @subsubsection Jump (@samp{jump})
2586
+ @table @code
2587
+ @kindex jump @r{[}+-@r{]} @ovar{line}
2588
+ @item jump @r{[}+-@r{]} @ovar{line}
2589
+ Change the next line to execute to the given line number.
2590
+ @end table
2591
+
2592
+ @node byebug settings
2593
+ @section byebug settings (@samp{set args}, @samp{set autoeval}..)
2594
+
2595
+ You can alter the way byebug interacts with you using @code{set}
2596
+ commands.
2597
+
2598
+ The various parameters to @code{set} are given below. Each parameter
2599
+ name needs to to be only enough to make it unique. For example
2600
+ @code{set force} is a suitable abbreviation for @code{set forcestep}.
2601
+ The letter case is not important, so @code{set FORCE} or @code{set
2602
+ Force} are also suitable abbreviations.
2603
+
2604
+ Many @code{set} commands are either ``on'' or ``off'', and you can
2605
+ indicate which way you want set by supplying the corresponding
2606
+ word. The number 1 can be used for ``on'' and 0 for ``off''. If none
2607
+ of these is given, we will assume ``on''. A deprecated way of turning
2608
+ something off is by prefacing it with ``no''.
2609
+
2610
+ Each @code{set} command has a corresponding @code{show} command which
2611
+ allows you to see the current value.
2612
+
2613
+ @menu
2614
+ * Args:: Annotation Level
2615
+ * Autoeval:: Evaluate unrecognized commands
2616
+ * Autolist:: Execute ``list'' command on every breakpoint
2617
+ * Autoirb:: Invoke IRB on every stop
2618
+ * Autoreload:: Reload source code when changed
2619
+ * Basename:: Report file basename only showing file names
2620
+ * Callstyle:: Show Report file basename only showing file names
2621
+ * Forcestep:: Make sure 'next/step' commands always move to a new line
2622
+ * Fullpath:: Display full file names in frames
2623
+ * History:: Generic command for showing command history parameters.
2624
+ * Keepframebindings:: Save frame binding on each call
2625
+ * Linetrace:: line execution tracing
2626
+ * Linetrace+:: line tracing style
2627
+ * Listsize:: Number of lines to try to show in a 'list' command
2628
+ * Post-mortem:: Whether post-mortem handling is in effect.
2629
+ * Trace:: Display stack trace when 'eval' raises exception
2630
+ * Width:: Number of characters byebug thinks are in a line
2631
+ @end menu
2632
+
2633
+ @node Args
2634
+ @subsection Set/Show args
2635
+
2636
+ @table @code
2637
+ @kindex set args @ovar{parameters}
2638
+ @item set args @ovar{parameters}
2639
+ Specify the arguments to be used if your program is rerun. If
2640
+ @code{set args} has no arguments, @code{restart} executes your program
2641
+ with no arguments. Once you have run your program with arguments,
2642
+ using @code{set args} before the next @code{restart} is the only way to run
2643
+ it again without arguments.
2644
+
2645
+ @kindex show args
2646
+ @item show args
2647
+ Show the arguments to give your program when it is started.
2648
+ @end table
2649
+
2650
+ @node Autoeval
2651
+ @subsection Set/Show auto-eval
2652
+
2653
+ @table @code
2654
+ @kindex set autoeval @r{[} on | 1 | off | 0 @r{]}
2655
+ @item set autoeval @r{[} on | 1 | off | 0 @r{]}
2656
+ Specify that byebug input that isn't recognized as a command should
2657
+ be passed to Ruby for evaluation (using the current debugged program
2658
+ namespace). Note however that we @emph{first} check input to see if it
2659
+ is a byebug command and @emph{only} if it is not do we consider it
2660
+ as Ruby code. This means for example that if you have variable called
2661
+ @code{n} and you want to see its value, you could use @code{p n},
2662
+ because just entering @code{n} will be interpreted as byebug
2663
+ ``next'' command.
2664
+
2665
+ See also @ref{irb} and @ref{Autoirb}.
2666
+
2667
+ When autoeval is set on, you'll get a different error message when you
2668
+ invalid commands are encountered. Here's a session fragment to show
2669
+ the difference
2670
+ @smallexample
2671
+ (rdb:1) @b{stepp}
2672
+ Unknown command
2673
+ (rdb:1) @b{set autoeval on}
2674
+ autoeval is on.
2675
+ (rdb:1) @b{stepp}
2676
+ NameError Exception: undefined local variable or method `stepp' for ...
2677
+ @end smallexample
2678
+
2679
+ @kindex show autoeval
2680
+ @item show args
2681
+ Shows whether Ruby evaluation of byebug input should occur or not.
2682
+ @end table
2683
+
2684
+ @node Autolist
2685
+ @subsection Execute ``list'' command on every breakpoint
2686
+
2687
+ @node Autoirb
2688
+ @subsection Set/Show auto-irb
2689
+
2690
+ @table @code
2691
+ @kindex set autoirb @r{[} on | 1 | off | 0 @r{]}
2692
+ @item set autoirb @r{[} on | 1 | off | 0 @r{]}
2693
+
2694
+ When your program stops, normally you go into a byebug command loop
2695
+ looking for byebug commands. If instead you would like to directly
2696
+ go into an irb shell, set this on. See also @ref{Autoeval} or
2697
+ @ref{irb} if you tend to use byebug commands but still want Ruby
2698
+ evaluation occasionally.
2699
+
2700
+ @kindex show autoirb
2701
+ @item show autoirb
2702
+ Shows whether byebug will go into irb on stop or not.
2703
+ @end table
2704
+
2705
+ @node Autoreload
2706
+ @subsection Set/Show auto-reload
2707
+ @table @code
2708
+ @kindex set autoreload @r{[} on | 1 | off | 0 @r{]}
2709
+ Set this on if byebug should check to see if the source has
2710
+ changed since the last time it reread in the file if it has.
2711
+ @end table
2712
+
2713
+ @node Basename
2714
+ @subsection Set/Show basename
2715
+
2716
+ @table @code
2717
+ @kindex set basename @r{[} on | 1 | off | 0 @r{]}
2718
+ @item set basename @r{[} on | 1 | off | 0 @r{]}
2719
+ Source filenames are shown as the shorter ``basename''
2720
+ only. (Directory paths are omitted). This is useful in running the
2721
+ regression tests and may useful in showing byebug examples as in
2722
+ this text. You may also just want less verbose filename display.
2723
+
2724
+ By default filenames are shown as with their full path.
2725
+
2726
+ @kindex show basename
2727
+ @item show basename
2728
+ Shows the whether filename display shows just the file basename or not.
2729
+ @end table
2730
+
2731
+ @node Callstyle
2732
+ @subsection Set/Show call style
2733
+
2734
+ @table @code
2735
+ @ifset FINISHED
2736
+ @kindex set callstyle @r{[} short | last | tracked @r{]}
2737
+ @item set forcestep @r{[} short | last | tracked @r{]}
2738
+ @else
2739
+ @kindex set callstyle @r{[} short | last
2740
+ @item set forcestep @r{[} short | last
2741
+ @end ifset
2742
+
2743
+ Sets how you want call parameters displayed; @code{short} shows just
2744
+ the parameter names;
2745
+ @ifset FINISHED
2746
+ @code{last} shows the parameter names and the
2747
+ class of these variables as they currently exist. Note the type could
2748
+ have changed between when the call and its current
2749
+ values.
2750
+ @end ifset
2751
+ @code{tracked} is the most accurate but this adds
2752
+ overhead. On every call, scalar values of the parameters get
2753
+ saved. For non-scalar values the class is saved.
2754
+ @end table
2755
+
2756
+ @node Forcestep
2757
+ @subsection Set/Show Forces Different Line Step/Next
2758
+
2759
+ @table @code
2760
+ @kindex set forcestep @r{[} on | 1 | off | 0 @r{]}
2761
+ @item set forcestep @r{[} on | 1 | off | 0 @r{]}
2762
+
2763
+ Due to the interpretive, expression-oriented nature of the Ruby
2764
+ Language and implementation, each line often contains many possible
2765
+ stopping points, while in a byebug it is often desired to treat each
2766
+ line as an individual stepping unit.
2767
+
2768
+ Setting forcestep on will cause each @code{step} or @code{next}
2769
+ command to stop at a different line number. See also @ref{Step} and
2770
+ @ref{Next}.
2771
+
2772
+ @kindex show forcestep
2773
+ @item show forcestep
2774
+ Shows whether forcestep is in effect or not.
2775
+ @end table
2776
+
2777
+ @node Fullpath
2778
+ @subsection Set/Show Frame full path
2779
+
2780
+ @node History
2781
+ @subsection Command History Parameters
2782
+ @table @code
2783
+ @item show commands
2784
+ @kindex show commands
2785
+ Display the last ten commands in the command history.
2786
+
2787
+ @item show commands @var{n}
2788
+ @kindex show commands @var{n}
2789
+ Print ten commands centered on command number @var{n}.
2790
+
2791
+ @item show history filename
2792
+ @kindex show history filename
2793
+ Show the filename in which to record the command history
2794
+ (the list of previous commands of which a record is kept).
2795
+
2796
+ @item set history save @r{[} on | 1 | off | 0 @r{]}
2797
+ @kindex set history save @r{[} on | 1 | off | 0 @r{]}
2798
+ Set whether to save the history on exit.
2799
+
2800
+ @item show history save
2801
+ @kindex show history save
2802
+ Show saving of the history record on exit.
2803
+
2804
+ @item set history size @var{number}
2805
+ @kindex set history size @var{number}
2806
+ Set the maximum number of commands to save in the history.
2807
+
2808
+ @item show history size
2809
+ @kindex show history size
2810
+ Show the size of the command history, i.e. the number of previous
2811
+ commands to keep a record of.
2812
+ @end table
2813
+
2814
+ @node Keepframebindings
2815
+ @subsection Save frame binding on each call
2816
+
2817
+ @node Linetrace
2818
+ @subsection Set/Show Line tracing
2819
+
2820
+ @table @code
2821
+ @kindex set linetrace @r{[} on | 1 | off | 0 @r{]}
2822
+ @item set linetrace @r{[} on | 1 | off | 0 @r{]}
2823
+
2824
+ Setting linetrace on will cause lines to be shown before run.
2825
+
2826
+ @kindex show linetrace
2827
+ @item show linetrace
2828
+ Shows whether line tracing is in effect or not.
2829
+ @end table
2830
+
2831
+ @node Linetrace+
2832
+ @subsection Set/Show Line tracing style
2833
+
2834
+ @table @code
2835
+ @kindex set linetrace+ @r{[} on | 1 | off | 0 @r{]}
2836
+ @item set linetrace+ @r{[} on | 1 | off | 0 @r{]}
2837
+
2838
+ Setting linetrace+ on will cause consecutive trace lines not to be a
2839
+ duplicate of the preceding line-trace line. Note however that this
2840
+ setting doesn't by itself turn on or off line tracing.
2841
+
2842
+ @kindex show linetrace+
2843
+ @item show linetrace
2844
+ Shows whether the line tracing style is to show all lines or remove
2845
+ duplicates linetrace lines when it is a repeat of the previous line.
2846
+ @end table
2847
+
2848
+ @node Listsize
2849
+ @subsection Set/Show lines in a List command
2850
+
2851
+ @table @code
2852
+ @kindex set listsize @var{number-of-lines}
2853
+ @item set listsize @var{number-of-lines}
2854
+ Set number of lines to try to show in a @code{list} command.
2855
+ @kindex show listsize
2856
+ @item show listsize
2857
+ Shows the list-size setting.
2858
+ @end table
2859
+
2860
+ @node Post-mortem
2861
+ @subsection Show Post-mortem handling
2862
+ @table @code
2863
+ @kindex show post-mortem
2864
+ Shows wither post-mortem debugging is in effect. Right now we don't
2865
+ have the ability to change the state inside byebug.
2866
+ @end table
2867
+
2868
+ @node Trace
2869
+ @subsection Display stack trace when 'eval' raises exception
2870
+
2871
+ @node Width
2872
+ @subsection Set/Show Line width
2873
+
2874
+ @table @code
2875
+ @kindex set width @var{column-width}
2876
+ @item set width @var{column-width}
2877
+ Set number of characters byebug thinks are in a line.
2878
+ We also change OS environment variable @code{COLUMNS}.
2879
+ @kindex show width
2880
+ @item show width
2881
+ Shows the current width setting.
2882
+ @end table
2883
+
2884
+ @node Program Information
2885
+ @section Program Information (@samp{info})
2886
+
2887
+ This @code{info} command (abbreviated @code{i}) is for describing the
2888
+ state of your program. For example, you can list the current
2889
+ parameters with @code{info args}, or list the breakpoints you have set
2890
+ with @code{info breakpoints} or @code{info watchpoints}. You can get
2891
+ a complete list of the @code{info} sub-commands with @w{@code{help
2892
+ info}}.
2893
+
2894
+ @table @code
2895
+ @kindex info args
2896
+
2897
+ @item info args
2898
+ Method arguments of the current stack frame.
2899
+ @kindex info breakpoints
2900
+
2901
+ @item info breakpoints
2902
+ Status of user-settable breakpoints
2903
+ @kindex info display
2904
+
2905
+ @item info display
2906
+ All display expressions.
2907
+ @kindex info files
2908
+
2909
+ @item info files
2910
+ Source files in the program.
2911
+ @kindex info file
2912
+
2913
+ @item info file @var{filename} @ovar{all|lines|mtime|sha1}
2914
+ Information about a specific file. Parameter @code{lines} gives the
2915
+ number of lines in the file, @code{mtime} shows the modification time
2916
+ of the file (if available), @code{sha1} computes a SHA1 has of the
2917
+ data of the file. @code{all} gives all of the above information.
2918
+
2919
+ @kindex info line
2920
+ @item info line
2921
+ Line number and file name of current position in source.
2922
+ @kindex info locals
2923
+ @item info locals
2924
+ Local variables of the current stack frame.
2925
+ @kindex info program
2926
+ @item info program
2927
+ Display information about the status of your program: whether it is
2928
+ running or not and why it stopped. If an unhandled exception occurred,
2929
+ the exception class and @code{to_s} method is called.
2930
+ @kindex info stack
2931
+ @item info stack
2932
+ Backtrace of the stack. An alias for @code{where}. @xref{Backtrace}.
2933
+ @kindex info thread
2934
+ @item info thread @ovar{thread-number} @r{[} terse | verbose@r{]}
2935
+ If no thread number is given, we list info for all
2936
+ threads. @code{terse} and @code{verbose} options are possible. If terse,
2937
+ just give summary thread name information. See information under @code{info threads} for
2938
+ more detail about this summary information.
2939
+
2940
+ If @code{verbose} is appended to the end of the command, then the entire
2941
+ stack trace is given for each thread.
2942
+
2943
+ @kindex info threads @r{[} terse | verbose@r{]}
2944
+ @item info threads
2945
+
2946
+ List information about currently-known threads. This information
2947
+ includes whether the thread is current (+), if it is suspended ($), or
2948
+ ignored (!); the thread number and the top stack item. If
2949
+ @code{verbose} is given then the entire stack frame is shown. Here is
2950
+ an example:
2951
+
2952
+ @smallexample
2953
+ (rdb:7) info threads
2954
+ 1 #<Thread:0xb7d08704 sleep> ./test/thread1.rb:27
2955
+ !2 #<Byebug::DebugThread:0xb7782e4c sleep>
2956
+ 3 #<Thread:0xb777e220 sleep> ./test/thread1.rb:11
2957
+ 4 #<Thread:0xb777e144 sleep> ./test/thread1.rb:11
2958
+ 5 #<Thread:0xb777e07c sleep> ./test/thread1.rb:11
2959
+ 6 #<Thread:0xb777dfb4 sleep> ./test/thread1.rb:11
2960
+ + 7 #<Thread:0xb777deec run> ./test/thread1.rb:14
2961
+ (rdb:1)
2962
+ @end smallexample
2963
+
2964
+ Thread 7 is the current thread since it has a plus sign in front. Thread 2 is
2965
+ ignored since it has a @code{!}. A ``verbose'' listing of the above:
2966
+
2967
+ @smallexample
2968
+ (rdb:7) info threads verbose
2969
+ 1 #<Thread:0xb7d08704 sleep>
2970
+ #0 Integer.join at line test/thread1.rb:27
2971
+ #1 at line test/thread1.rb:27
2972
+ !2 #<Byebug::DebugThread:0xb7782e4c sleep>
2973
+ 3 #<Thread:0xb777e220 sleep>
2974
+ #0 sleep(count#Fixnum) at line test/thread1.rb:11
2975
+ #1 Object.fn(count#Fixnum, i#Fixnum) at line test/thread1.rb:11
2976
+ #2 at line test/thread1.rb:23
2977
+ 4 #<Thread:0xb777e144 sleep>
2978
+ #0 sleep(count#Fixnum) at line test/thread1.rb:11
2979
+ #1 Object.fn(count#Fixnum, i#Fixnum) at line test/thread1.rb:11
2980
+ #2 at line test/thread1.rb:23
2981
+ 5 #<Thread:0xb777e07c sleep>
2982
+ #0 sleep(count#Fixnum) at line test/thread1.rb:11
2983
+ #1 Object.fn(count#Fixnum, i#Fixnum) at line test/thread1.rb:11
2984
+ #2 at line test/thread1.rb:23
2985
+ 6 #<Thread:0xb777dfb4 sleep>
2986
+ #0 sleep(count#Fixnum) at line test/thread1.rb:11
2987
+ #1 Object.fn(count#Fixnum, i#Fixnum) at line test/thread1.rb:11
2988
+ #2 at line test/thread1.rb:23
2989
+ + 7 #<Thread:0xb777deec run>
2990
+ #0 Object.fn(count#Fixnum, i#Fixnum) at line test/thread1.rb:14
2991
+ #1 at line test/thread1.rb:23
2992
+ @end smallexample
2993
+
2994
+ @kindex info variables
2995
+ @item info variables
2996
+ Local and instance variables.
2997
+ @end table
2998
+
2999
+ @node Post-Mortem Debugging
3000
+ @chapter Post-Mortem Debugging
3001
+ @cindex post-mortem debugging
3002
+
3003
+ It is also to possible enter byebug when you have an uncaught
3004
+ exception that is about to terminate our program. This is called
3005
+ @emph{post-mortem debugging}. In this state many, of byebug commands
3006
+ for examining variables and moving around in the stack still
3007
+ work. However some commands, such as those which imply a continuation
3008
+ of running code, no longer work.
3009
+
3010
+ The most reliable way to set up post-mortem debugging is to use the
3011
+ @option{--post-mortem} option in invoking @code{byebug}. See @ref{byebug
3012
+ command-line options}. This traps/wraps at byebug ``load'' of
3013
+ your Ruby script. When this is done, your program is stopped after
3014
+ the exception takes place, but before the stack has been
3015
+ unraveled. (Alas, it would be nice to if one could allow resetting the
3016
+ exception and continuing, but details of code in Ruby 1.8's
3017
+ @code{eval.c} prevent this.)
3018
+
3019
+ If however you haven't invoked @code{byebug} at the outset, but
3020
+ instead call @code{byebug} from inside your program, to set up
3021
+ post-mortem debugging set the @code{post_mortem} key in
3022
+ @code{Byebug.start}. Here's an example modified from
3023
+ @url{http://www.datanoise.com/articles/2006/12/20/post-mortem-debugging}:
3024
+
3025
+ @smallexample
3026
+ $ @b{cat t.rb }
3027
+ require 'rubygems'
3028
+ require 'byebug' ; Byebug.start(:post_mortem => true)
3029
+
3030
+ def t1
3031
+ raise 'test'
3032
+ end
3033
+ def t2
3034
+ t1
3035
+ end
3036
+ t2
3037
+
3038
+ $ @b{ruby t.rb }
3039
+ t.rb:8: raise 'test'
3040
+ (rdb:post-mortem) @b{l=}
3041
+ [3, 12] in t.rb
3042
+ 3
3043
+ 4 Byebug.start
3044
+ 5 Byebug.post_mortem
3045
+ 6
3046
+ 7 def t1
3047
+ => 8 raise 'test'
3048
+ 9 end
3049
+ 10 def t2
3050
+ 11 t1
3051
+ 12 end
3052
+ (rdb:post-mortem)
3053
+ @end smallexample
3054
+
3055
+ Alternatively you can call @code{Byebug.post_mortem()} after byebug has
3056
+ been started. The @code{post_mortem()} method can be called in two
3057
+ ways. Called without a block, it installs a global @code{at_exit()} hook
3058
+ that intercepts exceptions not handled by your Ruby script. In
3059
+ contrast to using the @option{--post-mortem} option, when this hook
3060
+ occurs after the call stack has been rolled back. (I'm not sure if
3061
+ this in fact makes any difference operationally; I'm just stating it
3062
+ because that's how it works.)
3063
+
3064
+ If you know that a particular block of code raises an exception you
3065
+ can enable post-mortem mode by wrapping this block inside a
3066
+ @code{Byebug.post_mortem} block
3067
+
3068
+ @smallexample
3069
+ def offender
3070
+ 1/0
3071
+ end
3072
+ ...
3073
+ require "ruby-gems"
3074
+ require "byebug"
3075
+ Byebug.post_mortem do
3076
+ ...
3077
+ offender
3078
+ ...
3079
+ end
3080
+ @end smallexample
3081
+
3082
+ Once inside byebug in post-mortem debugging, the prompt should
3083
+ be @code{(rdb:post-mortem)}.
3084
+
3085
+ @node Byebug Module and Class
3086
+ @chapter The Byebug Module and Class
3087
+
3088
+ @menu
3089
+ * Byebug Module:: byebug's Byebug module
3090
+ * Byebug Class:: Byebug class
3091
+ * Kernel routines:: Routines added to Kernel
3092
+ @end menu
3093
+
3094
+ @node Byebug Module
3095
+ @section The Byebug Module
3096
+
3097
+ @menu
3098
+ * Byebug.run::
3099
+ @ifset LATER
3100
+ * Byebug.post-mortem::
3101
+ @end ifset
3102
+ * Byebug.context::
3103
+ * Byebug.settings::
3104
+ @end menu
3105
+
3106
+ @node Byebug.run
3107
+ @subsection @code{Byebug.start}, @code{Byebug.started?}, @code{Byebug.stop}, @code{Byebug.run_script}
3108
+
3109
+ In order to provide better debugging information regarding the stack
3110
+ frame(s) across all threads, byebug has to intercept each call,
3111
+ save some information and on return remove it. Possibly, in Ruby 1.9
3112
+ possibly this will not be needed. Therefore one has to issue call to
3113
+ indicate start saving information and another call to stop. Of course,
3114
+ If you call byebug from the outset via @code{byebug} this is done
3115
+ for you.
3116
+
3117
+ @table @code
3118
+ @item Byebug.start(@ovar{options}) @ovar{block}
3119
+ @vindex @code{Byebug.start(options)}
3120
+ @vindex @code{Byebug.start(block)}
3121
+ Turn on add additional instrumentation code to facilitate debugging. A
3122
+ system even table hook is installed and some variables are set up to
3123
+ access thread frames.
3124
+
3125
+ This needs to be done before entering byebug; therefore a call
3126
+ to byebug issue a @code{Byebug.start} call if necessary.
3127
+
3128
+ If called without a block, @code{Byebug.start} returns @code{true} if
3129
+ byebug was already started. But if you want to know if the
3130
+ byebug has already been started @code{Byebug.started?} can tell
3131
+ you.
3132
+
3133
+ If a block is given, byebug is started and @code{yields} to
3134
+ block. When the block is finished executing, byebug stopped with
3135
+ the @code{Byebug.stop method}. You will probably want to put a call
3136
+ to @code{byebug} somwhere inside that block
3137
+
3138
+ But if you want to completely stop byebug, you must call
3139
+ @code{Byebug.stop} as many times as you called Byebug.start
3140
+ method.
3141
+
3142
+ The first time Byebug.start is called there is also some additional
3143
+ setup to make the @code{restart} command work. In particular, @code{$0} and
3144
+ @code{ARGV} are used to set internal byebug variables.
3145
+
3146
+ Therefore you should make try to make sure that when
3147
+ @code{Byebug.start} is called neither of these variables has been
3148
+ modified. If instead you don't want this behavior you can pass an
3149
+ options has and set the @code{:init} key to @code{false}. That is
3150
+ @smallexample
3151
+ Byebug.start(:init => false) # or Byebug.start(@{:init => false@})
3152
+ @end smallexample
3153
+
3154
+ If you want post-mortem debugging, you can also supply
3155
+ @code{:post_mortem => true} in @code{Byebug.start}.
3156
+
3157
+ @item Byebug.started?
3158
+ @vindex @code{Byebug.started?}
3159
+ Boolean. Return @code{true} if byebug has been started.
3160
+
3161
+ @item Byebug.stop
3162
+ @vindex @code{Byebug.stop}
3163
+ Turn off instrumentation to allow debugging. Return @code{true} is returned
3164
+ if byebug is disabled, otherwise it returns @code{false}.
3165
+ @emph{Note that if you want to stop byebug, you must call Byebug.stop
3166
+ as many times as you called the @code{Byebug.start} method.}
3167
+
3168
+ @item Byebug.run_script(@var{byebug-command-file}, out = handler.interface)
3169
+ @vindex @code{Byebug.run_script}
3170
+ Reads/runs the given file containing byebug commands. @code{.byebugrc} is run this way.
3171
+
3172
+ @item Byebug.last_exception
3173
+ @vindex @code{Byebug.last_exception}
3174
+ If not @code{nil}, this contains @code{$!} from the last exception.
3175
+
3176
+ @end table
3177
+
3178
+ @node Byebug.context
3179
+ @subsection @code{Byebug.context}
3180
+ As mentioned previously, @code{Byebug.start} instruments additional
3181
+ information to be obtained about the current block/frame stack. Here
3182
+ we describe these additional @code{Byebug.context} methods.
3183
+
3184
+ Were a frame position is indicated, it is optional. The top or current frame
3185
+ position (position zero) is used if none is given.
3186
+
3187
+ @table @code
3188
+ @item Byebug.context.frame_args @ovar{frame-position=0}
3189
+ @vindex @code{Byebug.context.frame_args}
3190
+ If track_frame_args? is true, return information saved about call
3191
+ arguments (if any saved) for the given frame position.
3192
+
3193
+ @item Byebug.context.frame_args_info @ovar{frame-position=0}
3194
+ @vindex @code{Byebug.context.frame_args_info}
3195
+
3196
+ @item Byebug.context.frame_class @ovar{frame-position=0}
3197
+ @vindex @code{Byebug.context.frame_args_info}
3198
+ Return the class of the current frame stack.
3199
+
3200
+ @item Byebug.context.frame_file @ovar{frame-position=0}
3201
+ @vindex @code{Byebug.context.frame_file}
3202
+ Return the filename of the location of the indicated frame position.
3203
+
3204
+ @item Byebug.context.frame_id @ovar{frame-position=0}
3205
+ @vindex @code{Byebug.context.frame_id}
3206
+ Same as @code{Byebug.context.method}.
3207
+
3208
+ @item Byebug.context.frame_line @ovar{frame-position=0}
3209
+ @vindex @code{Byebug.context.frame_line}
3210
+ Return the filename of the location of the indicated frame position.
3211
+
3212
+ @item Byebug.context.frame_method @ovar{frame-position=0}
3213
+ @vindex @code{Byebug.context.frame_method}
3214
+ Symbol of the method name of the indicated frame position.
3215
+
3216
+ @item Byebug.context.stack_size
3217
+ @vindex @code{Byebug.context.stack_size}
3218
+ Return the number the size of the frame stack. Note this may be less
3219
+ that the actual frame stack size if byebug recording
3220
+ (@code{Byebug.start}) was turned on at after some blocks were added
3221
+ and not finished when the @code{Byebug.start} was issued.
3222
+ @end table
3223
+
3224
+ @node Byebug.settings
3225
+ @subsection @code{Byebug.settings}
3226
+ @vindex @code{Byebug.settings}
3227
+ Symbols listed here are keys into the Array @code{Byebug.settings}.
3228
+ These can be set any time after the @code{byebug} is loaded. For example:
3229
+ @smallexample
3230
+ require "byebug/byebug"
3231
+ Byebug.settings[:autoeval] = true # try eval on unknown byebug commands
3232
+ Byebug.listsize = 20 # Show 20 lines in a list command
3233
+ @end smallexample
3234
+
3235
+ @table @code
3236
+ @item :argv
3237
+ Array of String. @code{argv[0]} is the debugged program name and
3238
+ @code{argv[1..-1]} are the command arguments to it.
3239
+ @item :autoeval
3240
+ Boolean. True if auto autoeval on. @xref{Autoeval}.
3241
+ @item :autoirb
3242
+ Fixnum: 1 if on or 0 if off. @xref{Autoirb}.
3243
+ @item :autolist
3244
+ Fixnum: 1 if on or 0 if off.
3245
+ @item :basename
3246
+ Boolean. True if basename on. @xref{Basename}.
3247
+ @item :callstyle
3248
+ Symbol: @code{:short} or @code{:last}. @xref{Callstyle}.
3249
+ @item :byebugtesting
3250
+ Boolean. True if currently testing byebug.
3251
+ @item :force_stepping
3252
+ Boolean. True if stepping should go to a line different from the last
3253
+ step. @xref{Forcestep}.
3254
+ @item :full_path
3255
+ Boolean. @xref{Fullpath}.
3256
+ @item :listsize
3257
+ Fixnum. Number of lines to show in a @code{list} command. @xref{Listsize}.
3258
+ @item :reload_source_on_change
3259
+ Boolean. True if we should reread the source every time it changes. @xref{Autoreload}.
3260
+ @item :stack_trace_on_error
3261
+ Boolean. True if we should produce a stack trace on error. @xref{Trace}.
3262
+ @item :width
3263
+ Fixnum. Number of characters byebug thinks are in a line. @xref{Width}.
3264
+ @end table
3265
+
3266
+ @node Byebug Class
3267
+ @section The @code{Byebug} Class
3268
+ @menu
3269
+ * Byebug.Breakpoint:: Byebug::Breakpoint
3270
+ * Byebug.Context:: Byebug::Context
3271
+ * Byebug.Command:: Byebug::Command
3272
+ @end menu
3273
+
3274
+ @table @code
3275
+ @item add_breakpoint(file, line, expr)
3276
+ @vindex @code{Byebug.add_breakpoint}
3277
+ Adds a breakpoint in file @var{file}, at line @var{line}. If
3278
+ @var{expr} is not nil, it is evaluated and a breakpoint takes effect
3279
+ at the indicated position when that expression is true. You should
3280
+ verify that @var{expr} is syntactically valid or a @code{SyntaxError}
3281
+ exception, and unless your code handles this the debugged program may
3282
+ terminate.
3283
+
3284
+ @item remove_breakpoint(bpnum)
3285
+ @vindex @code{Byebug.remove_breakpoint}
3286
+ When a breakpoint is added, it is assigned a number as a way to
3287
+ uniquely identify it. (There can be more than one breakpoint on a
3288
+ given line.) To remove a breakpoint, use @code{remove_breakpoint} with
3289
+ breakpoint number @var{bpnum}.
3290
+
3291
+ @item breakpoints
3292
+ @vindex @code{Byebug.breakpoints}
3293
+ Return a list of the breakpoints that have been added but not removed.
3294
+ @end table
3295
+
3296
+ @node Byebug.Breakpoint
3297
+ @subsection The @code{Byebug::Breakpoint} Class
3298
+ Breakpoint are objects in the @code{Byebug::Breakpoint} class.
3299
+ @table @code
3300
+ @item enabled?
3301
+ @vindex @code{Byebug::Breakpoints.enabled?}
3302
+ Returns whether breakpoint is enabled or not.
3303
+
3304
+ @item enabled=
3305
+ @vindex @code{Byebug::Breakpoints.enabled=}
3306
+ Sets whether breakpoint is enabled or not.
3307
+
3308
+ @item expr
3309
+ @vindex @code{Byebug::Breakpoints.expr}
3310
+ Expression which has to be true at the point where the breakpoint is
3311
+ set before we stop.
3312
+
3313
+ @item expr=
3314
+ @vindex @code{Byebug::Breakpoints.expr=}
3315
+
3316
+ @item hit_condition
3317
+ @item hit_condition=
3318
+ @vindex @code{Byebug::Breakpoints.condition}
3319
+ @vindex @code{Byebug::Breakpoints.condition=}
3320
+
3321
+ @item hit_count
3322
+ @vindex @code{Byebug::Breakpoints.hit_count}
3323
+ Returns the hit count of the breakpoint.
3324
+
3325
+ @item hit_value
3326
+ @vindex @code{Byebug::Breakpoints.hit_value}
3327
+ Returns the hit value of the breakpoint.
3328
+
3329
+ @item hit_value=
3330
+ @vindex @code{Byebug::Breakpoints.hit_value=}
3331
+ Sets the hit value of the breakpoint.
3332
+
3333
+ @item id
3334
+ @cindex @code{Byebug::Breakpoints.id}
3335
+ A numeric name for the breakpoint which is used in listing breakpoints
3336
+ and removing, enabling or disabling the breakpoint
3337
+
3338
+ @item pos
3339
+ @vindex @code{Byebug::Breakpoints.pos=}
3340
+ Returns the line number of this breakpoint.
3341
+ @item pos=
3342
+ @vindex @code{Byebug::Breakpoints.pos=}
3343
+ Sets the line number of this breakpoint.
3344
+
3345
+ @item source
3346
+ @vindex @code{Byebug::Breakpoints.source}
3347
+ Returns the file name in which the breakpoint occurs.
3348
+
3349
+ @item source=
3350
+ @vindex @code{Byebug::Breakpoints.source=}
3351
+ Sets the file name in which the breakpoint occurs.
3352
+ @end table
3353
+
3354
+ @node Byebug.Context
3355
+ @subsection The @code{Byebug::Context} Class
3356
+ Callbacks in @code{Byebug:Context} get called when a stopping point
3357
+ or an event is reached. It has information about the suspended program
3358
+ which enable a byebug to inspect the frame stack, evaluate variables
3359
+ from the perspective of the debugged program, and contains information
3360
+ about the place the debugged program is stopped.
3361
+
3362
+ @table @code
3363
+ @item at_line(@var{file}, @var{line})
3364
+ @vindex Byebug::Context::at_line(@var{file}, @var{line})
3365
+ This routine is called when byebug encounters a ``line'' event for
3366
+ which it has been indicated we want to stop at, such as by hitting a
3367
+ breakpoint or by some sort of stepping.
3368
+
3369
+ @item at_return(@var{file}, @var{line})
3370
+ @vindex Byebug::Context::at_return(@var{file}, @var{line})
3371
+ This routine is called when byebug encounters a ``return'' event for
3372
+ which it has been indicated we want to stop at, such as by hitting a
3373
+ @code{finish} statement.
3374
+
3375
+ @item debug_load(@var{file}, @var{stop-initially})
3376
+ @vindex Byebug::Context::debug_load(@var{file}, @var{stop-initially})
3377
+ This method should be used to debug a file. If the file terminates
3378
+ normally, @code{nil} is returned. If not a backtrace is returned.
3379
+
3380
+ The @var{stop-initially} parameter indicates whether the program
3381
+ should stop after loading. If an explicit call to byebug is in
3382
+ the debugged program, you may want to set this @code{false}.
3383
+ @end table
3384
+
3385
+ @node Byebug.Command
3386
+ @subsection The @code{Byebug::Command} Class
3387
+
3388
+ Each command you run is in fact its own class. Should you want to extend
3389
+ byebug, it's pretty easy to do since after all byebug is Ruby.
3390
+
3391
+ Each @code{Byebug#Command} class should have the a @code{regexp}
3392
+ method. This method returns regular expression for command-line
3393
+ strings that match your command. It's up to you to make sure this
3394
+ regular expression doesn't conflict with another one. If it does, it's
3395
+ undefined which one will get matched and run
3396
+
3397
+ In addition the instance needs these methods:
3398
+ @table @code
3399
+ @item execute
3400
+ Code which gets run when you type a command (string) that matches the
3401
+ commands regular expression.
3402
+ @item help
3403
+ A string which gets displayed when folks as for help on that command
3404
+ @item help_command
3405
+ A name used the help system uses to show what commands are available.
3406
+ @end table
3407
+
3408
+ Here's a small example of a new command:
3409
+ @smallexample
3410
+ module Byebug
3411
+ class MyCommand < Command
3412
+ def regexp
3413
+ /^\s*me$/ # Regexp that will match your command
3414
+ end
3415
+
3416
+ def execute
3417
+ puts "hi" # What you want to happen when your command runs
3418
+ end
3419
+ class << self
3420
+ def help_command
3421
+ 'me' # String name of command
3422
+ end
3423
+ def help(cmd)
3424
+ # Some sort of help text.
3425
+ %@{This does whatever it is I want to do@}
3426
+ end
3427
+ end
3428
+ end
3429
+ @end smallexample
3430
+
3431
+ Now here's an example of how you can load/use it:
3432
+ @smallexample
3433
+ require 'rubygems'
3434
+ require 'byebug'
3435
+ require '/tmp/mycmd.rb' # or wherever
3436
+ Byebug.start
3437
+ x=1
3438
+ byebug
3439
+ y=2
3440
+ @end smallexample
3441
+
3442
+ And now an example of invoking it:
3443
+ @smallexample
3444
+ ruby /tmp/testit.rb:
3445
+ /tmp/testit.rb:7
3446
+ y=2
3447
+ (rdb:1) help
3448
+ byebug help v0.10.3
3449
+ Type 'help <command-name>' for help on a specific command
3450
+ Available commands:
3451
+ backtrace delete enable help method putl set trace
3452
+ break disable eval info next quit show undisplay
3453
+ catch display exit irb p reload source up
3454
+ condition down finish list pp restart step var
3455
+ continue edit frame me ps save thread where
3456
+ ^^ This is you
3457
+
3458
+ (rdb:1) help me
3459
+ This does whatever it is I want to do
3460
+ (rdb:1) me
3461
+ hi
3462
+ (rdb:1)
3463
+ @end smallexample
3464
+
3465
+ @node Kernel routines
3466
+ @section Additions to @code{Kernel}
3467
+
3468
+ @table @code
3469
+
3470
+ @item byebug @ovar{steps=1}
3471
+ @vindex @code{Kernel::byebug}
3472
+ Enters byebug in the current thread after a stepping @var{steps} line-event steps.
3473
+ Before entering byebug startup script is read.
3474
+
3475
+ Setting @var{steps} to 0 will cause a break in byebug subroutine
3476
+ and not wait for eany line event to occur. This could be useful you
3477
+ want to stop right after the last statement in some scope.
3478
+
3479
+ Consider this example:
3480
+ @smallexample
3481
+ $ cat scope-test.rb
3482
+
3483
+ require 'rubygems'
3484
+ require 'byebug' ; Byebug.start
3485
+ 1.times do
3486
+ a = 1
3487
+ byebug # implied steps=1
3488
+ end
3489
+ y = 1
3490
+
3491
+ $ scope-test.rb:8
3492
+ y = 1
3493
+ (rdb:1) p a
3494
+ NameError Exception: undefined local variable or method `a' for main:Object
3495
+ (rdb:1)
3496
+ @end smallexample
3497
+ The byebug will get at the line event which follows @samp{a=1}. This
3498
+ is outside the @code{do} block scope where @var{a} is defined. If
3499
+ instead you want to stop before leaving the @code{do} loop it is
3500
+ possibly to stop right inside the @code{byebug}; call with 0 zero parameter:
3501
+ @smallexample
3502
+ $ cat scope-test.rb
3503
+
3504
+ require 'rubygems'
3505
+ require 'byebug' ; Byebug.start
3506
+ 1.times do
3507
+ a = 1
3508
+ byebug(0)
3509
+ end
3510
+ y = 1
3511
+
3512
+ $ scope-test.rb:8
3513
+ ../lib/byebug-base.rb:175
3514
+ Byebug.current_context.stop_frame = 0
3515
+ (rdb:1) where
3516
+ --> #0 Kernel.byebug(steps#Fixnum) at line ../lib/byebug-base.rb:175
3517
+ #1 at line scope-test.rb:6
3518
+ #2 at line scope-test.rb:4
3519
+ (rdb:1) up
3520
+ #1 at line scope-test.rb:6
3521
+ (rdb:1) p a
3522
+ 1
3523
+ (rdb:1)
3524
+ @end smallexample
3525
+ As seen above you will have to position the frame up one to be back in
3526
+ your debugged program rather than in byebug.
3527
+
3528
+ @item breakpoint @ovar{steps=1}
3529
+ @vindex @code{Kernel::breakpoint}
3530
+ An alias for byebug.
3531
+
3532
+ @item binding_n @ovar{n=0}
3533
+ @vindex @code{Kernel::binding_n}
3534
+ Returns a @samp{binding()} for the @var{n}-th call frame. Note however that you
3535
+ need to first call @samp{Byebug.start} before issuing this call.
3536
+
3537
+ @end table
3538
+
3539
+ @node Using from GitHub
3540
+ @appendix Building and Installing from the GitHub Repository
3541
+
3542
+ Here are Unix-centric instructions. If you have Microsoft Windows or
3543
+ OSX some of the below may need adjusting.
3544
+
3545
+ @menu
3546
+ * Prerequisites::
3547
+ * Package Checkout::
3548
+ * Trying Out::
3549
+ * Running Regression Tests::
3550
+ * Building the Documentation and Emacs files::
3551
+ * Building for Microsoft Windows::
3552
+ @end menu
3553
+
3554
+ @node Prerequisites
3555
+ @section Prerequisites: To build the package you'll need at a minimum:
3556
+
3557
+ @itemize @bullet
3558
+ @item
3559
+ Ruby (of course). Currently only version 1.8.6 and above but not
3560
+ version 1.9.@emph{x} work.
3561
+ @item
3562
+ Ruby development headers. This typically includes a file called @file{ruby.h}
3563
+ @item
3564
+ A C compiler like GNU C (@code{gcc})
3565
+ @item
3566
+ Rake
3567
+ @item
3568
+ Subversion (@code{svn}).
3569
+ @end itemize
3570
+
3571
+ If you want to build the documentation and install Emacs files, you'll
3572
+ also need:
3573
+
3574
+ @itemize @bullet
3575
+ @item
3576
+ a POSIX shell like bash
3577
+ @item
3578
+ autoconf
3579
+ @item
3580
+ automake
3581
+ @item
3582
+ GNU Make
3583
+ @item
3584
+ texinfo
3585
+ @end itemize
3586
+
3587
+ @node Package Checkout
3588
+ @section Basic Package Checkout and Installation
3589
+
3590
+ Check out the trunk of repository following the instructions at
3591
+ @url{http://rubyforge.org/scm/?group_id=1900} For example on a Unixy system,
3592
+ this may work:
3593
+
3594
+ @smallexample
3595
+ mkdir byebug
3596
+ cd byebug
3597
+ svn checkout svn://rubyforge.org/var/svn/byebug/trunk trunk
3598
+ @end smallexample
3599
+
3600
+ In order to make the Ruby gems, @code{byebug} and
3601
+ @code{byebug-base}, get yourself into the trunk directory after
3602
+ the code has been checked out and run:
3603
+
3604
+ @smallexample
3605
+ cd trunk # This is the same trunk checked out above.
3606
+ rake package
3607
+ @end smallexample
3608
+
3609
+ If all goes well you should have some gem files put in the directory
3610
+ @code{pkg}. Use the gem command to install that.
3611
+
3612
+ @smallexample
3613
+ sudo gem install byebug-*.gem # See gem help for other possibilities
3614
+ @end smallexample
3615
+
3616
+ If all goes well byebug script has been installed byebug is
3617
+ now ready to run. But if everything goes well you might want to run
3618
+ the built-in regression tests to make sure everything is okay.
3619
+ See step 3 below.
3620
+
3621
+ If the gem install didn't work,'t there may be a problem with your C
3622
+ compiler or the Ruby headers are not installed.
3623
+
3624
+ @node Trying Out
3625
+ @section Trying Out without Installing
3626
+
3627
+ You don't have to build a gem file to try out ruby debug. In fact when
3628
+ developing new features for byebug, developers often you want to
3629
+ try it out @emph{before} installing. If you have a problem in the latter
3630
+ part of step 1 you may want to try this approach since we go into a
3631
+ little more detail as to what happens under the covers when you do the
3632
+ gem install.
3633
+
3634
+ Run (from trunk)
3635
+ @smallexample
3636
+ rake lib
3637
+ @end smallexample
3638
+
3639
+ This creates a Makefile and builds byebug shared library. (On
3640
+ Unix the name is @code{byebug.so}).
3641
+
3642
+ Once this is done you can run byebug as you would byebug using the
3643
+ script @code{runner.sh}. For example (again from trunk)
3644
+
3645
+ @smallexample
3646
+ ./runner.sh ~/my-ruby-program.rb
3647
+ @end smallexample
3648
+
3649
+ @node Running Regression Tests
3650
+ @section Running the Regression Tests
3651
+
3652
+ We've put together some basic tests to make sure byebug is doing
3653
+ what we think it should do. To run these (from @code{trunk}):
3654
+
3655
+ @smallexample
3656
+ rake test
3657
+ @end smallexample
3658
+
3659
+ If you didn't build byebug shared library and skipped step 2,
3660
+ don't worry @code{rake test} will do step 2 for you. You should see a
3661
+ line that ends something like:
3662
+
3663
+ @smallexample
3664
+ Finished in 2.767579 seconds.
3665
+
3666
+ 12 tests, 35 assertions, 0 failures, 0 errors
3667
+ @end smallexample
3668
+
3669
+ The number of seconds, tests, and assertions may be different from the
3670
+ above. However you @emph{should} see exactly ``0 failures, 0 errors.''
3671
+
3672
+ @node Building the Documentation and Emacs files
3673
+ @section Building the Documentation and Testing/Installing Emacs Files
3674
+
3675
+ Of course, I recommend you read byebug manual that comes with
3676
+ the package. If you have the prerequisites described above, run this
3677
+ once:
3678
+ @smallexample
3679
+ sh ./autogen.sh
3680
+ @end smallexample
3681
+
3682
+ Then run:
3683
+ @smallexample
3684
+ ./configure
3685
+ make
3686
+ make test # Runs Emacs regression tests
3687
+ sudo make install # Or arrange to do this as root
3688
+ @end smallexample
3689
+
3690
+ @node Building for Microsoft Windows
3691
+ @section Building for Microsoft Windows
3692
+
3693
+ Microsoft Windows is ``special'' and building @code{byebug-base}
3694
+ on it requires extra care. A problem here seems to be that the
3695
+ ``One-click'' install is compiled using Microsoft Visual Studio C, version 6
3696
+ which is not sold anymore and is rather old.
3697
+
3698
+ Instead I suggest building via mingw/msys.
3699
+ @url{http://eigenclass.org/hiki.rb?cmd=view&p=cross+compiling+rcovrt&key=mingw}
3700
+ has instructions on how to do. Some amendments to these instructions.
3701
+
3702
+ First, those instructions are a little GNU/Linux centric. If you are
3703
+ using Ubuntu or Debian, then this should be the easiest to follow the
3704
+ instructions. On Ubuntu or Debian there is a mingw3 Debian
3705
+ package. Installing that will give you the cross compiler that is a
3706
+ prerequisite. Alternatively if you are running MS Windows I notice
3707
+ that cygwin also has a mingw package. Or possibly you could use MinGW
3708
+ directly. For other OS's you might have to build a cross-compiler,
3709
+ i.e. gcc which emits win32 code and can create a win32 DLL.
3710
+
3711
+ After you have a cross compiler you need to download the Ruby source
3712
+ and basically build a ruby interpreter. The cross-compile.sh script
3713
+ works although when I downloaded it, it had lots of blank space at the
3714
+ beginning which will mess up the Unix magic interpretation. That is
3715
+ remove the blanks in front of @code{#/bin/sh}.
3716
+
3717
+ On my system, this script fails in running @code{make ruby} because the
3718
+ fake.rb that got created needed to have a small change:
3719
+
3720
+ @smallexample
3721
+
3722
+ ALT_SEPARATOR = "\"; \
3723
+ @end smallexample
3724
+ should be:
3725
+ @smallexample
3726
+ ALT_SEPARATOR = "\\"; \
3727
+ @end smallexample
3728
+
3729
+ After fixing this, run @code{make ruby}. Also, I needed to run
3730
+ @code{make rubyw}.
3731
+
3732
+ And then @code{make install} as indicated.
3733
+
3734
+ Once all of that's in place, the place you want be is in
3735
+ @code{byebug/trunk/ext/win32}, not @code{byebug/ext}.
3736
+
3737
+ So let's say you've installed the cross-compiled install ruby in
3738
+ @code{/usr/local/ruby-mingw32/}. Here then are the commands to build @code{byebug-base-}@emph{xxx}@code{-mswin32.gem}:
3739
+ @smallexample
3740
+ cd .../byebug/trunk/ext/win32
3741
+ ruby -I /usr/local/ruby-mingw32/lib/ruby/1.8/i386-mingw32 ../extconf.rb
3742
+ make # Not rake
3743
+ cd ../.. # back in byebug/trunk
3744
+ rake win32_gem
3745
+ @end smallexample
3746
+
3747
+ @node Class Module Method Index
3748
+ @unnumbered Class, Module and Method Index
3749
+ @printindex vr
3750
+
3751
+ @node Command Index
3752
+ @unnumbered Command Index
3753
+ @printindex ky
3754
+
3755
+ @node General Index
3756
+ @unnumbered General Index
3757
+ @printindex cp
3758
+
3759
+ @tex
3760
+ % I think something like @colophon should be in texinfo. In the
3761
+ % meantime:
3762
+ \long\def\colophon{\hbox to0pt{}\vfill
3763
+ \centerline{The body of this manual is set in}
3764
+ \centerline{\fontname\tenrm,}
3765
+ \centerline{with headings in {\bf\fontname\tenbf}}
3766
+ \centerline{and examples in {\tt\fontname\tentt}.}
3767
+ \centerline{{\it\fontname\tenit\/},}
3768
+ \centerline{{\bf\fontname\tenbf}, and}
3769
+ \centerline{{\sl\fontname\tensl\/}}
3770
+ \centerline{are used for emphasis.}\vfill}
3771
+ \page\colophon
3772
+ % Blame: doc@cygnus.com, 1991.
3773
+ @end tex
3774
+
3775
+ @bye