Byebug

Debugging in Ruby 2.0

Byebug is a simple to use, feature rich debugger for Ruby 2.0. It uses the new TracePoint API for execution control and the new Debug Inspector API for call stack navigation, so it doesn't depend on internal core sources. It's developed as a C extension, so it's fast. And it has a full test suite so it's reliable.

It allows you to see what is going on inside a Ruby program while it executes and can do four main kinds of things to help you catch bugs in the act:

Start your program or attach to it, specifying anything that might affect its behavior.
Make your program stop on specified conditions.
Examine what has happened when your program has stopped.
Change things in your program, so you can experiment with correcting the effects of one bug and go on to learn about another.

Install

$ gem install byebug

Please upgrade your ruby to 2.0.0-p247 or higher - a bug in ruby core was directly affecting byebug and a fix for it has been released with this patchlevel (see #5 for more information)

Usage

Simply drop

byebug

wherever you want to start debugging and the execution will stop there. If you are debugging rails, start the server and once the execution get to your byebug command you will get a debugging prompt.

Former debugger or ruby-debug users, notice:

Some gems (rails, rspec) implement debugging flags (-d, --debugger) that early require and start the debugger. These flags are a performance penalty and Byebug doesn't need them anymore so my recommendation is not to use them.
Stopping execution using the word debugger doesn't work anymore unless you explicitly alias it. Similarly, the startup configuration file is now called .byebugrc instead of .rdebugrc.
autoreload, autoeval and autolist are default options in Byebug so you no longer need to set them in the startup file.

What's different from debugger

Works on 2.0.0 and it doesn't on 1.9.x.
Has no MRI internal source code dependencies, just a clean API.
Fixes most of debugger's current open issues:
- Post-mortem mode segfaulting.
- Line number wrongly shown as zero in backtrace.
- Line tracing.
- Colon delimited include paths.
- Nice markdown guide.
- Ruby 2.0 support.
- where/bt does not in fact give a backtrace.
- byebug can now be placed at the end of a block or method call.
Very actively mantained.
Editor agnostic: no external editor built-in support.
Pry command is built-in. No need of external gem like debugger-pry.

Semantic Versioning

Byebug tries to follow semantic versioning. Backwards compatibility doesn't seem like a critic issue for a debugger because it's not supposed to be used permanently by any program, let alone in production environments. However, I still like the idea of giving some meaning to version changes.

Byebug's public API is determined by its set of commands

+-----------+----------+------------------------------------------------+
|  Command  | Aliases  |                  Subcommands                   |
+-----------+----------+------------------------------------------------+
| backtrace | bt|where |                                                |
| break     |          |                                                |
| catch     |          |                                                |
| condition |          |                                                |
| continue  |          |                                                |
| delete    |          |                                                |
| disable   |          | breakpoints|display                            |
| display   |          |                                                |
| down      |          |                                                |
| edit      |          |                                                |
| enable    |          | breakpoints|display                            |
| finish    |          |                                                |
| frame     |          |                                                |
| help      |          |                                                |
| info      |          | args|breakpoints|catch|display|file|files      |
|           |          | global_variables|instance_variables|line       |
|           |          | locals|program|stack|variables                 |
| irb       |          |                                                |
| kill      |          |                                                |
| list      |          |                                                |
| method    |          | instance|iv                                    |
| next      |          |                                                |
| p         | eval     |                                                |
| pp        |          |                                                |
| pry       |          |                                                |
| ps        |          |                                                |
| putl      |          |                                                |
| quit      | exit     |                                                |
| reload    |          |                                                |
| restart   |          |                                                |
| save      |          |                                                |
| set       |          | args|autoeval|autoirb|autolist|autoreload      |
|           |          | basename|callstyle|forcestep|fullpath|history  |
|           |          | linetrace|linetrace_plus|listsize|post_mortem  |
|           |          | stack_trace_on_error|testing|width             |
| show      |          | args|autoeval|autoirb|autolist|autoreload      |
|           |          | basename|callstyle|commands|forcestep|fullpath |
|           |          | history|linetrace|linetrace_plus|listsize      |
|           |          | post_mortem|stack_trace_on_error|width         |
| skip      |          |                                                |
| source    |          |                                                |
| step      |          |                                                |
| thread    |          | current|list|resume|stop|switch                |
| trace     |          |                                                |
| undisplay |          |                                                |
| up        |          |                                                |
| var       |          | class|constant|global|instance|local|ct        |
+-----------+----------+------------------------------------------------+

Getting Started

A handful of commands are enough to get started using byebug. The following session illustrates these commands.

$ byebug triangle.rb
[1, 10] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
    1: # Compute the n'th triangle number: triangle(n) == (n*(n+1))/2
=>  2: def triangle(n)
    3:   tri = 0
    4:   0.upto(n) do |i|
    5:     tri += i
    6:   end
    7:   tri
    8: end
    9:
   10: t = triangle(3)
(byebug)

We are currently stopped before the first executable line of the program: line 2 of triangle.rb. If you are used to less dynamic languages and have used debuggers for more statically compiled languages like C, C++, or Java, it may seem odd to be stopped before a function definition but in Ruby line 2 is executed.

Byebug's prompt is (byebug). If the program has died and you are in post-mortem debugging, (byebug:post-mortem) is used instead. If the program has terminated normally, the string this position will be (byebug:ctrl). The commands available change depending on the program's state.

Byebug automatically lists 10 lines of code centered around the current line everytime it is stopped. The current line is marked with =>, so the range byebug would like to show is [-3..6]. However since there aren't 5 lines before the current line, the range is moved up so we can actually display 10 lines of code.

Now let us step through the program.

(byebug) step
[2, 11] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
    2: def triangle(n)
    3:   tri = 0
    4:   0.upto(n) do |i|
    5:     tri += i
    6:   end
    7:   tri
    8: end
    9:
=> 10: t = triangle(3)
   11: puts t
(byebug) <RET> # hit enter
[1, 10] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
    1: # Compute the n'th triangle number: triangle(n) == (n*(n+1))/2
    2: def triangle(n)
=>  3:   tri = 0
    4:   0.upto(n) do |i|
    5:     tri += i
    6:   end
    7:   tri
    8: end
    9:
   10: t = triangle(3)
(byebug) p tri
nil
(byebug) step
[1, 10] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
    1: # Compute the n'th triangle number: triangle(n) == (n*(n+1))/2
    2: def triangle(n)
    3:   tri = 0
=>  4:   0.upto(n) do |i|
    5:     tri += i
    6:   end
    7:   tri
    8: end
    9:
   10: t = triangle(3)
(byebug) p tri
0

The first step command runs the script one executable unit. The second command we entered was just hitting the return key; byebug remembers the last command you entered was step and it runs it again.

One way to print the values of variables is p (there are other ways). When we look at the value of tri the first time, we see it is nil. Again we are stopped before the assignment on line 3, and this variable hasn't been set previously. However after issuing another step command we see that the value is 0 as expected. If every time we stop we want to see the value of tri to see how things are going, there is a better way by setting a display expression:

(byebug) display tri
1: tri = 0

Now let us run the program until we return from the function. We'll want to see which lines get run, so we turn on line tracing. If we don't want whole paths to be displayed when tracing, we can turn on basename.

(byebug) display i
2: i =
(byebug) set linetrace on
line tracing is on.
(byebug) set basename on
basename is on.
(byebug) finish
Tracing: triangle.rb:5 tri += i
1: tri = 0
2: i = 0
Tracing: triangle.rb:5 tri += i
1: tri = 0
2: i = 1
Tracing: triangle.rb:5 tri += i
1: tri = 1
2: i = 2
Tracing: triangle.rb:5 tri += i
1: tri = 3
2: i = 3
Tracing: triangle.rb:7 tri
1: tri = 6
2: i =
Tracing: triangle.rb:11 puts t
1: tri =
2: i =
[2, 11] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
    2: def triangle(n)
    3:   tri = 0
    4:   0.upto(n) do |i|
    5:     tri += i
    6:   end
    7:   tri
    8: end
    9:
   10: t = triangle(3)
=> 11: puts t
1: tri =
2: i =
(byebug) quit
Really quit? (y/n) y

So far, so good. As you can see from the above to get out of byebug, one can issue a quit command (q and exit are just as good). If you want to quit without being prompted, suffix the command with an exclamation mark, e.g., q!.

The rest of the tutorial is available here

pry-byebug adds next, step, finish, continue and break commands to pry using byebug.
ruby-debug-passenger adds a rake task that restarts Passenger with byebug connected.
minitest-byebug starts a byebug session on minitest failures.

Credits

Everybody who has ever contributed to this forked and reforked piece of software, specially:

Kent Sibilev and Mark Moseley, original authors of ruby-debug.
Gabriel Horner, debugger's mantainer.
Koichi Sasada, author of the new C debugging API for Ruby.
Dennis Ushakov, author of debase, the starting point of this.
Logo by Ivlichev Victor Petrovich
@kevjames3 for testing, bug reports and the interest in the project.