# GUIDE

## Introduction

### First Steps

A handful of commands are enough to get started using `byebug`. The following
session illustrates these commands. Take the following sample file:

```ruby
#
# The n'th triangle number: triangle(n) = n*(n+1)/2 = 1 + 2 + ... + n
#
def triangle(n)
  tri = 0

  0.upto(n) { |i| tri += i }

  tri
end

t = triangle(3)
puts t

```

Let's debug it.

```console
$ byebug /path/to/triangle.rb

[1, 10] in /path/to/triangle.rb
    1: #
    2: # The n'th triangle number: triangle(n) = n*(n+1)/2 = 1 + 2 + ... + n
    3: #
=>  4: def triangle(n)
    5:   tri = 0
    6:
    7:   0.upto(n) { |i| tri += i }
    8:
    9:   tri
   10: end
(byebug)
```

We are currently stopped before the first executable line of the program: line 4
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 4 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 and the `--no-quit` option has been specified in the
command line, the prompt will be `(byebug:ctrl)` instead. The commands available
change depending on the program's state.

Byebug automatically lists 10 lines of code centered around the current line
every time it is stopped. The current line is marked with `=>`. If the range
would overflow the beggining or the end of the file, byebug will move it
accordingly so that only actual real lines of code are displayed.

Now let us step through the program.

```console
(byebug) step

[5, 14] in /path/to/triangle.rb
    5:   tri = 0
    6:
    7:   0.upto(n) { |i| tri += i }
    8:
    9:   tri
   10: end
   11:
=> 12: t = triangle(3)
   13: puts t
(byebug) <RET> # hit enter

[1, 10] in /path/to/triangle.rb
    1: #
    2: # The n'th triangle number: triangle(n) = n*(n+1)/2 = 1 + 2 + ... + n
    3: #
    4: def triangle(n)
=>  5:   tri = 0
    6:
    7:   0.upto(n) { |i| tri += i }
    8:
    9:   tri
   10: end
(byebug) eval tri
nil
(byebug) step

[2, 11] in /path/to/triangle.rb
    2: # The n'th triangle number: triangle(n) = n*(n+1)/2 = 1 + 2 + ... + n
    3: #
    4: def triangle(n)
    5:   tri = 0
    6:
=>  7:   0.upto(n) { |i| tri += i }
    8:
    9:   tri
   10: end
   11:
(byebug) eval 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 runs it again.

One way to print the values of variables is `eval` (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 5, and this variable hadn'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:

```console
(byebug) display tri
1: tri = 0
```

Now let us run the program until right before 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_.

```console
(byebug) set linetrace
linetrace is on
(byebug) set basename
basename is on
(byebug) finish 0
Tracing: triangle.rb:7   0.upto(n) { |i| tri += i }
1: tri = 0
Tracing: triangle.rb:7   0.upto(n) { |i| tri += i }
1: tri = 0
Tracing: triangle.rb:7   0.upto(n) { |i| tri += i }
1: tri = 1
Tracing: triangle.rb:7   0.upto(n) { |i| tri += i }
1: tri = 3
Tracing: triangle.rb:9   tri
1: tri = 6
1: tri = 6

[4, 13] in /home/davidr/Proyectos/byebug/triangle.rb
    4: def triangle(n)
    5:   tri = 0
    6:
    7:   0.upto(n) { |i| tri += i }
    8:
    9:   tri
=> 10: end
   11:
   12: t = triangle(3)
   13: puts t
