rfkm / cider Goto Github PK

CIDER (formerly nrepl.el) is the Clojure Interactive Development Environment that Rocks!

CIDER extends Emacs with support for interactive programming in Clojure. The features are centered around cider-mode, an Emacs minor-mode that complements clojure-mode. While clojure-mode supports editing Clojure source files, cider-mode adds support for interacting with a running Clojure process for compilation, debugging, definition and documentation lookup, running tests and so on.

CIDER is the successor to the now deprecated combination of using SLIME + swank-clojure for Clojure development.

If you like the project, please consider supporting its ongoing development.

This documentation tracks the master branch of CIDER. Some of the features and settings discussed here might not be available in older releases (including the current stable release). Please, consult the relevant git tag (e.g. v0.10.0) if you need documentation for a specific CIDER release.

• Overview
• Installation
  • Prerequisites
  • Installation via package.el
  • Setting up CIDER's nREPL middleware
    • Using Leiningen
    • Using Boot
    • Using embedded nREPL server
• Basic Usage
  • Setting up a Leiningen or Boot project (optional)
  • Launch a nREPL server and client from Emacs
  • Connect to a running nREPL server
  • Using cider-mode
  • Using the REPL
    • REPL Configuration
      • REPL history
  • ClojureScript usage
• Extended Workflow
  • Macroexpansion
  • Value Inspection
  • Running Tests
  • Navigating Stacktraces
  • Debugging
  • Code reloading
  • Managing multiple connections
• Configuration
  • Basic configuration
  • Overlays
  • Specifying indentation
  • Minibuffer completion
  • Auto-completion
  • Integration with other modes
• Caveats
  • Var Metadata
  • ClojureScript limitations
  • Microsoft Windows
  • powershell.el
• Troubleshooting
• Documentation
• Changelog
• Team
• Release policy
• Logo
• Contributing
  • Discussion
  • Issues
  • Patches
  • Documentation
  • Donations
  • Running the tests in batch mode
• License

CIDER aims to provide an interactive development experience similar to the one you'd get when programming in Emacs Lisp, Common Lisp (with SLIME or Sly), Scheme (with Geiser) and Smalltalk.

Programmers are expected to program in a very dynamic and incremental manner, constantly re-evaluating existing Clojure definitions and adding new ones to their running applications. You never stop/start a Clojure application while using CIDER - you're constantly interacting with it and changing it.

You can find more details about the typical CIDER workflow in the Basic Usage section. While we're a bit short on video tutorials, you can check out this tutorial about SLIME to get a feel about what do we mean by an "Interactive Development Environment". There are plenty of differences between CIDER and SLIME, but the core ideas are pretty much the same (and SLIME served as the principle inspiration for CIDER).

CIDER's built on top of nREPL, the Clojure networked REPL server.

CIDER's basic architecture looks something like this:

Clojure code gets executed by an nREPL server. CIDER sends requests to the server and processes its responses. The server's functionality is augmented by additional nREPL middleware, designed specifically to address the needs of an interactive development environment like CIDER. Much of the middleware we developed for CIDER is editor agnostic and is being used by other Clojure dev environments as well (e.g. vim-fireplace & CCW).

If you're interested in more details about CIDER's history and architecture you can check out the Clojure/conj presentation The Evolution of the Emacs tooling for Clojure and the Cognicast's episode on CIDER.

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
• Enhanced Clojure font-locking and indentation
• Grimoire integration
• clojure.test integration
• Classpath browser
• Namespace browser
• nREPL session management
• Scratchpad
• Minibuffer code evaluation
• Integration with company-mode and auto-complete-mode
• Support for working with multiple simultaneous nREPL connections

