This post demonstrates Julia’s Debugger through some simple examples.

Introduction

Learning how to use a debugger was an important milestone in my growth as a programmer. I thought I was doing fine without it, but I just didn’t know what I was missing. A debugger allows you to stop a program in the middle of execution and interact directly with the software that you’ve written. Debuggers validate your mental model of the program you’ve written, and your model of the language itself. Duncan Temple Lang once remarked, “before you learn anything in a new programming language, you should learn the debugger.” I’m taking his advice.

What follows is a brief, self contained, introduction to Julia’s debugger. You may also enjoy Norm Matloff’s general resources on debugging.

Stepping Through a Program

We start by loading Debugger and defining a simple function, f.

using Debugger

f = function(x, y = 2)
    z = 3
    x + y + z
end

We can enter the debugger by prefacing a function call with the aptly named macro @enter.

@enter f(1)

The debugger displays the following output.

In #1(x, y) at REPL[1]:1
 1  f = function(x, y = 2)
 2      z = 3
>3      x + y + z
 4  en

About to run: (+)(1, 2, 3)
1|debug>

This means that the current program state is paused inside the call f(1). The > symbol in front of line 3 means the debugger is ready to run line 3: x + y + z. The prompt has changed to 1|debug>, since we are in the debugger, not the Julia REPL.

From the debug prompt, we can enter any valid Debugger commands. Type ? followed by enter to see the possible commands.

1|debug> ?
  Debugger commands
  ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡

  Below, square brackets denote optional arguments.

  Misc:
  - o: open the current line in an editor
  - q: quit the debugger, returning nothing
  ... (and many more)

Let’s start by looking at the variables in our current frame. These are the local variables inside the function. We expect to see x, y, z bound to 1, 2, 3.

1|debug> fr
[1] #1(x, y) at REPL[1]:1
  | x::Int64 = 1
  | y::Int64 = 2
  | z::Int64 = 3

