1= Basic Configuration 2:experimental: 3 4Like Emacs itself, almost every part of CIDER is configurable. The 5CIDER developers have tried to implement some reasonable defaults that 6should work for a large portion of the Clojure community, but we know 7that there is nothing approaching a "one size fits all" development 8environment and we've tried to create points of customization that can 9account for many different peoples' preferences. In this way, you 10should be able to make CIDER as comfortable as possible for *you*. 11 12This section doesn't describe every possible customization that CIDER 13offers, but here are some of the most popular. 14 15TIP: You can see every single customizable configuration option with the command 16kbd:[M-x customize-group RET cider]. 17 18== Disable Automatic cider-mode in clojure-mode Buffers 19 20By default, CIDER enables `cider-mode` in all `clojure-mode` buffers 21after it establishes the first CIDER connection. It will also add a 22`clojure-mode` hook to enable `cider-mode` on newly-created `clojure-mode` 23buffers. You can override this behavior, however: 24 25[source,lisp] 26---- 27(setq cider-auto-mode nil) 28---- 29 30== Prompt for Symbol Confirmation 31 32NOTE: The default here was changed in CIDER 1.0. 33 34By default, CIDER won't prompt you for a symbol when it executes 35interactive commands that require a symbol (e.g. `cider-doc`). Such 36commands operate on the symbol at point and prompt you to provide 37a symbol if they can't obtain one automatically. 38 39If you set 40`cider-prompt-for-symbol` to `t`, this behavior will be inverted and 41CIDER will always prompt you to confirm the symbol on which a command 42will operate. This behavior is useful, as it allows you to edit the 43inferred symbol, before some operation is carried out with it (and you get to 44see what was inferred by `cider-symbol-at-point`). 45 46[source,lisp] 47---- 48(setq cider-prompt-for-symbol t) 49---- 50 51TIP: Many interactive commands that operate on the symbol at point, 52accept a prefix argument that flips the behavior configured via 53`cider-prompt-for-symbol` for the current command invocation. 54 55== Control what window to use when jumping to a definition 56 57By default kbd:[M-.] and other commands that jump to a definition have the following behavior: 58 59* If the definition buffer is visible simply switch to it. 60* Otherwise, use the current window to show the definition. 61 62Other behavior is possible, and is controlled with 63`cider-jump-to-pop-to-buffer-actions`; the value of this is passed as the 64`action` argument to `pop-to-buffer`. 65 66The default value is `\((display-buffer-reuse-window display-buffer-same-window))`. 67 68Some people might prefer to always display the definition in the current 69window. Here's how you can achieve this: 70 71[source,lisp] 72---- 73(setq cider-jump-to-pop-to-buffer-actions 74 '((display-buffer-same-window))) 75---- 76 77WARNING: Keep in mind this might cause problems with some special buffers (e.g. test report buffers), 78as when you try to navigate to a definition this will clobber the special buffer. 79 80For other possibilities, see the documentation for `display-buffer`. 81 82=== Example 1 83 84You jump to `map` in `core.clj` when `core.clj` *_is not_* being displayed in another 85window in the current frame. 86 87With both the default behavior and the alternative behavior defined above, the 88definition of `map` will be shown in the current window. 89 90=== Example 2 91 92You jump to `map` in `core.clj` when `core.clj` *_is_* being displayed in another window 93in the current frame. 94 95With the default behavior, the definition of `map` will be shown in the current 96window; you will now have two windows showing `core.clj`, and the existing 97`core.clj` window will be unchanged. 98 99With the alternative behavior defined above, the definition of `map` will be 100shown in the existing `core.clj` window; all windows will show the same buffer as 101before the jump, and the current window will now be the one showing `core.clj`. 102 103== Minibuffer completion 104 105Out-of-the box, CIDER uses the standard `completing-read` Emacs mechanism. While 106it's not fancy it certainly gets the job done (just press kbd:[TAB]). There 107are, however, ways to improve upon the standard completion if you wish to. 108 109=== icomplete 110 111`icomplete` is bundled with Emacs and enhances the default minibuffer completion: 112 113[source,lisp] 114---- 115(require 'icomplete) 116---- 117 118You can learn more about `icomplete` 119https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html[here]. 120 121=== ido 122 123`ido` is also bundled with Emacs and offers more features than `icomplete`. 124If you are using `ido`, be sure to use both `ido-everywhere` 125and https://github.com/DarwinAwardWinner/ido-completing-read-plus[`ido-completing-read+`]. 126You might also want to install https://github.com/lewang/flx[`ido-flex`]. 127 128=== ivy (recommended) 129 130If you're fine with installing a third-party package for enhanced minibuffer 131completion you can't go wrong with the modern and versatile 132http://oremacs.com/2015/04/16/ivy-mode/[ivy]. 133 134== Log nREPL Communications 135 136If you want to see all communications between CIDER and the nREPL 137server: 138 139[source,lisp] 140---- 141(setq nrepl-log-messages t) 142---- 143 144CIDER will then create buffers named `+*nrepl-messages conn-name*+` for 145each connection. 146 147The communication log is tremendously valuable for 148debugging CIDER-to-nREPL problems and we recommend you enable it when 149you are facing such issues. 150 151== Hide Special nREPL Buffers 152 153If you're finding that `+*nrepl-connection*+` and `+*nrepl-server*+` 154buffers are cluttering up your development environment, you can 155suppress them from appearing in some buffer switching commands like 156`switch-to-buffer`(kbd:[C-x b]): 157 158[source,lisp] 159---- 160(setq nrepl-hide-special-buffers t) 161---- 162 163If you need to make the hidden buffers appear When using 164`switch-to-buffer`, type kbd:[SPC] after issuing the command. The 165hidden buffers will always be visible in `list-buffers` (kbd:[C-x C-b]). 166 167== Prefer Local Resources Over Remote Resources 168 169To prefer local resources to remote resources (tramp) when both are available: 170 171[source,lisp] 172---- 173(setq cider-prefer-local-resources t) 174---- 175 176== Translate File Paths 177 178If you wish to translate file paths from your running instance you may use the 179`cider-path-translations` defcustom to do so. For instance, suppose your app is 180running in a docker container with your source directories mounted there. The 181navigation paths you'd get from nREPL will be relative to the source in the 182docker container rather than the correct path on your host machine. You can add 183translation mappings easily by setting the following (typically in `.dir-locals.el`): 184 185[source,lisp] 186---- 187((nil 188 (cider-path-translations . (("/root/.m2" . "/Users/foo/.m2") 189 ("/src/" . "/Users/foo/projects"))))) 190---- 191 192Each entry will be interpreted as a directory entry so trailing slash 193is optional. Navigation to definition will attempt to translate these locations, and 194if they exist, navigate there rather than report that the file does not 195exist. In the example above, the `.m2` directory is mounted at `/root/.m2` 196and the source at `/src`. These translations would map these locations 197back to the user's computer so that navigation to definition would work. 198 199Using the `eval` pseudo-variable you can make the translation dynamic, enabling 200the possibility of sharing the `.dir-locals.el` across a team of developers with 201different configurations. 202 203[source,lisp] 204---- 205((nil . ((eval . (customize-set-variable 'cider-path-translations 206 (list 207 (cons "/src" (clojure-project-dir)) 208 (cons "/root/.m2" (concat (getenv "HOME") "/.m2")))))))) 209---- 210 211In this example, the path `/src` will be translated to the correct path of your 212Clojure project on the host machine. And `/root/.m2` to the host's `~/.m2` folder. 213 214== Use a Local Copy of the JDK API Documentation 215 216If you are targeting the JVM and prefer a local copy of the JDK API 217documentation over Oracle's official copy (e.g., for 218http://docs.oracle.com/javase/8/docs/api/[JavaSE 8]), per nREPL's 219http://docs.oracle.com/javase/8/docs/api/[`javadoc-info` logic (accurate as of 29 Dec 2014)], 220you can arrange your project to include the *root* path of the local API doc 221(i.e., where the `index.html` is located) to be included on your classpath 222(i.e., where the doc HTML files can be located by 223`clojure.java.io/resource`). For example, for Leiningen, with the local API 224path being `/usr/share/doc/java/api/`, put the following line in 225`project.clj`: 226 227[source,clojure] 228---- 229:dev {:resource-paths ["/usr/share/doc/java/api/"]} 230---- 231 232*or* the following line in `$HOME/.lein/profiles.clj`: 233 234[source,clojure] 235---- 236:user {:resource-paths ["/usr/share/doc/java/api/"]} 237---- 238 239More details can be found https://github.com/clojure-emacs/cider/issues/930[here]. 240 241== Use a Local Copy of the Java Source Code 242 243When an exception is thrown, e.g. when eval-ing `(. clojure.lang.RT foo)`, a 244stack trace pops up. Some places of the stack trace link to Clojure files, 245others to Java files. By default, you can click the Clojure file links to 246navigate there. If you configure `cider-jdk-src-paths`, you can also click the 247Java file links to navigate there. 248 249On Windows and macOS the JDK source code is bundled with the JDK. On Windows its 250typical location is `+C:\Program Files\Java\{jdk-version}\src.zip+` 251and on macOS it's `+/Library/Java/JavaVirtualMachines/{jdk-version}/Contents/Home/src.zip+`. 252 253On Linux distributions usually the source code is distributed as a separate package. 254Here's how do get the JDK 8 source on Ubuntu: 255 256 sudo apt install openjdk-8-source 257 258The zip is installed to `/usr/lib/jvm/openjdk-8/src.zip`. 259 260You can download Clojure Java source code from 261https://repo1.maven.org/maven2/org/clojure/clojure/1.8.0/clojure-1.8.0-sources.jar[here]. 262 263Extract both and configure e.g. like so: 264 265 (setq cider-jdk-src-paths '("~/java/clojure-1.8.0-sources" 266 "~/java/openjvm-8-src")) 267 268It's possible to point `cider-jdk-src-paths` to `jar` or `zip` files, but extracting 269them is better since you can use features like `ag` or `dired-jump`. 270 271== Filter out namespaces in certain namespace-related commands 272 273You can hide all nREPL middleware details from `cider-browse-ns*` and `cider-apropos*` 274commands by customizing the variable `cider-filter-regexps`. The value of this 275variable should be a list of regexps matching the pattern of namespaces you want 276to filter out. 277 278Its default value is `+'("^cider.nrepl" "^refactor-nrepl" "^nrepl")+`, 279the most commonly used middleware collections/packages. 280 281An important thing to note is that this list of regexps is passed on to the middleware 282without any pre-processing. So, the regexps have to be in Clojure format (with twice the number of backslashes) 283and not Emacs Lisp. For example, to achieve the above effect, you could also set `cider-filter-regexps` to `'(".*nrepl")`. 284 285To customize `cider-filter-regexps`, you could use the Emacs customize UI, 286with kbd:[M-x] `customize-variable` kbd:[RET] `cider-filter-regexps`. 287 288An alternative is to set the variable along with the other CIDER configuration. 289 290[source,lisp] 291---- 292(setq cider-filter-regexps '(".*nrepl")) 293---- 294 295== Truncate long lines in special buffers 296 297By default contents of CIDER's special buffers such as `+*cider-test-report*+` 298or `+*cider-doc*+` are line truncated. You can set 299`cider-special-mode-truncate-lines` to `nil` to make those buffers use word 300wrapping instead of line truncating. 301 302[source,lisp] 303---- 304(setq cider-special-mode-truncate-lines nil) 305---- 306 307IMPORTANT: This variable should be set *before* loading CIDER (which means before 308`require`-ing it or autoloading it). 309