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.
You can see every single customizable configuration option with the command M-x customize-group RET cider.
This section doesn’t describe every possible customization that CIDER offers, but here are some of the most popular.
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)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 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.
== Auto-Save Clojure Buffers on Load
Normally, CIDER prompts you to save a modified Clojure buffer when you
type kbd:[C-c C-k] (`cider-load-buffer`). You can change this
behaviour by adjusting `cider-save-file-on-load`.
Don't prompt and don't save:
[source,lisp](setq cider-save-file-on-load nil)
Just save without prompting: [source,lisp]
(setq cider-save-file-on-load t)
== Change the Result Prefix for Interactive Evaluation Change the result prefix for interactive evaluation (not the REPL prefix). By default the prefix is `+=> +`. [source,lisp]
- (setq cider-eval-result-prefix "
-
⇒ ")
To remove the prefix altogether, just set it to the empty string (`""`). == 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 http://docs.oracle.com/javase/8/docs/api/[JavaSE 8]), per nREPL's http://docs.oracle.com/javase/8/docs/api/[`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`: [source,clojure]
:dev {:resource-paths ["/usr/share/doc/java/api/"]}
*or* the following line in `$HOME/.lein/profiles.clj`: [source,clojure]
:user {:resource-paths ["/usr/share/doc/java/api/"]}
More details can be found https://github.com/clojure-emacs/cider/issues/930[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 its `+/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
https://repo1.maven.org/maven2/org/clojure/clojure/1.8.0/clojure-1.8.0-sources.jar[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 use `jar` or `zip` files `cider-jdk-src-paths`, but extracting
them is better since you get 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`. It 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 kbd:[M-x] `customize-variable` kbd:[RET] `cider-filter-regexps`.
Or by including a similar snippet along with the other CIDER configuration.
[source,lisp]
(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. *This variable should be set before loading CIDER* (which means before `require`-ing it or autoloading it). [source,lisp]
(setq cider-special-mode-truncate-lines nil)