Indeed they are. To evaluate any Julia expression, we type ` (a backtick) and Debugger gives us a Julia prompt. We can call functions on the local variables based on their current state in the function execution.

1|julia> 2*x
2

We can also manipulate the state of the computation. Suppose we would like to see what happens in the rest of the function if x = 2.0.

1|julia> x = 2.0
2.0

Type Ctrl+C to exit the Julia prompt and return to the debug prompt.

1|julia> ^C

1|debug>

Inspecting the variables in our current frame shows the new value for x.

1|debug> fr
[1] #1(x, y) at REPL[1]:1
  | x::Float64 = 2.0
  | y::Int64 = 2
  | z::Int64 = 3

n steps to the next line in the function body, which is the implicit return statement. The call returns 2.0 + 2 + 3 = 7.0.

1|debug> n
In #1(x, y) at REPL[1]:1
 1  f = function(x, y = 2)
 2      z = 3
>3      x + y + z
 4  en

About to run: return 7.0

c continues execution until a breakpoint is hit. We didn’t add any breakpoints, and we’re already at the return statement anyways, so the call returns and we exit the debugger, returning to the main Julia REPL.

1|debug> c
7.0

julia>

That’s it for the basic introduction. The next example contains an actual bug.

Stopping on Error

It’s often useful to stop and enter the debugger when an error occurs, so we can examine the state of the program under the exact conditions that produced the error. We do this with Debugger by calling break_on(:error), then @run in front of the expression that produces the error. Hopefully, this investigation will lead us to the root cause.

The following code calculates and prints 2*3 + 4, but it contains two bugs.

axpy1 = function(a, x, y)
    ax + y
end

f1 = function()
    a = 2
    x = 3
    y = 4
    println("If a = $a, x = $x, y = $y, then ax + y = $(axpy1(x, y, a))")
end

When we call f1(), we see the following error message:

julia> f1()
ERROR: UndefVarError: ax not defined
Stacktrace:
 [1] (::var"#5#6")(::Int64, ::Int64, ::Int64) at ./REPL[45]:2
 [2] (::var"#9#10")() at ./REPL[48]:5
 [3] top-level scope at REPL[49]:1

We don’t need debugging to fix this error. This error message tells us exactly what the problem is: we never defined the variable ax. Our program is simple, and the stack trace only contains three frames, so if we have the correct mental model of how the language works, then we can reason through it to fix the error.

Debugging becomes truly useful when the problem is not obvious. The error message may be uninformative, the program may be complex, and the stack trace may contain more frames than you can fit in your head. If you hit an error, and you don’t know what’s wrong, then run the same code through the debugger, as follows.

julia> break_on(:error)

julia> @run f1()
Breaking for error:
ERROR: UndefVarError: ax not defined
Stacktrace:
 [1] (::var"#11#12")(::Int64, ::Int64, ::Int64) at REPL[52]:2
 [2] (::var"#13#14")() at REPL[53]:5

In #11(a, x, y) at REPL[52]:1
 1  axpy1 = function(a, x, y)
>2      ax + y
 3  en

About to run: (+)(Main.ax, 2)
1|debug>

We are now in the debugger prompt, inside the call to axpy1(), so we can enter any of the debugger commands. The error message said variable ax is not present. What variables are present? Let’s see.

1|debug> fr
[1] #11(a, x, y) at REPL[52]:1
  | a::Int64 = 3
  | x::Int64 = 4
  | y::Int64 = 2

We have a, x, and y, but no ax. Ah, of course: we should have written a*x instead of ax. Let’s fix this bug:

axpy2 = function(a, x, y)
    a*x + y
end

f2 = function()
    a = 2
    x = 3
    y = 4
    println("If a = $a, x = $x, y = $y, then ax + y = $(axpy2(x, y, a))")
end

We call it as follows:

julia> f2()
If a = 2, x = 3, y = 4, then ax + y = 14

That’s not right. 2 * 3 + 4 = 10, not 14. This is an altogether more troubling class of bug: one that executes perfectly fine, but produces the wrong answer. 😭 break_on(:error) doesn’t help us here, because there is no error to break on. Let’s use another debugging technique, breakpoints, to find what went wrong.

Setting Breakpoints

Breakpoints tell the debugger to stop executing code, and instead drop you into an interactive debugger prompt so that you can look around.

One simple way to add a breakpoint is to add the macro @bp to the line of the source code where you want to stop and examine the state. Let’s add @bp inside of the axpy function, which makes this equivalent to debugging when the axpy function is called. In practice, you might add @bp deep in a loop in a conditional branch, so it only enters the debugger in the one case you’re interested in.

axpy3 = function(a, x, y)
    @bp
    a*x + y
end

f3 = function()
    a = 2
    x = 3
    y = 4
    println("If a = $a, x = $x, y = $y, then ax + y = $(axpy3(x, y, a))")
end

If we run this code normally, then it behaves as before. In particular, leaving @bp in the code does not cause Julia to enter the debugger.

julia> f3()
If a = 2, x = 3, y = 4, then ax + y = 14

To stop at the break point and enter the debugger, we need to preface the code with @run.

julia> @run f3()
Hit breakpoint:
In #23(a, x, y) at REPL[62]:1
 1  axpy3 = function(a, x, y)
●2      @bp
>3      a*x + y
 4  en

About to run: (*)(3, 4)
1|debug>

We hit the breakpoint that we added inside the definition of axpy3, so we’re now back in the debugger. ●2 indicates the breakpoint we hit on the second line, and >3 indicates the next line to run. Let’s look at the variables in our current frame, the call to axpy3.

1|debug> fr
[1] #23(a, x, y) at REPL[62]:1
  | a::Int64 = 3
  | x::Int64 = 4
  | y::Int64 = 2

Fine, a, x, and y are all defined and nothing looks too terribly wrong. Debugger allows us to step up the call stack, into the parent frame of the call to axpy3() where we encountered the breakpoint. The command is up.

1|debug> up
In #25() at REPL[63]:1
 1  f3 = function()
 2      a = 2
 3      x = 3
 4      y = 4
>5      println("If a = $a, x = $x, y = $y, then ax + y = $(axpy3(x, y, a))")
 6  en

About to run: (var"#23#24"())(3, 4, 2)
2|debug>

We are inside the call to f3(), which called axpy3(). In addition, the prompt changed to 2|debug>, indicating that we are on frame 2. Let’s probe the state of the evaluation.

2|debug> fr
[2] #25() at REPL[63]:1
  | a::Int64 = 2
  | x::Int64 = 3
  | y::Int64 = 4

In this frame, we still have the same variables a, x, and y, but because of Julia’s lexical scoping rules they’re not the same as the a, x, and y in frame 1. Press ` (literal backtick) to enter the Julia REPL where can evaluate our axpy3 function in the frame where it appeared to have a problem:

2|julia>

2|julia> axpy3(a, x, y)
10

2 * 3 + 4 = 10, so our axpy3 function works just fine. The bug lies in f3, where we call axpy3(x, y, a) with the arguments in the wrong order. Type ^C followed by q to get back to the main Julia REPL.

Maybe it wasn’t the best idea to bury our call to axpy3 inside this string interpolation. Let’s fix the bug.

axpy4 = function(a, x, y)
    a*x + y
end

f4 = function()
    a = 2
    x = 3
    y = 4
    z = axpy4(a, x, y)
    println("If a = $a, x = $x, y = $y, then ax + y = $z")
end

Does it work?

julia> f4()
If a = 2, x = 3, y = 4, then ax + y = 10

Problem solved.

Conclusion

This post highlighted only a couple of Debugger’s rich set of capabilities. You can add a breakpoint when a function is called, when a particular method is called, when a condition is satisfied, or to an arbitrary line in a file. You can toggle breakpoints on and off, and generally control entire sequence of breakpoints. We didn’t even talk about watching expressions, editing code on the fly, or more sophisticated stepping.

Debuggers are one of those peripheral skills that take a little time and effort to learn, so it’s easy to put it off. Don’t. Debuggers save time by allowing you to quickly pinpoint problems. They also strengthen your mental model, for any language, by allowing you to constantly test, explore, and verify what you believe to be true.