CIDER
(formerly nrepl.el
) is the Clojure Interactive Development Environment that Rocks for Emacs, built on top of
nREPL, the Clojure networked
REPL server. It's a great alternative to the now deprecated combination
of SLIME + swank-clojure.
If you're interested in details about CIDER's history and architecture you can check out the Clojure/conj presentation The Evolution of the Emacs tooling for Clojure.
CIDER packs plenty of features. Here are some of them (in no particular order):
- Powerful REPL
- Interactive code evaluation
- Compilation notes (error and warning highlighting)
- Human-friendly stacktraces
- Smart code completion
- Definition lookup
- Documentation lookup
- Resource lookup
- Apropos
- Debugger
- Value inspector
- Function tracing
- Interactive macroexpansion
- Grimoire integration
clojure.test
integration- Classpath browser
- Namespace browser
- nREPL session management
- Scratchpad
- Minibuffer code evaluation
- Integration with company-mode and auto-complete-mode
- Installation
- CIDER nREPL middleware
- Configuration
- Basic Usage
- Keyboard shortcuts
- Requirements
- Caveats
- Troubleshooting
- Documentation
- Changelog
- Team
- Release policy
- Logo
- Contributing
- License
Installation
The canonical way to install CIDER is via package.el
, but plenty of other
options exist. (see wiki).
Prerequisites
You'll need to have Emacs installed (preferably the latest stable release). If you're new to Emacs you might want to read this tutorial, dedicated to setting up Emacs for Clojure development, first.
Upgrading from nrepl.el
Before installing CIDER make sure you've removed the old nrepl.el
package and all packages that depend on it. Use only packages updated to work with CIDER!
You'll also need to adjust your config accordingly, as most settings were renamed in CIDER. Consult the Configuration section of the README for more details.
Upgrading from clojure-test-mode
CIDER 0.7 ships a replacement for the deprecated clojure-test-mode
called cider-test
.
Please, make sure you've uninstalled clojure-test-mode
if you're using CIDER 0.7 as clojure-test-mode
sometimes interferes with CIDER's REPL initialization.
Installation via package.el
package.el
is the built-in package manager in Emacs.
CIDER
is available on all major package.el
community
maintained repos -
MELPA Stable,
MELPA and Marmalade.
You can install CIDER
with the following command:
M-x package-install [RET] cider [RET]
or by adding this bit of Emacs Lisp code to your Emacs initialization file
(.emacs
or init.el
):
(unless (package-installed-p 'cider)
(package-install 'cider))
If the installation doesn't work try refreshing the package list:
M-x package-refresh-contents [RET]
Keep in mind that MELPA packages are built automatically from
the master
branch, meaning bugs might creep in there from time to
time. Never-the-less, installing from MELPA is the recommended way of
obtaining CIDER, as the master
branch is normally quite stable and
"stable" (tagged) builds are released somewhat infrequently.
With the most recent builds of Emacs, you can pin CIDER to always use MELPA Stable (or Marmalade) by adding this to your Emacs initialization:
(add-to-list 'package-pinned-packages '(cider . "melpa-stable") t)
CIDER has deps (e.g. queue
) that are only available in the
GNU ELPA repository. It's the only repository enabled
by default and you should not disable it!
CIDER nREPL middleware
Using Leiningen
Much of CIDER's functionality depends on the presence of CIDER's own nREPL middleware.
Use the convenient plugin for defaults, either in your project's
project.clj
file or in the :user profile in ~/.lein/profiles.clj
.
:plugins [[cider/cider-nrepl "x.y.z"]]
A minimal profiles.clj
for CIDER would be:
{:user {:plugins [[cider/cider-nrepl "0.9.0"]]}}
Using Boot
Boot users can configure the tool to include the middleware automatically in
all of their projects using a ~/.boot/profile.boot
file like so:
(require 'boot.repl)
(swap! boot.repl/*default-dependencies*
concat '[[cider/cider-nrepl "0.9.0"]])
(swap! boot.repl/*default-middleware*
conj 'cider.nrepl/cider-middleware)
Using embedded nREPL server
If you're embedding nREPL in your application you'll have to start the server with CIDER's own nREPL handler.
(ns my-app
(:require [clojure.tools.nrepl.server :as nrepl-server]
[cider.nrepl :refer (cider-nrepl-handler)]))
(defn -main
[]
(nrepl-server/start-server :port 7888 :handler cider-nrepl-handler))
It goes without saying that your project should depend on cider-nrepl
.
x.y.z
should match the version of CIDER you're currently using (say 0.7.1
).
For snapshot releases of CIDER you should use the snapshot of the plugin as well
(say 0.7.1-SNAPSHOT
).
Note that you need to use at least CIDER 0.7 for the nREPL middleware to work properly. Don't use cider-nrepl with CIDER 0.6.
Configuration
You can certainly use CIDER
without configuring it any further,
but here are some ways other folks are adjusting their CIDER
experience.
Basic configuration
- Enable
eldoc
in Clojure buffers:
(add-hook 'cider-mode-hook #'eldoc-mode)
- Suppress auto-enabling of
cider-mode
inclojure-mode
buffers, when starting CIDER:
(setq cider-auto-mode nil)
By default CIDER will enable cider-mode
in all clojure-mode
buffers when the
first CIDER connection is established. It will also add a clojure-mode
hook to
enable it on newly created clojure-mode
buffers. The configuration snippet
above allows you to override this (somewhat non-standard) behavior.
- Log communication with the nREPL server (extremely useful for debugging CIDER problems):
(setq nrepl-log-messages t)
The log will go to the buffer *nrepl-messages*
.
- You can hide the
*nrepl-connection*
and*nrepl-server*
buffers from appearing in some buffer switching commands likeswitch-to-buffer
(C-x b) like this:
(setq nrepl-hide-special-buffers t)
When using switch-to-buffer
, pressing SPC after the command will
make the hidden buffers visible. They'll always be visible in
list-buffers
(C-x C-b).
-
By default, interactive commands that require a symbol will prompt for the symbol, with the prompt defaulting to the symbol at point. You can set
cider-prompt-for-symbol
to nil to instead try the command with the symbol at point first, and only prompt if that fails. -
You can control the TAB key behavior in the REPL via the
cider-repl-tab-command
variable. While the default commandcider-repl-indent-and-complete-symbol
should be an adequate choice for most users, it's very easy to switch to another command if you wish to. For instance if you'd like TAB to only indent (maybe because you're used to completing with M-TAB) use the following snippet:
(setq cider-repl-tab-command #'indent-for-tab-command)
- To prefer local resources to remote (tramp) ones when both are available:
(setq cider-prefer-local-resources t)
- Prevent the auto-display of the REPL buffer in a separate window after connection is established:
(setq cider-repl-pop-to-buffer-on-connect nil)
-
Configure whether the error buffer with stacktraces should be automatically shown on error:
-
Don't show on error:
(setq cider-show-error-buffer nil)
Independently of the value of
cider-show-error-buffer
, the error buffer is always generated in the background. Usecider-visit-error-buffer
to visit this buffer.-
Selective strategies:
(setq cider-show-error-buffer 'except-in-repl) ; or (setq cider-show-error-buffer 'only-in-repl)
-
-
To disable auto-selection of the error buffer when it's displayed:
(setq cider-auto-select-error-buffer nil)
- If using the
wrap-stacktrace
middleware fromcider-nrepl
, error buffer stacktraces may be filtered by default. Valid filter types includejava
,clj
,repl
,tooling
, anddup
. Setting this tonil
will show all stacktrace frames.
(setq cider-stacktrace-default-filters '(tooling dup))
- Error messages may be wrapped for readability. If this value is nil, messages
will not be wrapped; if it is truthy but non-numeric, the default
fill-column
will be used.
(setq cider-stacktrace-fill-column 80)
- The REPL buffer name has the format
*cider-repl project-name*
. Change the separator from space to something else by overridingnrepl-buffer-name-separator
.
(setq nrepl-buffer-name-separator "-")
- The REPL buffer name can also display the port on which the nREPL server is running. Buffer name will look like cider-repl project-name:port.
(setq nrepl-buffer-name-show-port t)
- Make C-c C-z switch to the CIDER REPL buffer in the current window:
(setq cider-repl-display-in-current-window t)
- Prevent C-c C-k from prompting to save the file corresponding to the buffer being loaded, if it's modified:
(setq cider-prompt-save-file-on-load nil)
- Change the result prefix for REPL evaluation (by default there's no prefix):
(setq cider-repl-result-prefix ";; => ")
And here's the result of that change:
user> (+ 1 2)
;; => 3
- Change the result prefix for interactive evaluation (by default it's
=>
):
(setq cider-interactive-eval-result-prefix ";; => ")
To remove the prefix altogether just set it to an empty string(""
).
- Normally code you input in the REPL is font-locked with
cider-repl-input-face
(after you pressRET
) and results are font-locked withcider-repl-result-face
. If you want them to be font-locked as inclojure-mode
use the following:
(setq cider-repl-use-clojure-font-lock t)
- You can control the C-c C-z key behavior of switching to the REPL buffer
with the
cider-switch-to-repl-command
variable. While the default commandcider-switch-to-relevant-repl-buffer
should be an adequate choice for most users,cider-switch-to-current-repl-buffer
offers a simpler alternative where CIDER will not attempt to match the correct REPL buffer based on underlying project directories:
(setq cider-switch-to-repl-command #'cider-switch-to-current-repl-buffer)
- You can configure known endpoints used by the cider command offered via a completing read. This is useful if you have a list of common host/ports you want to establish remote nREPL connections to. Using an optional label is helpful for identifying each host.
(setq cider-known-endpoints '(("host-a" "10.10.10.1" "7888") ("host-b" "7888")))
- If you are targeting the JVM and prefer a local copy of the JDK API documentation over Oracle's official copy (e.g., for JavaSE 8), per nREPL's
javadoc-info
logic (accurate as of 29 Dec 2014), you can arrange your project to include the root path of the local API doc (i.e., where theindex.html
is located) to be included on your classpath (i.e., where the doc HTML files can be located byclojure.java.io/resource
). For example, for Leiningen, with the local API path being/usr/share/doc/java/api/
, put the following line inproject.clj
:
:dev {:resource-paths ["/usr/share/doc/java/api/"]}
or the following line in $HOME/.lein/profiles.clj
:
:user {:resource-paths ["/usr/share/doc/java/api/"]}
More detail can be found here.
Running tests
-
If your tests are not following the
some.ns-test
naming convention you can customize the variablecider-test-infer-test-ns
. It should be bound to a function that takes the current ns and returns the matching test ns (which may be the same as the current ns). -
If you want to view the test report regardless of whether the tests have passed or failed:
(setq cider-test-show-report-on-success t)
REPL history
- To make the REPL history wrap around when its end is reached:
(setq cider-repl-wrap-history t)
- To adjust the maximum number of items kept in the REPL history:
(setq cider-repl-history-size 1000) ; the default is 500
- To store the REPL history in a file:
(setq cider-repl-history-file "path/to/file")
Note that the history is written to the file when you kill the REPL
buffer (which includes invoking cider-quit
) or you quit Emacs.
Minibuffer completion
Out-of-the box CIDER
uses the standard completing-read
Emacs mechanism. While it's not
fancy it certainly gets the job done (just press TAB
). There are, however, ways to improve
upon the standard completion if you wish to.
icomplete
icomplete
is bundled with Emacs and enhances the default minibuffer completion:
(require 'icomplete)
ido
ido
is also bundled with Emacs and offers more features than icomplete
.
If you are using ido
, be sure to use both ido-everywhere
and ido-ubiquitous
.
You might also want to install ido-flex
.
Auto-completion
CIDER
users are advised to use company-mode
to enable auto-completion
inside of source code and REPL buffers. This can be done globally, like so --
(global-company-mode)
-- or through mode-specific hooks:
(add-hook 'cider-repl-mode-hook #'company-mode)
(add-hook 'cider-mode-hook #'company-mode)
When company-mode
is thus enabled, it will receive completion information
from cider-complete-at-point
, and requires no additional setup or plugins.
auto-complete-mode
Migrating from -
Disable
ac-cider-setup
orac-nrepl-setup
from running onCIDER
hooks -
Remove
cider-mode
andcider-repl-mode
from theac-modes
list
Completion annotations
Completion candidates will be annotated by default with an abbreviation
corresponding to their type, and (contextually) their ns. The function used to
format the annotation can be configured by cider-annotate-completion-function.
The abbreviations used are configured by cider-completion-annotations-alist
and the context in which their namespace is included is configured by
cider-completion-annotations-include-ns.
Completion annotations can be disabled by setting
cider-annotate-completion-candidates
to nil.
Integration with other modes
- Enabling
CamelCase
support for editing commands(likeforward-word
,backward-word
, etc) in the REPL is quite useful since we often have to deal with Java class and method names. The built-in Emacs minor modesubword-mode
provides such functionality:
(add-hook 'cider-repl-mode-hook #'subword-mode)
- The use of paredit
when editing Clojure (or any other Lisp) code is highly
recommended. You're probably using it already in your
clojure-mode
buffers (if you're not you probably should). You might also want to enableparedit
in the REPL buffer as well:
(add-hook 'cider-repl-mode-hook #'paredit-mode)
- smartparens is an excellent
alternative to paredit. Many Clojure hackers have adopted it
recently and you might want to give it a try as well. To enable
smartparens
in the REPL buffer use the following code:
(add-hook 'cider-repl-mode-hook #'smartparens-strict-mode)
- RainbowDelimiters is a minor mode which highlights parentheses, brackets, and braces according to their depth. Each successive level is highlighted in a different color. This makes it easy to spot matching delimiters, orient yourself in the code, and tell which statements are at a given depth. Assuming you've already installed RainbowDelimiters you can enable it in the REPL like this:
(add-hook 'cider-repl-mode-hook #'rainbow-delimiters-mode)
-
auto-complete is a popular Emacs interactive auto-completion framework. ac-cider provides a completion source for auto-complete-mode, including, where CIDER provides it, pop-up documentation for completed symbols.
-
eval-sexp-fu provides some visual feedback when evaluating expressions. cider-eval-sexp-fu provides CIDER integration for
eval-sexp-fu
.
(require 'cider-eval-sexp-fu)
Basic Usage
The only requirement to use CIDER is to have a nREPL server to
which it may connect. Many Clojurians favour the use of the Leiningen or Boot tools
to start an nREPL server, but the use of Leiningen or Boot is not a prerequisite to use
CIDER (but it is required if you want to use the cider-jack-in
command).
Setting up a Leiningen or Boot project (optional)
Leiningen is the de facto standard build/project management tool for Clojure. Boot is a newer build tool offering abstractions and libraries to construct more complex build scenarios. Both have a similar scope to the Maven build tool favoured by Java developers (and they actually reuse many things from the Maven ecosystem).
CIDER features a command called cider-jack-in
that will start an nREPL server
for a particular Leiningen or Boot project and connect to it automatically.
This functionality depends on Leiningen 2.x (preferably 2.5+) or Boot
2.0.0+. Older versions are not supported. For Leiningen, follow the installation
instructions on its web site to get it up and running and afterwards create a
project like this:
$ lein new demo
The two main ways to obtain an nREPL connection are discussed in the following sections of the manual.
Launch a nREPL server and client from Emacs
Simply open in Emacs a file belonging to your lein
or boot
project (like
foo.clj
) and type M-x cider-jack-in. This will start a nREPL with
all the deps loaded in, plus a CIDER
client connected to it.
Alternative you can use C-u M-x cider-jack-in to specify the name of
a lein
or boot
project, without having to visit any file in it.
Connect to a running nREPL server
You can go to your project's dir in a terminal and type there (assuming you're using Leiningen that is):
$ lein repl
Or with Boot:
$ boot repl wait
Alternatively you can start nREPL either manually or by the facilities provided by your project build tool (Maven, etc).
After you get your nREPL server running go back to Emacs. Typing there M-x cider-connect will allow you to connect to the running nREPL server.
Using the cider minor mode
CIDER
comes with a handy minor mode called cider-mode
(complementing
clojure-mode
) that allows you to evaluate code in your Clojure source
files and load it directly in the REPL. A list of all
available commands is available in the CIDER
menu and in the following
section of this manual.
Pretty printing in the REPL
Make the REPL always pretty-print the results of your commands. Note
that this will not work correctly with forms such as (def a 1) (def b2)
and it expects clojure.pprint
to have been required already
(the default in more recent versions of Clojure):
M-x cider-repl-toggle-pretty-printing
Limiting printed output in the REPL
Accidentally printing large objects can be detrimental to your
productivity. Clojure provides the *print-length*
var which, if set,
controls how many items of each collection the printer will print. You
can supply a default value for REPL sessions via the global-vars
section of your Leiningen project's configuration.
:global-vars {*print-length* 100}
ClojureScript usage
ClojureScript support relies on the piggieback nREPL middleware being present in your REPL session. Version 0.2.0 or higher is recommended, and the below examples assume this, but version 0.1.5 is currently also supported.
-
Example usage of a non-browser connected Node.js REPL:
-
At the Clojure REPL:
(require '[cemerick.piggieback :as piggieback]) (require '[cljs.repl.node :as node]) (piggieback/cljs-repl (node/repl-env))
-
-
Example usage of browser-connected Weasel REPL (requires e.g.
[weasel "0.6.0"]
in your project's:dependencies
):-
At the Clojure REPL:
(require '[cemerick.piggieback :as piggieback]) (require '[weasel.repl.websocket :as weasel]) (piggieback/cljs-repl (weasel/repl-env :ip "127.0.0.1" :port 9001))
-
and in your ClojureScript:
(ns my.cljs.core (:require [weasel.repl :as repl])) (repl/connect "ws://localhost:9001")
-
The clojure-quick-repls library provides helper functions to automate REPL creation for both Clojure and Clojurescript, and will also automatically route requests to the correct REPL according to the file extension of the current buffer (note that CIDER does not provide the latter functionality out-of-the-box).
Provided that a Piggieback-enabled ClojureScript environment is active in your
REPL session, code loading and evaluation will work seamlessly regardless of the
presence of the cider-nrepl
middleware. If the middleware is present then most
other features of CIDER will also be enabled (including code completion,
documentation lookup, the namespace browser, and macroexpansion).
Keyboard shortcuts
- M-x cider-jack-in: Launch an nREPL server and a REPL client. Prompts for a project root if given a prefix argument.
- M-x cider: Connect to an already-running nREPL server.
While you're in clojure-mode
, cider-jack-in
is bound for
convenience to C-c M-j and cider-connect
is bound to C-c
M-c.
cider-mode
Keyboard shortcut | Description |
---|---|
C-x C-e C-c C-e | Evaluate the form preceding point and display the result in the echo area. If invoked with a prefix argument, insert the result into the current buffer. |
C-c C-w | Evaluate the form preceding point and replace it with its result. |
C-c M-e | Evaluate the form preceding point and output it result to the REPL buffer. If invoked with a prefix argument, takes you to the REPL buffer after being invoked. |
C-c M-p | Load the form preceding point in the REPL buffer. |
C-c C-p | Evaluate the form preceding point and pretty-print the result in a popup buffer. |
C-c C-f | Evaluate the top level form under point and pretty-print the result in a popup buffer. |
C-M-x C-c C-c | Evaluate the top level form under point and display the result in the echo area. |
C-u C-M-x C-u C-c C-c | Debug the top level form under point and walk through its evaluation |
C-c C-r | Evaluate the region and display the result in the echo area. |
C-c C-b | Interrupt any pending evaluations. |
C-c C-m | Invoke macroexpand-1 on the form at point and display the result in a macroexpansion buffer. If invoked with a prefix argument, macroexpand is used instead of macroexpand-1 . |
C-c M-m | Invoke clojure.walk/macroexpand-all on the form at point and display the result in a macroexpansion buffer. |
C-c C-n | Eval the ns form. |
C-c M-n | Switch the namespace of the REPL buffer to the namespace of the current buffer. |
C-c C-z | Switch to the relevant REPL buffer. Use a prefix argument to change the namespace of the REPL buffer to match the currently visited source file. |
C-u C-u C-c C-z | Switch to the REPL buffer based on a user prompt for a directory. |
C-c M-d | Display default REPL connection details, including project directory name, buffer namespace, host and port. |
C-c M-r | Rotate and display the default nREPL connection. |
C-c M-o | Clear the entire REPL buffer, leaving only a prompt. Useful if you're running the REPL buffer in a side by side buffer. |
C-c C-k | Load (eval) the current buffer. |
C-c C-l | Load (eval) a Clojure file. |
C-c C-d d | Display doc string for the symbol at point. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol. |
C-c C-d j | Display JavaDoc (in your default browser) for the symbol at point. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol. |
C-c M-i | Inspect expression. Will act on expression at point if present. |
C-c M-t v | Toggle var tracing. |
C-c M-t n | Toggle namespace tracing. |
C-c C-u | Undefine a symbol. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol. |
C-c , | Run tests for namespace. |
C-c C-, | Re-run test failures/errors for namespace. |
C-c M-, | Run test at point. |
C-c C-t | Show the test report buffer. |
M-. | Jump to the definition of a symbol. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol. |
C-c M-. | Jump to the resource referenced by the string at point. |
C-c C-. | Jump to some namespace on the classpath. |
M-, | Return to your pre-jump location. |
M-TAB | Complete the symbol at point. |
C-c C-d r | Lookup symbol in Grimoire. |
C-c C-d a | Apropos search for functions/vars. |
C-c C-d A | Apropos search for documentation. |
cider-repl-mode
Keyboard shortcut | Description |
---|---|
RET | Evaluate the current input in Clojure if it is complete. If incomplete, open a new line and indent. If invoked with a prefix argument is given then the input is evaluated without checking for completeness. |
C-RET | Close any unmatched parenthesis and then evaluate the current input in Clojure. |
C-j | Open a new line and indent. |
C-c M-o | Clear the entire REPL buffer, leaving only a prompt. |
C-c C-o | Remove the output of the previous evaluation from the REPL buffer. |
C-c C-u | Kill all text from the prompt to the current point. |
C-c C-b C-c C-c | Interrupt any pending evaluations. |
C-up C-down | Goto to previous/next input in history. |
M-p M-n | Search the previous/next item in history using the current input as search pattern. If M-p/M-n is typed two times in a row, the second invocation uses the same search pattern (even if the current input has changed). |
M-s M-r | Search forward/reverse through command history with regex. |
C-c C-n C-c C-p | Move between the current and previous prompts in the REPL buffer. Pressing RET on a line with old input copies that line to the newest prompt. |
TAB | Complete symbol at point. |
C-c C-d d | Display doc string for the symbol at point. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol |
C-c C-d j | Display JavaDoc (in your default browser) for the symbol at point. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol. |
C-c C-d r | Lookup symbol in Grimoire. |
C-c C-d a | Apropos search for functions/vars. |
C-c C-d A | Apropos search for documentation. |
C-c C-z | Switch to the previous Clojure buffer. This complements C-c C-z used in cider-mode. |
C-c M-i | Inspect expression. Will act on expression at point if present. |
C-c M-n | Select a namespace and switch to it. |
C-c C-. | Jump to some namespace on the classpath. |
C-c M-t v | Toggle var tracing. |
C-c M-t n | Toggle namespace tracing. |
In the REPL you can also use "shortcut commands" by pressing ,
at the beginning of a REPL line. You'll be presented with a list of commands you can quickly run (like quitting, displaying some info, clearing the REPL, etc). The character used to trigger the shortcuts is configurable via cider-repl-shortcut-dispatch-char
. Here's how you can change it to :
:
(setq cider-repl-shortcut-dispatch-char ?\:)
cider-macroexpansion-mode
Keyboard shortcut | Description |
---|---|
C-c C-m | Invoke macroexpand-1 on the form at point and replace the original form with its expansion. If invoked with a prefix argument, macroexpand is used instead of macroexpand-1 . |
C-c M-m | Invoke clojure.walk/macroexpand-all on the form at point and replace the original form with its expansion. |
g | The prior macroexpansion is performed again and the current contents of the macroexpansion buffer are replaced with the new expansion. |
C-/ C-x u | Undo the last inplace expansion performed in the macroexpansion buffer. |
cider-inspector-mode
Keyboard shortcut | Description |
---|---|
Tab and Shift-Tab | navigate inspectable sub-objects |
Return | inspect sub-objects |
l | pop to the parent object |
g | refresh the inspector (e.g. if viewing an atom/ref/agent) |
cider-test-report-mode
Keyboard shortcut | Description |
---|---|
C-c , | Run tests for namespace. |
C-c C-, | Re-run test failures/errors for namespace. |
C-c M-, | Run test at point. |
M-p | Move point to previous test. |
M-n | Move point to next test. |
t and M-. | Jump to test definition. |
d | Display diff of actual vs expected. |
e | Display test error cause and stacktrace info. |
cider-stacktrace-mode
Keyboard shortcut | Description |
---|---|
M-p | move point to previous cause |
M-n | move point to next cause |
M-. and Return | navigate to the source location (if available) for the stacktrace frame |
Tab | Cycle current cause detail |
0 and S-Tab | Cycle all cause detail |
1 | Cycle cause #1 detail |
2 | Cycle cause #2 detail |
3 | Cycle cause #3 detail |
4 | Cycle cause #4 detail |
5 | Cycle cause #5 detail |
j | toggle display of java frames |
c | toggle display of clj frames |
r | toggle display of repl frames |
t | toggle display of tooling frames (e.g. compiler, nREPL middleware) |
d | toggle display of duplicate frames |
a | toggle display of all frames |
cider-debug
cider-debug
(invoked with C-u C-M-x) tries to be consistent with
Edebug. So
it makes available the following bindings while stepping through code.
Keyboard shortcut | Description |
---|---|
n | Next step |
c | Continue without stopping |
o | Move out of the current sexp (like up-list ) |
i | Inject a value into running code |
e | Eval code in current context |
l | List local variables |
q | Quit execution |
To uninstrument a form, after having instrumented it with C-u C-M-x you just have to evaluate the form again as you'd normally do (e.g. with C-M-x).
Managing multiple sessions
You can connect to multiple nREPL servers using M-x cider-jack-in multiple times. To close the current nREPL connection, use M-x nrepl-close. M-x cider-quit closes all connections.
CIDER maintains a list of nREPL connections and a single 'default' connection. When you execute CIDER commands in a Clojure editing buffer such as to compile a namespace, these commands are executed against the default connection.
You can display the default nREPL connection using C-c M-d and rotate the default connection using C-c M-r. Another option for setting the default connection is to execute the command M-x nrepl-make-connection-default in the appropriate REPL buffer.
To switch to the relevant REPL buffer based on the Clojure namespace in the current Clojure buffer, use: C-c C-z. You can then use the same key combination to switch back to the Clojure buffer you came from.
The single prefix C-u C-c C-z, will switch you to the relevant REPL buffer and set the namespace in that buffer based on namespace in the current Clojure buffer.
To explicitly choose the REPL buffer that C-c C-z uses
based on project directory, use a double prefix C-u C-u C-c
C-z. This assumes you have cider-switch-to-relevant-repl
mapped to the var cider-switch-to-repl-command
which is the default
configuration.
To change the designation used for CIDER buffers use M-x
cider-change-buffers-designation. This changes the CIDER REPL
buffer, nREPL connection buffer and nREPL server buffer. For example
using cider-change-buffers-designation
with the string "foo" would
change *cider-repl localhost*
to *cider-repl foo*
.
Requirements
Caveats
ClojureScript limitations
Currently, the following features are not supported for ClojureScript development:
- Grimoire lookup
- Reloading
- Running tests
- Tracing
There is currently no support for both Clojure and ClojureScript evaluation in the same nREPL session. If Piggieback is active, code evaluation and all features will assume ClojureScript.
The aforementioned clojure-quick-repls aids this situation by routing requests to the correct REPL according to the file extension of the current buffer.
Microsoft Windows
On Microsoft Windows the JVM default line separator string is \r\n
which can appear in Emacs as ^M
characters at the end of lines
printed out by the JVM. One option is to set the
buffer-display-table
to not show these characters as detailed
here
(changing slime-repl-mode-hook
to
cider-repl-mode-hook
). Alternatively, setting the system property
line.separator
to \n
at JVM startup will stop the carriage return
from being printed and will fix output in all cider buffers. To do so
add "-Dline.separator=\"\n\""
to :jvm-opts
in
~/.lein/profiles.clj
.
powershell.el
The powershell inferior shell mode truncates CIDER's REPL output when loaded. As a workaround remove
(require 'powershell)
from your Emacs config.
Troubleshooting
In case you run into issues here are a few tips that can help you diagnose the problem.
Generally, it's not a bad idea to configure Emacs to spit the backtrace on error
(instead of just logging the error in the *Messages*
buffer. You can toggle
this behavior by using M-x toggle-debug-on-error
.
REPL not starting
Make sure that your CIDER
version matches your cider-nrepl
version. Check
the contents of the *Messages*
buffer for CIDER
-related errors. You should
also check the nREPL messages passed between CIDER and nREPL in
*nrepl-messages*
. If you don't see anything useful there it's time to bring
out the big guns.
Debugging the REPL init
Emacs features a super powerful built-in
Emacs Lisp debugger
and using it is the best way to diagnose problems of any kind. To debug CIDER's
REPL initialization it's a good idea to hook into one of its entry points. Add a
breakpoint to cider-make-repl
(C-u C-M-x
, while its body). Next time you
start CIDER you'll be dropped in the debugger and you can step forward until you
find the problem.
Here's a great crash course on using the debugger.
*nrepl-messages*
buffer
Missing Check the value of nrepl-log-messages
. It should be non-nil.
cider-debug
complains that it “failed to instrument ...”
In the REPL buffer, issue the following.
your.namespace> (ns cider.nrepl.middleware.util.instrument)
cider.nrepl.middleware.util.instrument> (def verbose-debug true)
This will cause cider to print extensive information on the REPL buffer when you try to debug an expression (e.g., with C-u C-M-x
). File an issue and copy this information.
Warning saying you have to use nREPL 0.2.7+
CIDER currently requires at least nREPL 0.2.7 to work properly (there were some
nasty bugs in 0.2.6). Unfortunately the latest leiningen
(2.5.1) pulls in exactly
0.2.6, so you if you're a lein user you'll have to do a bit of manual work. Just
add this to your profiles.clj
:
{:user {:dependencies [[org.clojure/tools.nrepl "0.2.10"]]}}
Make sure you add the newer nREPL dependency to the :dependencies
key instead
of :plugins
(where cider-nrepl
Lein plugin resides). That's a pretty common
mistake.
Generally you're advised to use the newest nREPL with CIDER, as bugs get fixed in pretty much every release.
Note, that running cider-jack-in
from outside the scope of a project will
result in the older (0.2.6) nREPL dependency being used (at least on Leiningen
2.5.1). This is likely a Leiningen bug.
Documentation
A single-page quick reference PDF for CIDER commands is available here. This PDF can be created manually by running pdflatex
on the CIDER refcard LaTeX file.
Changelog
An extensive changelog is available here.
Team
- Bozhidar Batsov (maintainer)
- Tim King (original author)
- Phil Hagelberg
- Hugo Duncan
- Steve Purcell
- Jeff Valk
Release policy
We’re following SemVer (as much as one can be following it when the major version is 0). At this point bumps of the minor (second) version number are considered major releases and always include new features or significant changes to existing features. API compatibility between major releases is not a (big) concern (although we try to break the API rarely and only for a good reason).
The development cycle for the next major release starts immediately after the previous one has been shipped. Bugfix/point releases (if any) address only serious bugs and never contain new features.
The versions of CIDER and cider-nrepl
are always kept in sync. If you're tracking the
master
branch of CIDER, you should also be tracking the master
branch of cider-nrepl
.
Logo
CIDER's logo was created by @ndr-qef. You can find the logo in various formats here.
The logo is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.
Contributing
Discussion
For questions, suggestions and support refer to our official mailing list
, the Freenode channel #clojure-emacs
, #cider
on slack or our gitter channel.
Please, don't report issues there, as this makes them harder to track.
Issues
Report issues and suggest features and improvements on the GitHub issue tracker. Don't ask questions on the issue tracker - the mailing list and the IRC channel are the places for questions.
If you want to file a bug, please clone this repo and provide sufficient details to reproduce the issue. Start by running make run-cider
.
This will bring up Emacs with only the latest version of CIDER loaded. By starting fresh, with the latest code, we can ensure that the problem at hand isn't already fixed or caused by interactions with other packages.
Patches
Patches under any form are always welcome! GitHub pull requests are even better! :-)
Before submitting a patch or a pull request make sure all tests are passing and that your patch is in line with the contribution guidelines.
Documentation
Consider improving and extending the community wiki.
Donations
You can support my work on CIDER, clojure-mode and all my other projects via gratipay and PayPal.
Running the tests in batch mode
Install cask if you haven't already, then:
$ cd /path/to/cider
$ cask
Run all tests with:
$ make test
(Note: tests may not run correctly inside Emacs' shell-mode buffers. Running in a terminal is recommended.)
License
Copyright © 2012-2015 Tim King, Phil Hagelberg, Bozhidar Batsov, Hugo Duncan, Steve Purcell and contributors.
Distributed under the GNU General Public License, version 3