(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 (or the abbreviation `q`). If you want to quit
without being prompted, suffix the command with an exclamation mark, e.g., `q!`.

### Second Sample Session: Delving Deeper

In this section we'll introduce breakpoints, the call stack and restarting.
Below we will debug a simple Ruby program to solve the classic Towers of Hanoi
puzzle. It is augmented by the bane of programming: some command-parameter
processing with error checking.

```ruby
#
# Solves the classic Towers of Hanoi puzzle.
#
def hanoi(n, a, b, c)
  hanoi(n - 1, a, c, b) if n - 1 > 0

  puts "Move disk #{a} to #{b}"

  hanoi(n - 1, c, b, a) if n - 1 > 0
end

n_args = $ARGV.length

raise("*** Need number of disks or no parameter") if n_args > 1

n = 3

if n_args > 0
  begin
    n = $ARGV[0].to_i
  rescue ValueError
    raise("*** Expecting an integer, got: #{$ARGV[0]}")
  end
end

raise("*** Number of disks should be between 1 and 100") if n < 1 || n > 100

hanoi(n, :a, :b, :c)
```

Recall in the first section it was stated that before the `def` is run, the
method it names is undefined. Let's check that out. First let's see what
private methods we can call before running `def hanoi`.

```console
$ byebug path/to/hanoi.rb

    1: #
    2: # Solves the classic Towers of Hanoi puzzle.
    3: #
    4: def hanoi(n, a, b, c)
    5:   hanoi(n - 1, a, c, b) if n - 1 > 0
    6:
    7:   puts "Move disk #{a} to #{b}"
    8:
    9:   hanoi(n - 1, c, b, a) if n - 1 > 0
   10: end
(byebug) private_methods
public
private
include
using
define_method
default_src_encoding
DelegateClass
Digest
timeout
initialize_copy
initialize_dup
initialize_clone
sprintf
format
Integer
Float
String
Array
Hash
warn
raise
fail
global_variables
__method__
__callee__
__dir__
eval
local_variables
iterator?
block_given?
catch
throw
loop
respond_to_missing?
trace_var
untrace_var
at_exit
syscall
open
printf
print
putc
puts
gets
readline
select
readlines
`
p
test
srand
rand
trap
load
require
require_relative
autoload
autoload?
proc
lambda
binding
caller
caller_locations
exec
fork
exit!
system
spawn
sleep
exit
abort
Rational
Complex
set_trace_func
gem_original_require
Pathname
pp
y
URI
rubygems_require
initialize
singleton_method_added
singleton_method_removed
singleton_method_undefined
method_missing
(byebug) private_methods.member?(:hanoi)
false
```

`private_methods` is not a byebug command but a Ruby feature. By default, when
`byebug` doesn't understand a command, it will evaluate it as if it was a Ruby
command. You can use any Ruby to inspect your program's state at the place it
is stopped.

Now let's see what happens after stepping:

```console
(byebug) step

[5, 14] in /path/to/hanoi.rb
    5:   hanoi(n - 1, a, c, b) if n - 1 > 0
    6:
    7:   puts "Move disk #{a} to #{b}"
    8:
    9:   hanoi(n - 1, c, b, a) if n - 1 > 0
   10: end
   11:
=> 12: n_args = $ARGV.length
   13:
   14: raise("*** Need number of disks or no parameter") if n_args > 1
(byebug) private_methods.member?(:hanoi)
true
(byebug)
```

Okay, lets go on and talk about program arguments.

```console
(byebug) $ARGV
[]
```

Oops. We forgot to specify any parameters to this program. Let's try again. We
can use the `restart` command here.

```console
(byebug) restart 3
Re exec'ing:
  /path/to/exe/byebug /path/to/hanoi.rb 3

[1, 10] in /path/to/hanoi.rb
    1: #
    2: # Solves the classic Towers of Hanoi puzzle.
    3: #
=>  4: def hanoi(n, a, b, c)
    5:   hanoi(n - 1, a, c, b) if n - 1 > 0
    6:
    7:   puts "Move disk #{a} to #{b}"
    8:
    9:   hanoi(n - 1, c, b, a) if n - 1 > 0
   10: end
(byebug) break 5
Created breakpoint 1 at /path/to/hanoi.rb:5
(byebug) continue
Stopped by breakpoint 1 at /path/to/hanoi.rb:5

[1, 10] in /path/to/hanoi.rb
    1: #
    2: # Solves the classic Towers of Hanoi puzzle.
    3: #
    4: def hanoi(n, a, b, c)
=>  5:   hanoi(n - 1, a, c, b) if n - 1 > 0
    6:
    7:   puts "Move disk #{a} to #{b}"
    8:
    9:   hanoi(n - 1, c, b, a) if n - 1 > 0
   10: end
(byebug) display n
1: n = 3
(byebug) display a
2: a = :a
(byebug) display b
3: b = :b
(byebug) undisplay 3
(byebug) continue
Stopped by breakpoint 1 at /path/to/hanoi.rb:5
1: n = 2
2: a = :a
[1, 10] in /path/to/hanoi.rb
    1: #
    2: # Solves the classic Towers of Hanoi puzzle.
    3: #
    4: def hanoi(n, a, b, c)
=>  5:   hanoi(n - 1, a, c, b) if n - 1 > 0
    6:
    7:   puts "Move disk #{a} to #{b}"
    8:
    9:   hanoi(n - 1, c, b, a) if n - 1 > 0
   10: end

(byebug) c
Stopped by breakpoint 1 at /path/to/hanoi.rb:5
1: n = 1
2: a = :a

[1, 10] in /path/to/hanoi.rb
    1: #
    2: # Solves the classic Towers of Hanoi puzzle.
    3: #
    4: def hanoi(n, a, b, c)
=>  5:   hanoi(n - 1, a, c, b) if n - 1 > 0
    6:
    7:   puts "Move disk #{a} to #{b}"
    8:
    9:   hanoi(n - 1, c, b, a) if n - 1 > 0
   10: end
(byebug) set nofullpath
fullpath is off
(byebug) where
--> #0  Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at .../shortpath/to/hanoi.rb:5
    #1  Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at .../shortpath/to/hanoi.rb:5
    #2  <top (required)> at .../Proyectos/byebug/hanoi.rb:28
(byebug)
```

In the above we added new commands: `break` (see [breakpoints]()), which
indicates to stop just before that line of code is run, and `continue`, which
resumes execution. To remove a display expression `undisplay` is used. If we
give a display number, just that display expression is removed.

We also used a new command `where`(see [backtrace]()) to show the callstack. In
the above situation, starting from the bottom line we see we called the `hanoi`
method from line 28 of the file `hanoi.rb` and the `hanoi` method called itself
two more times at line 5.

In the callstack we show a _current frame_ mark, the frame number, the method
being called, the names of the parameters, the types those parameters
_currently_ have and the file-line position. Remember it's possible that when
the program was called the parameters had different types, since the types of
variables can change dynamically. You can alter the style of what to show in the
trace (see [callstyle]()).

Now let's move around the callstack.

```console
(byebug) undisplay
Clear all expressions? (y/n) y
(byebug) n_args
NameError Exception: undefined local variable or method `n_args' for main:Object
(byebug) frame 2

[19, 28] in /path/to/hanoi.rb
   19:   begin
   20:     n = $ARGV[0].to_i
   21:   rescue ValueError
   22:     raise("*** Expecting an integer, got: #{$ARGV[0]}")
   23:   end
   24: end
   25:
   26: raise("*** Number of disks should be between 1 and 100") if n < 1 || n > 100
   27:
=> 28: hanoi(n, :a, :b, :c)
(byebug) n_args
1
(byebug) eval n
3
(byebug) down 2

[1, 10] in /path/to/hanoi.rb
    1: #
    2: # Solves the classic Towers of Hanoi puzzle.
    3: #
    4: def hanoi(n, a, b, c)
=>  5:   hanoi(n - 1, a, c, b) if n - 1 > 0
    6:
    7:   puts "Move disk #{a} to #{b}"
    8:
    9:   hanoi(n - 1, c, b, a) if n - 1 > 0
   10: end
(byebug) eval n
2
```

Notice in the above to get the value of variable `n` we had to use a print
command like `eval n`. If we entered just `n`, that would be taken to mean byebug
command `next`. In the current scope, variable `n_args` is not defined.  However
I can change to the top-most frame by using the `frame 2` command. Notice that
inside frame #2, the value of `n_args` can be shown. Also note that the value of
variable `n` is different.

### Attaching to a running program with `byebug`

In the previous sessions we've been calling byebug right at the outset, but
there is another mode of operation you might use. If there's a lot of code that
needs to be run before the part you want to inspect, it might not be efficient
or convenient to run byebug from the outset.

In this section we'll show how to enter the code in the middle of your program,
while delving more into byebug's operation. We will also use unit testing. Using
unit tests will greatly reduce the amount of debugging needed, while at the same
time, will increase the quality of your program.

What we'll do is take the `triangle` code from the first session and write a
unit test for that. In a sense we did write a tiny test for the program which
was basically the last line where we printed the value of `triangle(3)`. This
test however wasn't automated: the expectation is that someone would look at the
output and verify that what was printed is what was expected.

Before we can turn that into something that can be `required`, we probably want
to remove that output. However I like to keep in that line so that when I
look at the file, I have an example of how to run it.  Therefore we will
conditionally run this line if that file is invoked directly, but skip it if it
is not. _NOTE: `byebug` resets `$0` to try to make things like this work._

```ruby
if __FILE__ == $PROGRAM_NAME
  t = triangle(3)
  puts t
end
```

Okay, we're now ready to write our unit test and we'll use the `minitest`
framework for that. Here's the test code, it should be placed in the same
directory as `triangle.rb`.

```ruby
require "minitest/autorun"
require_relative "triangle.rb"

class TestTriangle < Minitest::Test
  def test_basic
    solutions = []

    0.upto(5) { |i| solutions << triangle(i) }

    assert_equal([0, 1, 3, 6, 10, 15], solutions, "First 5 triangle numbers")
  end
end
```

Let's say we want to stop before the first statement in our test method, we'll
add the following:

```ruby
...
def test_basic
  byebug
  solutions = []
...
```

Now we run the program, requiring `byebug`

```console
$ ruby -rbyebug test_triangle.rb
Run options: --seed 31679

# Running:

[2, 11] in test_triangle.rb
    2: require_relative "triangle.rb"
    3:
    4: class TestTriangle < Minitest::Test
    5:   def test_basic
    6:     byebug
=>  7:     solutions = []
    8:
    9:     0.upto(5) { |i| solutions << triangle(i) }
   10:
   11:     assert_equal([0, 1, 3, 6, 10, 15], solutions, "First 5 triangle numbers")
(byebug)
```

and we see that we are stopped at line 7 just before the initialization of the
list `solutions`.

Now let's see where we are...

```console
(byebug) set nofullpath
Displaying frame's full file names is off.
(byebug) bt
--> #0  TestTriangle.test_basic at .../Proyectos/byebug/test_triangle.rb:7
    #1  block (3 levels) in Minitest::Test.run at .../lib/minitest/test.rb:108
    #2  Minitest::Test.capture_exceptions at .../lib/minitest/test.rb:206
    #3  block (2 levels) in Minitest::Test.run at .../lib/minitest/test.rb:105
    #4  Minitest::Test.time_it at .../lib/minitest/test.rb:258
    #5  block in Minitest::Test.run at .../lib/minitest/test.rb:104
    #6  #<Class:Minitest::Runnable>.on_signal(name#String, action#Proc) at .../minitest-5.5.0/lib/minitest.rb:321
    #7  Minitest::Test.with_info_handler(&block#Proc) at .../lib/minitest/test.rb:278
    #8  Minitest::Test.run at .../lib/minitest/test.rb:103
    #9  #<Class:Minitest>.run_one_method(klass#Class, method_name#String) at .../minitest-5.5.0/lib/minitest.rb:768
    #10 #<Class:Minitest::Runnable>.run_one_method(klass#Class, method_name#String, reporter#Minitest::CompositeReporter) at .../minitest-5.5.0/lib/minitest.rb:295
    #11 block (2 levels) in #<Class:Minitest::Runnable>.run(reporter#Minitest::CompositeReporter, options#Hash) at .../minitest-5.5.0/lib/minitest.rb:289
    ͱ-- #12 Array.each at .../minitest-5.5.0/lib/minitest.rb:288
    #13 block in #<Class:Minitest::Runnable>.run(reporter#Minitest::CompositeReporter, options#Hash) at .../minitest-5.5.0/lib/minitest.rb:288
    #14 #<Class:Minitest::Runnable>.on_signal(name#String, action#Proc) at .../minitest-5.5.0/lib/minitest.rb:321
    #15 #<Class:Minitest::Runnable>.with_info_handler(reporter#Minitest::CompositeReporter, &block#Proc) at .../minitest-5.5.0/lib/minitest.rb:308
    #16 #<Class:Minitest::Runnable>.run(reporter#Minitest::CompositeReporter, options#Hash) at .../minitest-5.5.0/lib/minitest.rb:287
    #17 block in #<Class:Minitest>.__run(reporter#Minitest::CompositeReporter, options#Hash) at .../minitest-5.5.0/lib/minitest.rb:150
    ͱ-- #18 Array.map at .../minitest-5.5.0/lib/minitest.rb:150
    #19 #<Class:Minitest>.__run(reporter#Minitest::CompositeReporter, options#Hash) at .../minitest-5.5.0/lib/minitest.rb:150
    #20 #<Class:Minitest>.run(args#Array) at .../minitest-5.5.0/lib/minitest.rb:127
    #21 block in #<Class:Minitest>.autorun at .../minitest-5.5.0/lib/minitest.rb:56
(byebug)
```

We get the same result as if we had run byebug from the outset.

### Debugging Oddities: How debugging Ruby may be different from other languages

If you are used to debugging in other languages like C, C++, Perl, Java or even
Bash (see [bashdb](http://bashdb.sourceforge.net)), there may be a number of things that
seem or feel a little bit different and may confuse you. A number of these
things aren't oddities of the debugger per se but differences in how Ruby works
compared to those other languages. Because Ruby works a little differently from
those other languages, writing a debugger has to also be a little different as
well if it is to be useful. In this respect, using Byebug may help you
understand Ruby better.

We've already seen one such difference: the fact that we stop on method
definitions or `def`'s and that is because these are in fact executable
statements. In other compiled languages this would not happen because that's
already been done when you compile the program (or in Perl when it scans in the
program). In this section we'll consider some other things that might throw off
new users to Ruby who are familiar with other languages and debugging in them.

#### Bouncing Around in Blocks (iterators)

When debugging languages with coroutines like Python and Ruby, a method call may
not necessarily go to the first statement after the method header. It's possible
that the call will continue after a `yield` statement from a prior call.

```ruby
#
# Enumerator for primes
#
class SievePrime
  def initialize
    @odd_primes = []
  end

  def next_prime
    candidate = 2
    yield candidate
    not_prime = false
    candidate += 1

    loop do
      @odd_primes.each do |p|
        not_prime = (0 == (candidate % p))
        break if not_prime
      end

      unless not_prime
        @odd_primes << candidate
        yield candidate
      end

      candidate += 2
    end
  end
end

SievePrime.new.next_prime do |prime|
  puts prime
  break if prime > 10
end
```

```console
$ byebug primes.rb
[1, 10] in /path/to/primes.rb
    1: #
    2: # Enumerator for primes
    3: #
=>  4: class SievePrime
    5:   def initialize
    6:     @odd_primes = []
    7:   end
    8:
    9:   def self.next_prime(&block)
   10:    candidate = 2
(byebug) set linetrace
line tracing is on.
(byebug) set basename
basename in on.
(byebug) step 9
Tracing: primes.rb:5   def initialize
Tracing: primes.rb:9   def next_prime
Tracing: primes.rb:31 SievePrime.new.next_prime do |prime|
Tracing: primes.rb:6     @odd_primes = []
Tracing: primes.rb:10     candidate = 2
Tracing: primes.rb:11     yield candidate
Tracing: primes.rb:32   puts prime
2
Tracing: primes.rb:33   break if prime > 10
Tracing: primes.rb:12     not_prime = false

[7, 16] in /path/to/primes.rb
    7:   end
    8:
    9:   def next_prime
   10:     candidate = 2
   11:     yield candidate
=> 12:     not_prime = false
   13:     candidate += 1
   14:
   15:     loop do
   16:       @odd_primes.each do |p|
   17:         not_prime = (0 == (candidate % p))
(byebug)
```

The loop between lines 31-34 gets interleaved between those of
`SievePrime#next_prime`, lines 9-28 above.

#### No Parameter Values in a Call Stack

In traditional debuggers, in a call stack you can generally see the names of the
parameters and the values that were passed in.

Ruby is a very dynamic language and it tries to be efficient within the confines
of the language definition. Values generally aren't taken out of a variable or
expression and pushed onto a stack. Instead a new scope is created and the
parameters are given initial values. Parameter passing is by _reference_ not by
_value_ as it is say Algol, C, or Perl. During the execution of a method,
parameter values can change (and often do). In fact even the _class_ of the
object can change.

So at present, the name of the parameter is shown. The call-style setting
([callstyle]()) can be used to set whether the name is shown or the name and the
_current_ class of the object.

#### Lines You Can Stop At

Consider the following little Ruby program.

```ruby
"Yes it does" =~ /
(Yes) \s+
it  \s+
does
/ix
puts $1
```

The stopping points that Ruby records are the last two lines, lines 5 and 6.

Inside `byebug` you can get a list of stoppable lines for a file using the `info
file` command.

### Threading support

Byebug supports debugging Ruby programs making use of multiple threads.

Let's consider the following sample program:

```ruby
class Company
  def initialize(task)
    @tasks, @results = Queue.new, Queue.new

    @tasks.push(task)
  end

  def run
    manager = Thread.new { manager_routine }
    employee = Thread.new { employee_routine }

    sleep 6

    go_home(manager)
    go_home(employee)
  end

  #
  # An employee doing his thing
  #
  def employee_routine
    loop do
      if @tasks.empty?
        have_a_break(0.1)
      else
        work_hard(@tasks.pop)
      end
    end
  end

  #
  # A manager doing his thing
  #
  def manager_routine
    loop do
      if @results.empty?
        have_a_break(1)
      else
        show_off(@results.pop)
      end
    end
  end

  private

  def show_off(result)
    puts result
  end

  def work_hard(task)
    task ** task
  end

  def have_a_break(amount)
    sleep amount
  end

  def go_home(person)
    person.kill
  end
end

Company.new(10).run
```

The `Company` class simulates a real company. The company has a manager and an
employee represented by 2 threads: they work concurrently to achieve the
company's targets.

* The employee looks for tasks to complete. If there are tasks, it works hard to
  complete them. Otherwise he has a quick break.

```ruby
#
# An employee doing his thing
#
def employee_routine
  loop do
    if @tasks.empty?
      have_a_break(0.1)
    else
      work_hard(@tasks.pop)
    end
  end
end
```

* The manager, on the other hand, sits there all day and sporadically checks
  whether there are any results to show off.

```ruby
#
# A manager doing his thing
#
def manager_routine
  loop do
    if @results.empty?
      have_a_break(1)
    else
      show_off(@results.pop)
    end
  end
end
```

We do some abstractions easily readable in the code. Our tasks are just a
`Queue` of numbers, so are our results. What our employer does when he works is
some calculation with those numbers and what the manager does with the results
is printing them to the screen.

We instantiate a new company with an initial task and after running that
company we expect the result to be printed in the screen, but it is not.  Lets
debug our sample program:

```console
[1, 10] in /path/to/company.rb
=>  1: class Company
    2:   def initialize(task)
    3:     @tasks, @results = Queue.new, Queue.new
    4:
    5:     @tasks.push(task)
    6:   end
    7:
    8:   def run
    9:     manager = Thread.new { manager_routine }
   10:     employee = Thread.new { employee_routine }
(byebug) l

[11, 20] in /path/to/company.rb
   11:
   12:     sleep 6
   13:
   14:     go_home(manager)
   15:     go_home(employee)
   16:   end
   17:
   18:   #
   19:   # An employee doing his thing
   20:   #

(byebug) c 12
Stopped by breakpoint 1 at /path/to/company.rb:12

[7, 16] in /path/to/company.rb
    7:
    8:   def run
    9:     manager = Thread.new { manager_routine }
   10:     employee = Thread.new { employee_routine }
   11:
=> 12:     sleep 6
   13:
   14:     go_home(manager)
   15:     go_home(employee)
   16:   end
(byebug) th l
+ 1 #<Thread:0x0000000192f328 run> /path/to/company.rb:12
  2 #<Thread:0x00000001ff9870@/path/to/company.rb:9 sleep>
  3 #<Thread:0x00000001ff80d8@/path/to/company.rb:10 sleep>
```

What we have done here is just start our program and advance to the point
inmediately after our `employee` and `manager` threads have been created. We
can then check that the threads are there using the `thread list` command. Now
we want to debug both of this threads to check what's happening and look for the
bug.

```console
(byebug) th switch 3

[5, 14] in /path/to/company.rb
    5:     @tasks.push(task)
    6:   end
    7:
    8:   def run
    9:     manager = Thread.new { manager_routine }
=> 10:     employee = Thread.new { employee_routine }
   11:
   12:     sleep 6
   13:
   14:     go_home(manager)
(byebug) th stop 1; th stop 2
$ 1 #<Thread:0x00000001307310 sleep> /path/to/company.rb:12
$ 2 #<Thread:0x000000018bf438 sleep> /path/to/company.rb:9
(byebug) th l
$ 1 #<Thread:0x00000001307310 sleep> /path/to/company.rb:12
$ 2 #<Thread:0x000000018bf438@/path/to/company.rb:9 sleep> /path/to/company.rb:55
+ 3 #<Thread:0x00000001ff80d8@/path/to/company.rb:10 sleep> /path/to/company.rb:10
```

We have started by debugging the `employee` thread. To do that, we switch to
that thread using the `thread switch 3` command. The thread number is the one
specified by `thread list`, we know this is our worker thread because `thread
list` specifies where the thread is defined in the file (and its current
position if the thread is currently running).

After that we stopped the main thread and the worker thread, using the command
`thread stop`. We do this because we want to focus on the employee thread first
and don't want the program to finish while we are debugging. Notice that stopped
threads are marked with the "$" symbol whereas the current thread is marked with
the "+" symbol.

```console
(byebug) s

[17, 26] in /path/to/company.rb
   17:
   18:   #
   19:   # An employee doing his thing
   20:   #
   21:   def employee_routine
=> 22:     loop do
   23:       if @tasks.empty?
   24:         have_a_break(0.1)
   25:       else
   26:         work_hard(@tasks.pop)
(byebug) s

[18, 27] in /path/to/company.rb
   18:   #
   19:   # An employee doing his thing
   20:   #
   21:   def employee_routine
   22:     loop do
=> 23:       if @tasks.empty?
   24:         have_a_break(0.1)
   25:       else
   26:         work_hard(@tasks.pop)
   27:       end
(byebug) n

[21, 30] in /path/to/company.rb
   21:   def employee_routine
   22:     loop do
   23:       if @tasks.empty?
   24:         have_a_break(0.1)
   25:       else
=> 26:         work_hard(@tasks.pop)
   27:       end
   28:     end
   29:   end
   30:
(byebug) s

[49, 58] in /path/to/company.rb
   49:   def show_off(result)
   50:     puts result
   51:   end
   52:
   53:   def work_hard(task)
=> 54:     task ** task
   55:   end
   56:
   57:   def have_a_break(amount)
   58:     sleep amount
(byebug) s

[21, 30] in /path/to/company.rb
   21:   #
   22:   # An employee doing his thing
   23:   #
   24:   def employee_routine
   25:     loop do
=> 26:       if @tasks.empty?
   27:         have_a_break(0.1)
   28:       else
   29:         work_hard(@tasks.pop)
   30:       end
(byebug) n

[22, 31] in /path/to/company.rb
   22:   # An employee doing his thing
   23:   #
   24:   def employee_routine
   25:     loop do
   26:       if @tasks.empty?
=> 27:         have_a_break(0.1)
   28:       else
   29:         work_hard(@tasks.pop)
   30:       end
   31:     end
(byebug) n

[21, 30] in /path/to/company.rb
   21:   #
   22:   # An employee doing his thing
   23:   #
   24:   def employee_routine
   25:     loop do
=> 26:       if @tasks.empty?
   27:         have_a_break(0.1)
   28:       else
   29:         work_hard(@tasks.pop)
   30:       end
   31:     end
(byebug)
```

Everything seems fine in this thread. The first iteration the employee will do
his job, and after that it will just check for new tasks and sleep. Let's debug
the manager task now:

```console
(byebug) th resume 2
  2 #<Thread:0x000000019892d8@/path/to/company.rb:12 run> /path/to/company.rb:12
(byebug) th switch 2
  2 #<Thread:0x000000019892d8@/path/to/company.rb:12 sleep> /path/to/company.rb:12

[7, 16] in /path/to/company.rb
    7:
    8:   #
    9:   # A CEO running his company
   10:   #
   11:   def run
=> 12:     manager = Thread.new { manager_routine }
   13:     employee = Thread.new { employee_routine }
   14:
   15:     sleep 6
   16:
(byebug)
```

We used the command `thread resume` to restart the manager's thread and then
switch to it using `thread switch`. It's important to resume the thread's
execution before switching to it, otherwise we'll get a hang because we cannot
run a sleeping thread.

Now we can investigate the problem in the employer's side:

```console
(byebug) s
[30, 39] in /path/to/company.rb
   30:
   31:   #
   32:   # A manager doing his thing
   33:   #
   34:   def manager_routine
=> 35:     loop do
   36:       if @results.empty?
   37:         have_a_break(1)
   38:       else
   39:         show_off(@results.pop)
(byebug) s

[31, 40] in /path/to/company.rb
   31:   #
   32:   # A manager doing his thing
   33:   #
   34:   def manager_routine
   35:     loop do
=> 36:       if @results.empty?
   37:         have_a_break(1)
   38:       else
   39:         show_off(@results.pop)
   40:       end
(byebug) n

[32, 41] in /path/to/company.rb
   32:   # A manager doing his thing
   33:   #
   34:   def manager_routine
   35:     loop do
   36:       if @results.empty?
=> 37:         have_a_break(1)
   38:       else
   39:         show_off(@results.pop)
   40:       end
   41:     end
(byebug) n

[31, 40] in /path/to/company.rb
   31:   #
   32:   # A manager doing his thing
   33:   #
   34:   def manager_routine
   35:     loop do
=> 36:       if @results.empty?
   37:         have_a_break(1)
   38:       else
   39:         show_off(@results.pop)
   40:       end
(byebug)
```

Now we can see the problem, the `@results` variable is always empty! The
employee forgot to leave the results in his manager's deck. We fix it by
changing the line

```ruby
work_hard(@tasks.pop)
```

in the `employee_routine` method with the line

```ruby
@results << work_hard(@tasks.pop)
```

To be continued...

* More complex examples with objects, pretty printing and irb.
* Line tracing and non-interactive tracing.
* Post-mortem debugging.

## Getting in & out

### Starting byebug

There is a wrapper script called `byebug` which basically `require`'s the gem
then loads `byebug` before its argument (the program to be debugged) is started.
If you don't need to pass dash options to your program, which might be confused
with byebug options, then you don't need to add the `--`. To get a brief list of
options and descriptions, use the `--help` option.

```console
$ byebug --help

  byebug 3.5.1

  Usage: byebug [options] <script.rb> -- <script.rb parameters>

    -d, --debug               Set $DEBUG=true
    -I, --include list        Add paths to $LOAD_PATH
    -m, --[no-]post-mortem    Use post-mortem mode
    -q, --[no-]quit           Quit when script finishes
    -x, --[no-]rc             Run byebug initialization file
    -s, --[no-]stop           Stop when script is loaded
    -r, --require file        Require library before script
    -R, --remote [host:]port  Remote debug [host:]port
    -t, --[no-]trace          Turn on line tracing
    -v, --version             Print program version
    -h, --help                Display this message

```

Many options appear as a long option name, such as `--help` and a short one
letter option name, such as `-h`. The list of options is detailed below:

#### -h | --help

It causes `byebug` to print some basic help and exit.

#### -v | --version

It causes `byebug` to print its version number and exit.

#### -d | --debug

Sets `$DEBUG` to `true`. Compatible with Ruby's flag.

#### -I | --include path

Adds `path` to load path. `path` can be a single path or a colon separated path
list.

#### -m | --post-mortem

If your program raises an exception that isn't caught you can enter byebug for
inspection of what went wrong. You may also want to use this option in
conjunction with `--no-stop`. See also [Post-Mortem Debugging]().

#### --no-quit

Keep inside `byebug` after your program terminates normally.

#### --no-stop

Normally `byebug` stops before executing the first statement. If instead you
want it to start running initially and perhaps break it later in the execution,
use this option.

#### -r | --require lib

Requires the library before executing the script.  This option is compatible
with Ruby's.

#### -t | --trace

Turns on line tracing. Running `byebug --trace <rubyscript>.rb` is pretty much
like running `ruby -rtracer <rubyscript>.rb`. If all you want to do however is
get a line trace, `tracer` is most likely faster than `byebug`.

```console
$ time byebug --trace --no-stop hanoi.rb > /dev/null

real 0m0.743s
user 0m0.668s
sys  0m0.068s
$ time ruby -rtracer hanoi.rb > /dev/null

real 0m0.077s
user 0m0.072s
sys  0m0.004s
```

### Byebug default options

Byebug has many command-line options,; it seems that some people want to set
them differently from the defaults. For example, some people may want
`--no-quit` to be the default behavior. One could write a wrapper script or set
a shell alias to handle this.

### Command Files

A command file is a file of lines that are `byebug` commands. Comments (lines
starting with `#`) may also be included. An empty line in a command file does
nothing; it does not mean to repeat the last command, as it would from the
terminal.

When you start `byebug`, it automatically executes commands from its
_init file_, called `.byebugrc`. During startup, `byebug` does the following:

* __Processes command line options and operands.__ Reads the init file in your
  current directory, if any, and then checks your home directory. The home
  directory is the directory named in the `$HOME` or `$HOMEPATH` environment
  variable. Thus, you can have more than one init file, one generic in your home
  directory, and another, specific to the program you are debugging, in the
  directory where you invoke `byebug`.

You can also request the execution of a command file with the `source` command
(see [Source]()).

### Quitting byebug

To exit `byebug`, use the `quit` command (abbreviated to `q`). Normally, if you
are in an interactive session, this command will prompt to ask if you really
want to quit. If you want to quit without being prompted, enter `quit
unconditionally` (abbreviated to `q!`).

Another way to terminate byebug is to use the `kill` command. This does the
more forceful `kill -9`. It can be used in cases where `quit` doesn't work (I
haven't seen those yet).

### Calling byebug from inside your program

Running a program from byebug adds a bit of overhead and slows it down a little.
Furthermore, by necessity, debuggers change the operation of the program they
are debugging. And this can lead to unexpected and unwanted differences. It has
happened so often that the term
[Heisenbugs](https://en.wikipedia.org/wiki/Heisenbug) was coined to describe the
situation where using a debugger (among other possibilities) changes the
behavior of the program so that the bug doesn't manifest itself anymore.

There is another way to get into byebug which adds no overhead or slowdown until
you reach the point at which you want to start debugging. However here you must
change the script and make an explicit call to byebug. Because byebug isn't
involved before the first call, there is no overhead and the script will run
at the same speed as if there were no byebug.

To enter byebug this way, just drop `byebug` in whichever line you want to start
debugging at. You also have to require byebug somehow. If using bundler, it will
take care of that for you, otherwise you can use the ruby `-r` flag or add
`require "byebug"` in the line previous to the `byebug` call.

If speed is crucial, you may want to start and stop this around certain sections
of code, using `Byebug.start` and `Byebug.stop`. Alternatively, instead of
issuing an explicit `Byebug.stop` you can add a block to the `Byebug.start` and
debugging is turned on for that block. If the block of code raises an uncaught
exception that would cause the block to terminate, the `stop` will occur.  See
[Byebug.start with a block]().

When `byebug`is run, `.byebugrc` is read.

You may want to enter byebug at several points in the program where there is a
problem you want to investigate. And since `byebug` is just a method call it's
possible to enclose it in a conditional expression, for example

```ruby
byebug if "bar" == foo and 20 == iter_count
```

### Restarting Byebug

You can restart the program using `restart [program args]`. This is a re-exec -
all byebug state is lost. If command arguments are passed, those are used.
Otherwise program arguments from the last invocation are used.

You won't be able to restart your program in all cases. First, the program
should have been invoked at the outset rather than having been called from
inside your program or invoked as a result of post-mortem handling.

Also, since this relies on the OS `exec` call, this command is available only if
your OS supports `exec`.

## Debugging remote programs

It is possible to set up debugging so that you can issue byebug commands from
outside the process running the Ruby code. In fact, you might even be on a
different computer than the one running the Ruby program.

To setup remote debugging, drop the following somewhere before the point in the
program that you want to debug (In Rails, the
`config/environments/development.rb` could be a good candidate).

```ruby
require "byebug/core"
Byebug.wait_connection = true
Byebug.start_server("localhost", <port>)
```

Once this piece gets executed, you can connect to the remote debugger from your
local machine, by running: `byebug -R localhost:<port>`.

Next, at a place of program execution which gets run just before the code you
want to debug, add a call to `byebug` as was done without remote execution:

```ruby
# work, work, work...
byebug
some ruby code  # byebug will stop before this line is run
```

## Byebug Command Reference

### Command Syntax

Usually a command is put on a single line. There is no limit on how long it can
be. It starts with a command name, which is followed by arguments whose meaning
depends on the command name. For example, the command `step` accepts an
argument which is the number of times to step, as in `step 5`. You can also use
the `step` command with no arguments. Some commands do not allow any arguments.

Multiple commands can be put on a line by separating each with a semicolon `;`.
You can disable the meaning of a semicolon to separate commands by escaping it
with a backslash.

For example, you might want to enter the following code to compute the 5th
Fibonacci number.

```console
(byebug) fib1=0; fib2=1; 5.times {|temp| temp=fib1; fib1=fib2; fib2 += temp }
0
1
SyntaxError Exception: /home/davidr/Proyectos/sample_app/trace.rb:1: syntax
error, unexpected end-of-input, expecting '}'
 5.times { |temp| temp=fib1
                           ^
nil
1
SyntaxError Exception: /home/davidr/Proyectos/sample_app/trace.rb:1: syntax
error, unexpected tSTRING_DEND, expecting end-of-input
 fib2 += temp }
               ^
nil
(byebug) fib1=0\; fib2=1\; 5.times {|temp| temp=fib1\; fib1=fib2\; fib2 += temp }
5
(byebug) fib2
8
```

You might also consider using the [irb]() or [pry]() commands and then you
won't have to escape semicolons.

A blank line as input (typing just `<RET>`) means to repeat the previous
command.

Byebug uses readline, which handles line editing and retrieval of previous
commands. Up arrow, for example, moves to the previous byebug command; down
arrow moves to the next more recent command (provided you are not already at
the last command). Command history is saved in file `.byebug_history`. A limit
is put on the history size. You can see this with the `show history size`
command. See [history]() for history parameters.

### Command Output

In the command-line interface, when `byebug` is waiting for input it presents a
prompt of the form `(byebug)`. If the program has terminated normally the prompt
will be `(byebug:ctrl)` and in post-mortem debugging it will be
`(byebug:post-mortem)`.

Whenever `byebug` gives an error message such as for an invalid command or an
invalid location position, it will generally preface the message with `***`.

### Command Help

Once inside `byebug` you can always ask it for information on its commands using
the `help` command. You can use `help` (abbreviated `h`) with no arguments to
display a short list of named classes of commands

```console
(byebug) help

  break      -- Sets breakpoints in the source code
  catch      -- Handles exception catchpoints
  condition  -- Sets conditions on breakpoints
  continue   -- Runs until program ends, hits a breakpoint or reaches a line
  delete     -- Deletes breakpoints
  disable    -- Disables breakpoints or displays
  display    -- Evaluates expressions every time the debugger stops
  down       -- Moves to a lower frame in the stack trace
  edit       -- Edits source files
  enable     -- Enables breakpoints or displays
  finish     -- Runs the program until frame returns
  frame      -- Moves to a frame in the call stack
  help       -- Helps you using byebug
  history    -- Shows byebug's history of commands
  info       -- Shows several informations about the program being debugged
  interrupt  -- Interrupts the program
  irb        -- Starts an IRB session
  kill       -- Sends a signal to the current process
  list       -- Lists lines of source code
  method     -- Shows methods of an object, class or module
  next       -- Runs one or more lines of code
  pry        -- Starts a Pry session
  quit       -- Exits byebug
  restart    -- Restarts the debugged program
  save       -- Saves current byebug session to a file
  set        -- Modifies byebug settings
  show       -- Shows byebug settings
  skip       -- Runs until the next breakpoint as long as it is different from the current one
  source     -- Restores a previously saved byebug session
  step       -- Steps into blocks or methods one or more times
  thread     -- Commands to manipulate threads
  tracevar   -- Enables tracing of a global variable
  undisplay  -- Stops displaying all or some expressions when program stops
  untracevar -- Stops tracing a global variable
  up         -- Moves to a higher frame in the stack trace
  var        -- Shows variables and its values
  where      -- Displays the backtrace

```

With a command name, `help` displays information on how to use the command.

```console
(byebug) help list

  l[ist][[-=]][ nn-mm]

  Lists lines of source code

  Lists lines forward from current line or from the place where code was
  last listed. If "list-" is specified, lists backwards instead. If
  "list=" is specified, lists from current line regardless of where code
  was last listed. A line range can also be specified to list specific
  sections of code.
(byebug)
```

A number of commands, namely `info`, `set`, `show`, `enable` and `disable`, have
many sub-parameters or _subcommands_. When you ask for help for one of these
commands, you will get help for all of the subcommands that command offers.
Sometimes you may want help only on a subcommand and to do this just follow the
command with its subcommand name. For example, `help info breakpoints`will just
give help about the `info breakpoints` command. Furthermore it will give longer
help than the summary information that appears when you ask for help. You don't
need to list the full subcommand name, just enough of the letters to make that
subcommand distinct from others will do. For example, `help info b` is the same
as `help info breakpoints`.

Some examples follow.

```console
(byebug) help info
info[ subcommand]

Generic command for showing things about the program being debugged.

--
List of "info" subcommands:
--
info args        -- Argument variables of current stack frame
info breakpoints -- Status of user-settable breakpoints
info catch       -- Exceptions that can be caught in the current stack frame
info display     -- Expressions to display when program stops
info file        -- Info about a particular file read in
info files       -- File names and timestamps of files read in
info line        -- Line number and filename of current position in source file
info program     -- Execution status of the program
```

```console
(byebug) help info breakpoints
Status of user-settable breakpoints.
Without argument, list info about all breakpoints.
With an integer argument, list info on that breakpoint.
```

```console
(byebug) help info b
Status of user-settable breakpoints.
Without argument, list info about all breakpoints.
With an integer argument, list info on that breakpoint.
```

### Control Commands: quit, restart, source

#### Quit

To exit `byebug`, type `quit` (abbreviated to `q`). Normally, if you are in an
interactive session, this command will prompt you to confirm you really want to
quit. If you want to quit without being prompted, enter `quit unconditionally`
(abbreviated to `q!`).

#### Restart

To restart the program, use the `restart|r` command. This is a re-exec - all
`byebug` state is lost. If command arguments are passed, those are used.
Otherwise program arguments from the last invocation are used.

You won't be able to restart your program in all cases. First, the program
should have been invoked at the outset rather than having been called from
inside your program or invoked as a result of post-mortem handling.

#### Source

You can run `byebug` commands inside a file, using the command `source <file>`.
The lines in a command file are executed sequentially. They are not printed as
they are executed. If there is an error, execution proceeds to the next command
in the file. For information about command files that get run automatically on
startup see [Command Files]().

### Display Commands: display, undisplay

#### Display

If you find that you want to print the value of an expression frequently (to see
how it changes), you might want to add it to the *automatic display list** so
that `byebug` evaluates it each time your program stops or after a line is
printed if line tracing is enabled. Each expression added to the list is given a
number to identify it; to remove an expression from the list, you specify that
number. The automatic display looks like this:

```console
(byebug) display n
1: n = 3
```

This display shows item numbers, expressions and their current values. If the
expression is undefined or illegal the expression will be printed but no value
will appear.

```console
(byebug) display undefined_variable
2: undefined_variable =
(byebug) display 1/0
3: 1/0 =
```

If you use `display` with no argument, `byebug` will display the current values
of the expressions in the list, just as it is done when your program stops.
Using `info display` has the same effect.

#### Undisplay

To remove an item from the list, use `undisplay` followed by the number
identifying the expression you want to remove. `undisplay` does not repeat if
you press `<RET>`after using it (otherwise you would just get the error _No
display number n_)

You can also temporarily disable or enable display expressions, so that the will
not be printed but they won't be forgotten either, so you can toggle them again
later. To do that, use `disable display` or `enable display` followed by the
expression number.

### Evaluation of expressions: irb, pry

To examine and change data in your script you can just evaluate any Ruby code
from `byebug`'s prompt. Any input that is not recognized as a command will be
evaluated, so `byebug` essentially works as a REPL. If you want to evaluate
something that conflicts with a `byebug` command, just use Ruby's `eval`. For
example, if you want to print a variable called `n`, type `eval n` because
typing just `n` will execute `byebug`'s command `next`.

Finally, if you need more advanced functionality from REPL's, you can enter
`irb` or `pry` using `irb` or `pry` commands. The binding's environment will be
set to the current state in the program.  When you leave the repl and go back to
`byebug`'s command prompt we show the file, line and text position of the
program. If you issue a `list` without location information, the default
location used is the current line rather than the current position that may have
got updated via a prior `list` command.

```console
$ byebug triangle.rb
[1, 10] in /path/to/triangle.rb
    1: # Compute the n'th triangle number, the hard way: 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: if __FILE__ == $0
(byebug) irb
irb(main):001:0> (0..6).inject { |sum, i| sum += i }
 => 21
irb(main):002:0> exit
(byebug)
```

### Printing variables: var

Byebug can print many different information about variables. Such as

* `var const <object>`. Show the constants of `<object>`. This is basically
  listing variables and their values in `<object>.constant`.
* `var instance <object>`. Show the instance variables of `<object>`. This is
  basically listing `<object>.instance_variables`.
* `var instance`. Show instance_variables of `self`.
* `var local`. Show local variables.
* `var global`. Show global variables.
* `var all`. Show local, global and instance and class variables of `self`.
* `method instance <object>`. Show methods of `<object>`. Basically this is the
  same as running `<object>.instance_methods(false)`.
* `method <class-or-module>`. Show methods of the class or module
  `<class-or-module>`. Basically this is the same as running
  `<class-or-module>.methods`.

### Examining Program Source Files: list

`byebug` can print parts of your script's source.  When your script stops,
`byebug` spontaneously lists the source code around the line where it stopped
that line. It does that when you change the current stack frame as well.
Implicitly there is a default line location. Each time a list command is run
that implicit location is updated, so that running several list commands in
succession shows a contiguous block of program text.

If you don't need code context displayed every time, you can issue the `set
noautolist` command. Now whenever you want code listed, you can explicitly issue
the `list` command or its abbreviation `l`. Notice that when a second listing is
displayed, we continue listing from the place we last left off. When the
beginning or end of the file is reached, the line range to be shown is adjusted
so "it doesn't overflow". You can set the `noautolist` option by default by
dropping `set noautolist` in byebug's startup file `.byebugrc`.

If you want to set how many lines to be printed by default rather than use the
initial number of lines, 10, use the `set listsize` command ([listsize()). To
see the entire program in one shot, give an explicit starting and ending line
number. You can print other portions of source files by giving explicit position
as a parameter to the list command.

There are several ways to specify what part of the file you want to print. `list
nnn` prints lines centered around line number `nnn` in the current source file.
`l` prints more lines, following the last lines printed. `list -` prints lines
just before the lines last printed. `list nnn-mmm` prints lines between `nnn`
and `mmm` inclusive. `list =` prints lines centered around where the script is
stopped. Repeating a `list` command with `RET` discards the argument, so it is
equivalent to typing just `list`.  This is more useful than listing the same
lines again. An exception is made for an argument of `-`: that argument is
preserved in repetition so that each repetition moves up in the source file.

### Editing Source files: edit

To edit a source file, use the `edit` command.  The editor of your choice is invoked
with the current line set to the active line in the program. Alternatively, you can
give a line specification to specify what part of the file you want to edit.

You can customize `byebug` to use any editor you want by using the `EDITOR`
environment variable. The only restriction is that your editor (say `ex`) recognizes
the following command-line syntax:

```bash
ex +nnn file
```

The optional numeric value `+nnn` specifies the line number in the file where
you want to start editing. For example, to configure `byebug` to use the `vi` editor,
you could use these commands with the `sh` shell:

```bash
EDITOR=/usr/bin/vi
export EDITOR
byebug ...
```

or in the `csh` shell,

```bash
setenv EDITOR /usr/bin/vi
byebug ...
```

### The stack trace

When your script has stopped, one thing you'll probably want to know is where
it stopped and some idea of how it got there.

Each time your script calls a method or enters a block, information about this
action is saved. This information is what we call a _stack frame_ or just a
_frame_. The set of all frames at a certain point in the program's execution is
called the _stack trace_ or just the _stack_. Each frame contains a line number
and the source-file name that the line refers to. If the frame is the beginning
of a method it also contains the method name.

When your script is started, the stack has only one frame, that of the `main`
method. This is called the _initial frame_ or the _outermost frame_. Each time
a method is called, a new frame is added to the stack trace. Each time a method
returns, the frame for that method invocation is removed. If a method is
recursive, there can be many frames for the same method. The frame for the
method in which execution is actually occurring is called the _innermost
frame_. This is the most recently created of all the stack frames that still
exist.

Every time the debugger stops, one entry in the stack is selected as the
current frame. Many byebug commands refer implicitly to the selected block. In
particular, whenever you ask Byebug to list lines without giving a line number
or location the value is found in the selected frame. There are special
commands to select whichever frame you're interested in, such as `up`, `down`
and `frame`.

After switching frames, when you issue a `list` command without any position
information, the position used is the location in the frame that you just
switched between, rather than a location that got updated via a prior `list`
command.

Byebug assigns numbers to all existing stack frames, starting with zero for the
_innermost frame_, one for the frame that called it, and so on upward. These
numbers do not really exist in your script, they are assigned by Byebug to give
you a way of designating stack frames in commands.

### Printing the Stack: `where` command

The command `where`, aliased to `bt` or `backtrace` prints the call stack., It
shows one line per frame, for many frames, starting with the place that you are
stopped at (frame zero), followed by its caller (frame one), and on up the
stack. Each frame is numbered and can be referred to in the `frame` command.
The position of the current frame is marked with `-->`.

The are some special frames generated for methods that are implemented in C.
One such method is `each`. They are marked differently in the call stack to
indicate that we cannot switch to those frames. This is because they have no
source code in Ruby, so we can not debug them using Byebug.

```console
(byebug) where
--> #0 Object.gcd(a#Fixnum, b#Fixnum) at line gcd.rb:6
    #1 at line gcd.rb:19
```

### Selecting a frame: `up`, `down` and `frame` commands

* `up <n>`: Move `n` frames up the stack, towards the outermost frame (higher
  frame numbers, frames that have existed longer). `n` defaults to one.

* `down <n>`: Move `n` frames down the stack, towards the _innermost frame_
  (lower frame numbers, frames that were created more recently). `n` defaults to
  one.

* `frame <n>`: Allows you to move to an arbitrary frame. `n` is the stack frame
  number or 0 if no frame number is given. `frame 0` will show the current and
  most recent stack frame. If a negative number is given, counting is from the
  other end of the stack frame, so `frame -1` shows the least-recent, outermost
  stack frame. Without an argument, `frame` prints the current stack frame.