Basic Configuration
Like Emacs itself, almost every part of CIDER is configurable. The CIDER developers have tried to implement some reasonable defaults that should work for a large portion of the Clojure community, but we know that there is nothing approaching a "one size fits all" development environment and we’ve tried to create points of customization that can account for many different peoples' preferences. In this way, you should be able to make CIDER as comfortable as possible for you.
This section doesn’t describe every possible customization that CIDER offers, but here are some of the most popular.
You can see every single customizable configuration option with the command M-x customize-group RET cider. |
Disable Automatic cider-mode in clojure-mode Buffers
By default, CIDER enables cider-mode
in all clojure-mode
buffers
after it establishes the first CIDER connection. It will also add a
clojure-mode
hook to enable cider-mode
on newly-created clojure-mode
buffers. You can override this behavior, however:
(setq cider-auto-mode nil)
Disable Symbol Confirmation
By default, CIDER prompts you for a symbol when it executes
interactive commands that require a symbol (e.g. cider-doc
). The
default symbol will be the one at point. If you set
cider-prompt-for-symbol
to nil
, CIDER will try the symbol at point
first, and only prompt if that fails (this was the behavior in older
CIDER releases).
(setq cider-prompt-for-symbol nil)
Control what window to use when jumping to a definition
By default M-. and other commands that jump to a definition have the following behavior:
-
If the definition buffer is visible simply switch to it.
-
Otherwise, use the current window to show the definition.
Other behavior is possible, and is controlled with
cider-jump-to-pop-to-buffer-actions
; the value of this is passed as the
action
argument to pop-to-buffer
.
The default value is ((display-buffer-reuse-window display-buffer-same-window))
.
Some people might prefer to always display the definition in the current window. Here’s how you can achieve this:
(setq cider-jump-to-pop-to-buffer-actions
'((display-buffer-same-window)))
Keep in mind this might cause problems with some special buffers (e.g. test report buffers), as when you try to navigate to a definition this will clobber the special buffer. |
For other possibilities, see the documentation for display-buffer
.
Example 1
You jump to map
in core.clj
when core.clj
is not being displayed in another
window in the current frame.
With both the default behavior and the alternative behavior defined above, the
definition of map
will be shown in the current window.
Example 2
You jump to map
in core.clj
when core.clj
is being displayed in another window
in the current frame.
With the default behavior, the definition of map
will be shown in the current
window; you will now have two windows showing core.clj
, and the existing
core.clj
window will be unchanged.
With the alternative behavior defined above, the definition of map
will be
shown in the existing core.clj
window; all windows will show the same buffer as
before the jump, and the current window will now be the one showing core.clj
.
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)
You can learn more about icomplete
here.
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-completing-read+
.
You might also want to install ido-flex
.
ivy (recommended)
If you’re fine with installing a third-party package for enhanced minibuffer completion you can’t go wrong with the modern and versatile ivy.
Log nREPL Communications
If you want to see all communications between CIDER and the nREPL server:
(setq nrepl-log-messages t)
CIDER will then create buffers named *nrepl-messages conn-name*
for
each connection.
The communication log is tremendously valuable for debugging CIDER-to-nREPL problems and we recommend you enable it when you are facing such issues.
Hide Special nREPL Buffers
If you’re finding that *nrepl-connection*
and *nrepl-server*
buffers are cluttering up your development environment, you can
suppress them from appearing in some buffer switching commands like
switch-to-buffer
(C-x b):
(setq nrepl-hide-special-buffers t)
If you need to make the hidden buffers appear When using
switch-to-buffer
, type SPC after issuing the command. The
hidden buffers will always be visible in list-buffers
(C-x C-b).
Prefer Local Resources Over Remote Resources
To prefer local resources to remote resources (tramp) when both are available:
(setq cider-prefer-local-resources t)
Translate File Paths
If you wish to translate file paths from your running instance you may use the
cider-path-translations
defcustom to do so. For instance, suppose your app is
running in a docker container with your source directories mounted there. The
navigation paths you’d get from nREPL will be relative to the source in the
docker container rather than the correct path on your host machine. You can add
translation mappings easily by setting the following (typically in .dir-locals.el
):
((nil
(cider-path-translations . (("/root" . "/Users/foo")
("/src/" . "/Users/foo/projects")))))
Each entry will be interpreted as a directory entry so trailing slash
is optional. Navigation to definition will attempt to translate these locations, and
if they exist, navigate there rather than report that the file does not
exist. In the example above, the .m2
directory is mounted at /root/.m2
and the source at /src
. These translations would map these locations
back to the user’s computer so that navigation to definition would work.
Use a Local Copy of the JDK API Documentation
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 details can be found here.
Use a Local Copy of the Java Source Code
When an exception is thrown, e.g. when eval-ing (. clojure.lang.RT foo)
, a
stack trace pops up. Some places of the stack trace link to Clojure files,
others to Java files. By default, you can click the Clojure file links to
navigate there. If you configure cider-jdk-src-paths
, you can also click the
Java file links to navigate there.
On Windows and macOS the JDK source code is bundled with the JDK. On Windows its
typical location is C:\Program Files\Java\{jdk-version}\src.zip
and on macOS it’s /Library/Java/JavaVirtualMachines/{jdk-version}/Contents/Home/src.zip
.
On Linux distributions usually the source code is distributed as a separate package. Here’s how do get the JDK 8 source on Ubuntu:
sudo apt install openjdk-8-source
The zip is installed to /usr/lib/jvm/openjdk-8/src.zip
.
You can download Clojure Java source code from here.
Extract both and configure e.g. like so:
(setq cider-jdk-src-paths '("~/java/clojure-1.8.0-sources" "~/java/openjvm-8-src"))
It’s possible to point cider-jdk-src-paths
to jar
or zip
files, but extracting
them is better since you can use features like ag
or dired-jump
.
Filter out namespaces in certain namespace-related commands
You can hide all nREPL middleware details from cider-browse-ns*
and cider-apropos*
commands by customizing the variable cider-filter-regexps
. The value of this
variable should be a list of regexps matching the pattern of namespaces you want
to filter out.
Its default value is '("^cider.nrepl" "^refactor-nrepl" "^nrepl")
,
the most commonly used middleware collections/packages.
An important thing to note is that this list of regexps is passed on to the middleware
without any pre-processing. So, the regexps have to be in Clojure format (with twice the number of backslashes)
and not Emacs Lisp. For example, to achieve the above effect, you could also set cider-filter-regexps
to '(".*nrepl")
.
To customize cider-filter-regexps
, you could use the Emacs customize UI,
with M-x customize-variable
RET cider-filter-regexps
.
An alternative is to set the variable along with the other CIDER configuration.
(setq cider-filter-regexps '(".*nrepl"))
Truncate long lines in special buffers
By default contents of CIDER’s special buffers such as *cider-test-report*
or *cider-doc*
are line truncated. You can set
cider-special-mode-truncate-lines
to nil
to make those buffers use word
wrapping instead of line truncating.
(setq cider-special-mode-truncate-lines nil)
This variable should be set before loading CIDER (which means before
require -ing it or autoloading it).
|