Debugger

CIDER ships with a powerful interactive Clojure debugger inspired by Emacs’s own Edebug. You’re going to love it!

The debugger currently does not support ClojureScript. See this issue for more details.

Using the Debugger

During normal CIDER development, it’s common for a programmer to evaluate a form, often a function definition, by typing C-M-x (cider-eval-defun-at-point). CIDER can also instrument a form for debugging when you add a prefix to the evaluation command: C-u C-M-x. During the instrumentation process, CIDER will insert as many breakpoints as possible into the form. Whenever execution reaches a breakpoint, CIDER will drop into debugging mode and will prompt you for what to do next. You can remove the instrumentation by evaluating the form again normally, using C-M-x.

You can also insert a breakpoint manually into any code by placing #break in front of the form where you want the breakpoint to trigger and then evaluating the form with C-M-x. When execution reaches the form after the #break, you’ll be dropped into the debugger.

For instance, if you hit C-M-x on the following, a breakpoint is triggered every time (inspector msg) is evaluated.

(defn eval-msg [{:keys [inspect] :as msg}]
  (if inspect
    #break (inspector msg)
    msg))

Instead of #break, you can also write #dbg before a form. This will place a breakpoint both in front of the form, as with #break, and also everything inside it. In the example above, this places one breakpoint around (inspector msg) and another around msg. In fact, typing C-u C-M-x to instrument a top-level form is just a convenient way to evaluate the form with an implicit #dbg in front of it; the behavior is the same.

At any point, you can bring up a list of all currently instrumented defs with the command M-x cider-browse-instrumented-defs. Protocols and types can be instrumented as well, but they will not be listed by this command.

Understanding Breakpoints

In the CIDER debugger, the term "breakpoint" refers to a place where the debugger can halt execution and display the value of an expression. You can set a single breakpoint with #break, or set breakpoints throughout a form with #dbg (or by evaluating with C-u C-M-x), as described previously.

When using #dbg or C-u C-M-x, not every form is wrapped in a breakpoint. The debugger tries to avoid setting breakpoints on expressions that are not interesting. For example, there is little point in stopping execution at a literal number 23 in your code and showing you that its value is 23 - you already know that.

Keys

Once you drop into the CIDER debugger, you have a number of commands available to you to step through your code, evaluate other forms, inspect values, inject new values, or view the current stack. cider-debug tries to be consistent with Edebug command keys, although there are some differences.

Keyboard shortcut Description

Keyboard shortcut	Description
`n`	Next step
`i`	Step in to a function
`o`	Step out of the current sexp (like `up-list`)
`O`	Force-step out of the current sexp
`h`	Skip all sexps up to “here” (current position). Move the cursor before doing this.
`H`	Force-step to “here”
`c`	Continue without stopping in current breakpoint
`C`	Continue without stopping for all breakpoints
`e`	Eval code in current context
`p`	Inspect the current value
`P`	Inspect an arbitrary expression
`l`	Inspect local variables
`L`	Toggle display of local variables
`j`	Inject a value into running code
`s`	Show the current stack
`t`	Trace. Continue, printing expressions and their values.
`q`	Quit execution

n

Next step

i

Step in to a function

o

Step out of the current sexp (like up-list)

O

Force-step out of the current sexp

h

Skip all sexps up to “here” (current position). Move the cursor before doing this.

H

Force-step to “here”

c

Continue without stopping in current breakpoint

C

Continue without stopping for all breakpoints

e

Eval code in current context

p

Inspect the current value

P

Inspect an arbitrary expression

l

Inspect local variables

L

Toggle display of local variables

j

Inject a value into running code

s

Show the current stack

t

Trace. Continue, printing expressions and their values.

q

Quit execution

Additionally, all the usual evaluation commands such as C-x C-e or C-c M-: will be scoped to the current lexical context while the debugger is active, allowing you to access local variables.

Stepping Command Details

These commands continue execution until reaching a breakpoint.

next: Steps to the next breakpoint
in: Steps in to the function about to be called. If the next breakpoint is not around a function call, does the same as next. Note that not all functions can be stepped in to - only normal functions stored in vars, for which CIDER can find the source. You cannot currently step in to multimethods, protocol functions, or functions in clojure.core (although multimethods and protocols can be instrumented manually).
out: Steps to the next breakpoint that is outside of the current sexp.
Out: Same as o, but skips breakpoints in other functions. That is, if the code being skipped over contains a call to another instrumented function, the debugger will stop in that function if you step out with o, but not if you step out with O.
here: Place the point somewhere further on in the function being debugged, at the point where you want to stop next. Then press h, and the debugger will skip all breakpoints up until that spot.
Here: Same as h, but skips breakpoints in other functions, as with O.
continue: Continues without stopping for the current breakpoint.
continue-all: Continues without stopping, skipping all breakpoints.

