diff options
author | Chris Perkins <chrisperkins99@gmail.com> | 2016-04-15 11:11:53 -0600 |
---|---|---|
committer | Chris Perkins <chrisperkins99@gmail.com> | 2016-04-15 13:30:24 -0600 |
commit | ac74a443ac1ad364dcf3d14e4b4ea455bc596ec3 (patch) | |
tree | 0d1aaf4d7895df972b8c332031c5fab692e859d2 /doc | |
parent | 855a7f456baf57d47fdd9b67428c7331b4e9b6b5 (diff) |
More documentation for the debugger
Diffstat (limited to 'doc')
-rw-r--r-- | doc/debugging.md | 93 |
1 files changed, 86 insertions, 7 deletions
diff --git a/doc/debugging.md b/doc/debugging.md index b8b810cf..2a9e96b8 100644 --- a/doc/debugging.md +++ b/doc/debugging.md @@ -7,7 +7,7 @@ CIDER ships with a powerful interactive Clojure debugger inspired by Emacs's own The debugger can be invoked in several ways, the simplest one is to type <kbd>C-u C-M-x</kbd>. This will take the current top-level form, place as many -breakpoints inside it as possible (instrument it), and then evaluate it a +breakpoints inside it as possible (instrument it), and then evaluate it as normal. Whenever a breakpoint is reached, you'll be shown the value and asked for input (see below). Note that if the current form is a `defn`, it will stay instrumented, so the debugger will be triggered every time the function is @@ -39,26 +39,105 @@ instrumented as well, but they will not be listed by this command. ## Keys -`cider-debug` tries to be consistent with -[Edebug][]. So -it makes available the following bindings while stepping through code. +`cider-debug` tries to be consistent with [Edebug][], although there are some +differences. It makes available the following bindings while stepping through +code. Keyboard shortcut | Description --------------------------------|------------------------------- <kbd>n</kbd> | Next step +<kbd>i</kbd> | Step in to a function +<kbd>o</kbd> | Step out of the current sexp (like `up-list`) +<kbd>O</kbd> | Force-step out of the current sexp +<kbd>h</kbd> | Skip all sexps up to “here” (current position). Move the cursor before doing this. +<kbd>H</kbd> | Force-step to “here” <kbd>c</kbd> | Continue without stopping -<kbd>o</kbd> | Move out of the current sexp (like `up-list`) -<kbd>i</kbd> | Inject a value into running code <kbd>e</kbd> | Eval code in current context +<kbd>p</kbd> | Inspect a value <kbd>l</kbd> | Inspect local variables +<kbd>j</kbd> | Inject a value into running code <kbd>s</kbd> | Show the current stack -<kbd>h</kbd> | Skip all sexps up to “here” (current position). Move the cursor before doing this. +<kbd>t</kbd> | Trace. Continue, printing expressions and their values. <kbd>q</kbd> | Quit execution In addition, all the usual evaluation commands (such as <kbd>C-x C-e</kbd> or <kbd>C-c M-:</kbd>) will use the current lexical context (local variables) while the debugger is active. +## Command Details + +Here are some more details about what each of the above commands does. + +### Stepping Commands + +These commands continue execution until reaching a breakpoint. + +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`). Not every form is wrapped in a +breakpoint; the debugger tries to avoid setting breakpoints on expressions that +would not be interesting to stop at, such as constants. For example, there would +not be much point in stopping execution at a literal number 23 in your code and +showing that its value is 23 - you already know that. + +- **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, skipping all breakpoints. + +### Other Commands + +- **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**: 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. + +```clojure +(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 +is 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`. + ## Internal Details *This section explains a bit of the inner workings of the debugger. It is mostly |