The canonical way to install CIDER is via package.el (Emacs's built-in package manager), but plenty of other options exist. (see the wiki).

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.

CIDER officially supports Emacs 24.3+ and Clojure 1.5+.

You'll also need a recent version of your favorite build tool (Leiningen, Boot or Gradle) to be able to start CIDER via cider-jack-in. Generally it's a good idea to use their latest stable versions.

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.

If you were using nrepl-ritz, you'll also have to remove its plugin and middleware from your profiles.clj (or project.clj).

CIDER 0.7 introduced 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 or newer, as clojure-test-mode sometimes interferes with CIDER's REPL initialization.

package.el is the built-in package manager in Emacs.

CIDER is available on the two major package.el community maintained repos - MELPA Stable and MELPA.

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 by adding this to your Emacs initialization:

(add-to-list 'package-pinned-packages '(cider . "melpa-stable") t)

CIDER has deps (e.g. queue & seq) that are only available in the GNU ELPA repository. It's the only package repository enabled by default in Emacs and you should not disable it!

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 :repl profile in ~/.lein/profiles.clj.

:plugins [[cider/cider-nrepl "x.y.z"]]

A minimal profiles.clj for CIDER would be:

{:repl {:plugins [[cider/cider-nrepl "0.10.0"]]}}

Be careful not to place this in the :user profile, as this way CIDER's middleware will always get loaded, causing lein to start slower. You really need it just for lein repl and this is what the :repl profile is for.

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.10.0"]])

(swap! boot.repl/*default-middleware*
       conj 'cider.nrepl/cider-middleware)

For more information visit boot-clj wiki.

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.

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 (however, it is required if you want to use the cider-jack-in command).

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.

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 server with all the project deps loaded in and CIDER with automatically connect to it.

Alternatively 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.

In Clojure(Script) buffers the command cider-jack-in is bound to C-c M-j.

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's 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.

In Clojure(Script) buffers the command cider-connect is bound to C-c M-c.

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. Here's a list of its keybindings:

There's no need to memorize this list. In any Clojure buffer with cider-mode active you'll have a CIDER menu available, which lists all the most important commands and their keybindings. You can also invoke C-h f RET cider-mode to get a list of the keybindings for cider-mode.

CIDER comes with a powerful REPL, which is quite handy when you want to experiment with the code you're working on or just explore some stuff (e.g. a library you're playing with). The REPL offers a number of advanced features:

• auto-completion
• font-locking (the same as in clojure-mode)
• quick access to many CIDER commands (e.g. definition and documentation lookup, tracing, etc)

Here's a list of the keybindings that are available in CIDER's REPL:

There's no need to memorize this list. In any REPL buffer you'll have a REPL menu available, which lists all the most important commands and their keybindings. You can also invoke C-h f RET cider-repl-mode to get a list of the keybindings for cider-repl-mode.

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 ?\:)

• You can customize the prompt in REPL buffer. To do that you can customize cider-repl-prompt-function and set it to a function that takes one argument, a namespace name. For convenience, three functions are already provided: cider-repl-prompt-lastname, cider-repl-prompt-abbreviated, cider-repl-prompt-default and by default the last one is being used. Prompt for each of them for namespace leiningen.core.ssl:

  • cider-repl-prompt-lastname:

  ssl>
  

  • cider-repl-prompt-abbreviated:

  l.c.ssl>
  

  • cider-repl-prompt-default:

  leiningen.core.ssl>
  

  You may, of course, write your own function. For example, in leiningen there are two namespaces with similar names - leiningen.classpath and leiningen.core.classpath. To make them easily recognizable you can either use the default value or you can opt to show only two segments of the namespace and still be able to know which is the REPL's current namespace. Here is an example function that will do exactly that:

  (defun cider-repl-prompt-show-two (namespace)
    "Return a prompt string with the last name in NAMESPACE."
    (let* ((names (reverse (-take 2 (reverse (split-string namespace "\\."))))))
      (concat (car names) "." (cadr names) "> ")))

• 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 command cider-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)

• 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

• The REPL buffer name has the format *cider-repl project-name*. Change the separator from space to something else by overriding nrepl-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)

• Normally code in the REPL is font-locked the same way as in clojure-mode. Before CIDER 0.10 by default REPL input was font-locked with cider-repl-input-face (after you press RET) and results were font-locked with cider-repl-result-face. If you want to restore the old behaviour use:

(setq cider-repl-use-clojure-font-lock nil)

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

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 repl-options section of your Leiningen project's configuration.

:repl-options {:init (set! *print-length* 50)}

• 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 quitting Emacs.

ClojureScript support relies on the piggieback nREPL middleware being present in your REPL session.

1. Add the following dependencies to your project.clj

   [com.cemerick/piggieback "0.2.1"]
   [org.clojure/clojure "1.7.0"]

   as well as the following option:

   :repl-options {:nrepl-middleware [cemerick.piggieback/wrap-cljs-repl]}

2. Issue M-x customize-variable RET cider-cljs-repl if you'd like to change the REPL used (the default is rhino).

3. Open a file in your project and issue M-x cider-jack-in-clojurescript. This will start up the nREPL server, and then create two REPL buffers for you, one in Clojure and one in ClojureScript. All usual CIDER commands will be automatically directed to the appropriate REPL, depending on whether you're visiting a clj or a cljs file.

Using Weasel, you can also have a browser-connected REPL.

1. Add [weasel "0.7.0"] to your project's :dependencies.

2. Issue M-x customize-variable RET cider-cljs-repl and choose the Weasel option.

3. Add this to your ClojureScript code:

   (ns my.cljs.core
     (:require [weasel.repl :as repl]))
   (repl/connect "ws://localhost:9001")

4. Open a file in your project and issue M-x cider-jack-in-clojurescript.

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).

CIDER packs a ton of extra functionality, besides basic Clojure code evaluation. Much of the functionality is centered around additional major modes, which provide you with convenient ways to get something done or inspect something.

Pressing C-c C-m after some form in a source buffer or the REPL will result in a new buffer, showing the macroexpansion of form in question. You'll have access to additional keybindings in the macroexpansion buffer (which is internally using cider-macroexpansion-mode):

Pressing C-c C-i after some form in a source buffer or the REPL will result in a new buffer, showing the structure of the result of the form in question. You'll have access to additional keybindings in the inspector buffer (which is internally using cider-inspector-mode):

You can run clojure.test tests pretty quickly in CIDER. Pressing C-c , in a source buffer will run the tests for the namespace you're currently in. CIDER is smart enough to figure out the namespace containing the tests.

In the buffer displaying the test execution results you'll have a bit of additional functionality at your disposal.

Certain aspects of the test execution behavior are configurable:

• If your tests are not following the some.ns-test naming convention you can customize the variable cider-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)

CIDER comes with a powerful solution to the problem of verbose Clojure stacktraces. Stacktraces are presented in a special major mode (cider-stacktrace-mode), which gives you the possibility to filter out certain stack frames and some handy ways to navigate causes. You'll also be able to go to the code in question with a single keystroke.

• Error buffer stacktraces may be filtered by default. Valid filter types include java, clj, repl, tooling, and dup. Setting this to nil 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 debugger can be invoked in several ways, the simplest one is to type C-u C-M-x. This will take the current top-level form, place as many breakpoints inside it as possible (instrument it), and then evaluate it a 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 called. To uninstrument defn (or similar forms), you just have to evaluate it again as you'd normally do (e.g. with C-M-x).

Another way to trigger the debugger is by placing breakpoints yourself. Just write #break before a form, and the debugger will popup every time that form is evaluated. 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 not only breakpoint the form but also everything inside it. In the example above, this places a breakpoint around (inspector msg) and another around msg. If you've been paying attention, you may have noticed that the first option (C-u C-M-x) is a quick way of evaluating the current top-level form with #dbg in front.

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

cider-debug tries to be consistent with Edebug. So it makes available the following bindings while stepping through code.

In addition, all the usual evaluation commands (such as C-x C-e or C-c M-:) will use the current lexical context (local variables) while the debugger is active.

cider-refresh wraps clojure.tools.namespace, and as such the same benefits and caveats regarding writing reloadable code also apply.

Calling cider-refresh will cause all modified Clojure files on the classpath to be reloaded. You can also provide a single prefix argument to reload all Clojure files on the classpath unconditionally, or a double prefix argument to first clear the state of the namespace tracker before reloading.

The above three operations are analogous to clojure.tools.namespace.repl/refresh, clojure.tools.namespace.repl/refresh-all and clojure.tools.namespace.repl/clear (followed by a normal refresh), respectively.

• You can define Clojure functions to be called before reloading, and after a successful reload, when using cider-refresh:

(setq cider-refresh-before-fn "user/stop-system!"
      cider-refresh-after-fn "user/start-system!")

• These must be set to the namespace-qualified names of vars bound to functions of no arguments. The functions must be synchronous (blocking), and are expected to be side-effecting - they will always be executed serially, without retries.

• By default, messages regarding the status of the in-progress reload will be displayed in the echo area after you call cider-refresh. The same information will also be recorded in the *cider-refresh-log* buffer, along with anything printed to *out* or *err* by cider-refresh-before-fn and cider-refresh-start-fn.

• You can make the *cider-refresh-log* buffer display automatically after you call cider-refresh by setting the cider-refresh-show-log-buffer variable to a non-nil value (this will also prevent any related messages from also being displayed in the echo area):

(setq cider-refresh-show-log-buffer t)

You can connect to multiple nREPL servers using M-x cider-jack-in (or cider-connect) multiple times. To close the current nREPL connection, use M-x cider-quit.

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 a specific connection. This is controlled by the variable cider-request-dispatch - when it's set to 'dynamic (the default), CIDER will try to infer which connection to use from the current project and currently visited file; when 'static dispatch is used all requests will always be routed to the default connection (this was the default behavior in CIDER before 0.10).

You can display the current 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 cider-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 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*.

You can certainly use CIDER without configuring it any further, but here are some ways other folks are adjusting their CIDER experience.

• Enable eldoc in Clojure buffers:

(add-hook 'cider-mode-hook #'eldoc-mode)

• Suppress auto-enabling of cider-mode in clojure-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.

• Don't log communication with the nREPL server:

(setq nrepl-log-messages nil)

Basically, this will dispose of the buffer *nrepl-messages*. The communication log is invaluable for debugging CIDER issues, so you're generally advised to keep it around.

• You can hide the *nrepl-connection* and *nrepl-server* buffers from appearing in some buffer switching commands like switch-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).

• 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. Use cider-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)

• 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:

;; Don't prompt and don't save
(setq cider-prompt-save-file-on-load nil)
;; Just save without prompting
(setq cider-prompt-save-file-on-load 'always-save)

• 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("").

• CIDER can syntax highlight symbols that are known to be defined. By default, this is done on symbols from the clojure.core namespace as well as macros from any namespace. If you'd like CIDER to also colorize usages of functions and variables from any namespace, do:

(setq cider-font-lock-dynamically '(macro core function var))

• 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 the index.html is located) to be included on your classpath (i.e., where the doc HTML files can be located by clojure.java.io/resource). For example, for Leiningen, with the local API path being /usr/share/doc/java/api/, put the following line in project.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.

When you evaluate code in Clojure files, the result is displayed in the buffer itself, in an overlay right after the evaluated code. If you want this overlay to be font-locked (syntax-highlighted) like Clojure code, set the following variable.

(setq cider-overlays-use-font-lock t)

You can disable overlays entirely (and display results in the echo-area at the bottom) with the cider-use-overlays variable.

(setq cider-use-overlays nil)

It is common for macros to require special indentation mechanisms. This is most common in macros that start with do, def, or with-. CIDER has some heuristics to detect these macros, but it also lets you explicitly specify how a macro should be indented.

Here's a simple example of how someone would specify the indent spec for a macro they've written (using an example in core):

(defmacro with-in-str
  "[DOCSTRING]"
  {:style/indent 1}
  [s & body]
  ...cut for brevity...)

And here's a more complex one:

(defmacro letfn
  "[DOCSTRING]"
  {:style/indent [1 [[:defn]] :form]}
  [fnspecs & body]
  ...cut for brevity...)

Don't worry if this looks intimidating. For most macros the indent spec should be either just a number, or one of the keywords :defn or :form. A full description of the spec is provided in Indent-Spec.md.

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 is bundled with Emacs and enhances the default minibuffer completion:

(require 'icomplete)

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.

CIDER users are advised to use company-mode to enable auto-completion inside of source code and REPL buffers. To install company-mode do:

M-x package-install <RET> company <RET>

After installation, company can be turned on 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.

If you'd prefer to trigger completions manually you can add this to you config:

(setq company-idle-delay nil) ; never start completions automatically
(global-set-key (kbd "M-TAB") #'company-complete) ; use meta+tab, aka C-M-i, as manual trigger

To make tab complete, without losing the ability to manually indent, you can add this to your config:

(global-set-key (kbd "TAB") #'company-indent-or-complete-common)

company-indent-or-complete-common is available only in company-mode 0.9+ (at the time of this writing it's still in development).

• Disable ac-cider-setup or ac-nrepl-setup from running on CIDER hooks

• Remove cider-mode and cider-repl-mode from the ac-modes list

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.

• Enabling CamelCase support for editing commands(like forward-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 mode subword-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 enable paredit 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)

Currently, the following features are not supported for ClojureScript development:

• Grimoire lookup
• Reloading
• Running tests
• Tracing
• Debugging (check out this ticket dedicated to porting the debugger to ClojureScript)

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.

Currently var metadata about the location of the var's definition within the ClojureScript source code (file, line & column) is set only when evaluating the entire source buffer (C-c C-k). All other interactive code evaluation commands (e.g. C-c C-e) don't set this metadata and you won't be able to use commands like find-var on such vars. This is a limitation of nREPL and piggieback, that's beyond CIDER. You can find some discussions on the subject here and here.

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.

The powershell inferior shell mode truncates CIDER's REPL output when loaded. As a workaround remove

(require 'powershell)

from your Emacs config.

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.

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.

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 in 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.

Check the value of nrepl-log-messages. It should be non-nil.

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.

CIDER currently requires at least nREPL 0.2.12 to work properly (there were some nasty bugs in older version and no support tracking where some var was defined in the source code). Leiningen users can add this to their profiles.clj to force the proper dependency:

{:repl {:dependencies [[org.clojure/tools.nrepl "0.2.12"]]}}

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.

Most likely you've updated CIDER, without updating clojure-mode as well.

CIDER depends on clojure-mode and you should always update them together, as the latest CIDER version might depend on functionality present only in the latest clojure-mode version.

The built-in package manager isn't perfect and sometimes it messes up. If you just updated and encountered an error you should try the following before opening an issue: Go into the .emacs.d/elpa directory, delete any folders related to CIDER, restart emacs and then re-install the missing packages. Note that the order here matters.

Emacs doesn't load the new files, it only installs them on disk. To see the effect of changes you have to restart emacs.

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.

An extensive changelog is available here.

• Bozhidar Batsov (maintainer)
• Tim King (original author)
• Phil Hagelberg
• Hugo Duncan
• Steve Purcell
• Jeff Valk
• Michael Griffiths
• Lars Andersen
• Artur Malabarba

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.

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.

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.

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 in 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.

Consider improving and extending the community wiki.

You can support my work on CIDER, clojure-mode and inf-clojure via Salt, Gratipay and PayPal.

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 them in a terminal is recommended.)

You can also check for the presence of byte-compilation warnings in batch mode:

$ make test-bytecomp

Copyright © 2012-2015 Tim King, Phil Hagelberg, Bozhidar Batsov, Hugo Duncan, Steve Purcell and contributors.

Distributed under the GNU General Public License, version 3