Other Command Details

eval: Prompts for a clojure expression, which can reference local variables that are in scope where the debugger is stopped. Displays the result in an overlay.
inspect: Inspects the currently evaluated value in a cider-inspector buffer.
inspect-prompt: Like eval, but displays the value in a cider-inspector buffer.
locals: Opens a cider-inspector buffer displaying all local variables defined in the context where the debugger is stopped.
inject: Replaces the currently-displayed value with the value of an expression that you type in. Subsequent code will see the new value that you entered.
stacktrace: Shows the stacktrace of the point where the debugger is stopped.
trace: Continues execution, but at each breakpoint, instead of stopping and displaying the value in an overlay, prints the form and its value to the REPL.
quit: Quits execution immediately. Unlike with continue, the rest of the code in the debugged function is not executed.

Conditional Breakpoints

Breakpoints can be conditional, such that the debugger will only stop when the condition is true.

Conditions are specified using :break/when metadata attached to a form.

(dotimes [i 10]
  #dbg ^{:break/when (= i 7)}
  (prn i))

Evaluating the above with C-M-x, the debugger will stop only once, when i equals 7.

You can also have CIDER insert the break condition into your code for you. Place the point where you want the condition to go and evaluate with C-u C-u C-M-x or C-u C-u C-c C-c. CIDER will then prompt you for the condition in the minibuffer and insert the appropriate #dbg plus metadata annotation in your code. Note that you’ll have to delete this annotation by hand; you cannot simply use C-M-x as you can to un-instrument C-u C-M-x.

Caveats

Due to the way the debugger is currently implemented there are some limitations when it comes to certain forms. Set literals are currently not instrumented at all. Map literals are currently only instrumented if they are small or the keys have some natural order. For example the following expression won’t be instrumented.

#dbg (count {:foo 2 :bar (inc 4) "foo" 6 "bar" 8 9
             10 11 12 13 14 15 (inc 16) 17 (inc 18)})

Another construct where the debugger is currently limited is loop/recur. As recur always has to appear in a tail-position inside a loop or a fn and the debugger uses macros to interleave breakpoints in the forms it might happen that a recur no longer appears in a tail position. In that case we have to avoid setting up the breakpoint. An example of such a case is:

(loop [i 0]
  #break
  (when (< i 10)
    (println i)
    (recur (inc i))))

Here the breakpoint is exactly in front of a form that contains as last expression a recur which is not wrapped in a loop. Currently this breakpoint has no effect. This does not mean you can not use the debugger with loop, it just means you have to set your debug statements more carefully.

Debugger Internals

This section explains a bit of the inner workings of the debugger. It is intended to help those who are interested in contributing, and doesn’t teach anything about the debugger’s usage.

CIDER works in several steps as it instruments your code:

First, CIDER walks through the code, adding metadata to forms and symbols that identify their position (coordinate) in the code.
Then, it macroexpands everything to get rid of macros.
Then, it walks through the code again, instrumenting it.
- CIDER understands all existing special forms and takes care not to instrument where it’s not supposed to. For instance, CIDER does not instrument the arglist of fn* or the left-side of a let-binding.
- Wherever it finds the previously-injected metadata, assuming that location is valid for instrumentation, it wraps the form or symbol in a macro called breakpoint-if-interesting.
When the resulting code actually gets compiled, the Clojure compiler will expand the breakpoint-if-interesting macros. This macro decides whether the return value of the form or symbol is actually something the user might want to see. If it is, the form or symbol gets wrapped in a breakpoint macro, otherwise it’s returned as is.
The breakpoint macro takes the coordinate information that was provided in step 1. and sends it over to Emacs (the front-end). It also sends the return value of the form and a prompt of available commands. Emacs then uses this information to show the value of actual code forms and prompt for the next action.

A few example forms that don’t have interesting return values (and so are not wrapped in a breakpoint):

In (fn [x] (inc x)) the return value is a function object and carries no information. Note that this is not the same as the return value when you call this function (which is interesting). Also, even those this form is not wrapped in a breakpoint, the forms inside it are ((inc x) and x).
Similarly, in a form like (map inc (range 10)), the symbol inc points to a function in clojure.core. That’s also irrelevant (unless it’s being shadowed by a local, but the debugger can identify that).