diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/about/logo.md | 2 | ||||
| -rw-r--r-- | doc/about/team.md | 7 | ||||
| -rw-r--r-- | doc/cider-refcard.tex | 7 | ||||
| -rw-r--r-- | doc/clojurescript.md | 126 | ||||
| -rw-r--r-- | doc/code_completion.md | 18 | ||||
| -rw-r--r-- | doc/configuration.md | 2 | ||||
| -rw-r--r-- | doc/debugging.md | 14 | ||||
| -rw-r--r-- | doc/faq.md | 36 | ||||
| -rw-r--r-- | doc/hacking_on_cider.md | 25 | ||||
| -rw-r--r-- | doc/index.md | 36 | ||||
| -rw-r--r-- | doc/installation.md | 33 | ||||
| -rw-r--r-- | doc/interactive_programming.md | 40 | ||||
| -rw-r--r-- | doc/managing_connections.md | 173 | ||||
| -rw-r--r-- | doc/miscellaneous_features.md | 37 | ||||
| -rw-r--r-- | doc/navigating_stacktraces.md | 16 | ||||
| -rw-r--r-- | doc/troubleshooting.md | 22 | ||||
| -rw-r--r-- | doc/up_and_running.md | 101 | ||||
| -rw-r--r-- | doc/using_the_repl.md | 2 |
18 files changed, 469 insertions, 228 deletions
diff --git a/doc/about/logo.md b/doc/about/logo.md index a4232760..9ccc726f 100644 --- a/doc/about/logo.md +++ b/doc/about/logo.md @@ -1,4 +1,4 @@ -CIDER's logo was created by [@ndr-qef](https://github.com/ndr-qef). You can find +CIDER's logo was created by [@tapeinosyne](https://github.com/tapeinosyne). You can find the logo in various formats [here](https://github.com/clojure-emacs/cider/tree/master/logo). diff --git a/doc/about/team.md b/doc/about/team.md index 7592a0a9..a26733b1 100644 --- a/doc/about/team.md +++ b/doc/about/team.md @@ -5,9 +5,7 @@ group of long-term contributors manage releases, evaluate pull-requests, and does a lot of the groundwork on major new features. * [Bozhidar Batsov](https://github.com/bbatsov) (author & head maintainer) -* [Artur Malabarba](https://github.com/malabarba) -* [Michael Griffiths](https://github.com/cichli) -* [Jeff Valk](https://github.com/jeffvalk) +* [Vitalie Spinu](https://github.com/vspinu) * [Lars Andersen](https://github.com/expez) ## CIDER Alumni @@ -19,3 +17,6 @@ core team members. Lovingly known as The Alumni: * [Phil Hagelberg](https://github.com/technomancy) * [Hugo Duncan](https://github.com/hugoduncan) * [Steve Purcell](https://github.com/purcell) +* [Artur Malabarba](https://github.com/malabarba) +* [Michael Griffiths](https://github.com/cichli) +* [Jeff Valk](https://github.com/jeffvalk) diff --git a/doc/cider-refcard.tex b/doc/cider-refcard.tex index 6d877bd5..6885b438 100644 --- a/doc/cider-refcard.tex +++ b/doc/cider-refcard.tex @@ -125,11 +125,10 @@ \item[C-c M-p] cider-insert-last-sexp-in-repl \item[C-c C-z] cider-switch-to-repl-buffer \item[C-c M-o] cider-find-and-clear-repl-buffer - \item[C-c M-d] cider-display-connection-info - \item[C-c M-r] cider-rotate-default-connection - \item[C-c M-n] cider-repl-set-ns + \item[C-c M-d] cider-describe-connection + \item[C-c M-n M-n] cider-repl-set-ns \item[C-c C-b] cider-interrupt - \item[C-c C-x] cider-refresh + \item[C-c M-n M-r] cider-ns-refresh \item[C-c C-q] cider-quit \end{keylist} \end{multicols} diff --git a/doc/clojurescript.md b/doc/clojurescript.md index 17393e09..ade0222a 100644 --- a/doc/clojurescript.md +++ b/doc/clojurescript.md @@ -5,18 +5,31 @@ the functionality available with Clojure exists for ClojureScript (at least not yet). To give you a concrete example - things like running tests and the debugger are currently Clojure-only features. + +### Piggieback + ClojureScript support relies on the [piggieback][] nREPL middleware being present in your REPL session. There's one exception to this, though - [shadow-cljs][]. It has its own nREPL middleware and doesn't rely on piggieback at all. +If `cider-inject-dependencies-at-jack-in` is enabled (which is the default) then +piggieback will be automatically added and configured for your project when +doing `cider-jack-in-cljs`. + +If this configuration option is disabled or you're going to connect to +an already running nREPL server using `cider-connect-cljs` - continue +reading ahead. + +#### Manual Piggieback Setup + To setup piggieback add the following dependencies to your project (`project.clj` in Leiningen based project or `build.boot` in Boot project): ```clojure ;; use whatever are the most recent versions here -[cider/piggieback "0.3.2"] +[cider/piggieback "0.3.9"] [org.clojure/clojure "1.9.0"] ``` @@ -35,19 +48,28 @@ or in `build.boot`: repl {:middleware '[cider.piggieback/wrap-cljs-repl]}) ``` +### Starting a ClojureScript REPL + There are many ClojureScript REPLs out there and it's often hard to wrap your head around them and the differences between them. You'd do well to read [this awesome article](https://lambdaisland.com/guides/clojure-repls/clojurescript-repls) before proceeding with the rest of the instructions listed here. Open a file in your project and issue <kbd>M-x</kbd> -`cider-jack-in-clojurescript` <kbd>RET</kbd>. 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. +`cider-jack-in-cljs` <kbd>RET</kbd>. This will start up the nREPL +server, and then create a ClojureScript REPL buffer for you, one. + +!!! Note + + Prior to CIDER 0.18, `cider-jack-in-cljs` would create both a Clojure and + a ClojureScript REPL. In CIDER 0.18+ if you want to create both REPLs + you'll have to use `cider-jack-in-clj&cljs` instead. + +When you have a combination of Clojure and ClojureScript REPLs all +usual CIDER commands will be automatically directed to the appropriate +REPL, depending on whether you're visiting a `.clj` or a `.cljs` file. -`cider-jack-in-clojurescript` will prompt you about the type of +`cider-jack-in-cljs` will prompt you about the type of ClojureScript to start. Keep in mind that some of the REPLs will require some additional setup, before you can make use of them (e.g. you'll need to have Node.js installed to be able to start a node REPL). @@ -67,8 +89,25 @@ All supported ClojureScript REPLs are stored in (cider-register-cljs-repl-type 'super-cljs "(do (...))" optional-requirements-function) ``` +You can also modify the known ClojureScript REPLs on a per-project basis using +`.dir-locals.el`: + +```el +;; replace the list of REPLs types and set some default +((nil + (cider-default-cljs-repl . super-cljs) + (cider-cljs-repl-types . ((super-cljs "(do (foo) (bar))"))))) +``` + +```el +;; modify the list of known REPLs and set some default +((nil + (eval . (cider-register-cljs-repl-type 'super-cljs "(do (foo) (bar))")) + (cider-default-cljs-repl . super-cljs))) +``` + You can also create a ClojureScript REPL with the command -`cider-create-sibling-cljs-repl` in cases where you already have a +`cider-jack-in-sibling-clojurescript` in cases where you already have a Clojure REPL running. Continue reading for the additional setup needed for the various ClojureScript @@ -80,7 +119,7 @@ Using Weasel, you can also have a browser-connected REPL. 1. Add `[weasel "0.7.0"]` to your project's `:dependencies`. -2. Issue <kbd>M-x</kbd> `cider-jack-in-clojurescript` <kbd>RET</kbd> and choose +2. Issue <kbd>M-x</kbd> `cider-jack-in-cljs` <kbd>RET</kbd> and choose the `Weasel` option when prompted about the ClojureScript REPL type you want to use. @@ -92,7 +131,7 @@ Using Weasel, you can also have a browser-connected REPL. (repl/connect "ws://localhost:9001") ``` -4. Open a file in your project and issue <kbd>M-x</kbd> `cider-jack-in-clojurescript`. +4. Open a file in your project and issue <kbd>M-x</kbd> `cider-jack-in-cljs`. Provided that a Piggieback-enabled ClojureScript environment is active in your REPL session, code loading and evaluation will work seamlessly regardless of the @@ -109,7 +148,7 @@ documentation lookup, the namespace browser, and macroexpansion). [adzerk/boot-cljs-repl "X.Y.Z" :scope "test"] [pandeiro/boot-http "X.Y.Z" :scope "test"] [weasel "0.7.0" :scope "test"] -[cider/piggieback "0.3.2" :scope "test"] +[cider/piggieback "0.3.9" :scope "test"] ; not needed for cider-jack-in-cljs ``` and this at the end of `build.boot`: @@ -130,13 +169,18 @@ and this at the end of `build.boot`: 2. Issue <kbd>M-x</kbd> `customize-variable` <kbd>RET</kbd> `cider-boot-parameters` and insert `dev`. -3. Open a file in your project and issue <kbd>M-x</kbd> `cider-jack-in-clojurescript`. +3. Open a file in your project and issue <kbd>M-x</kbd> `cider-jack-in-cljs`. 5. Connect to the running server with your browser. The address is printed on the terminal, but it's probably `http://localhost:3000`. For more information visit [boot-cljs-repl](https://github.com/adzerk-oss/boot-cljs-repl). -### Using the Figwheel REPL (Leiningen-only) +### Using Figwheel (Leiningen-only) + +!!! Warning + + This has been deprecated in favour of using `figwheel-main`. Check out + the instructions in the next section. You can also use [Figwheel](https://github.com/bhauman/lein-figwheel) with CIDER. @@ -145,35 +189,59 @@ You can also use [Figwheel](https://github.com/bhauman/lein-figwheel) with CIDER 2. Add these to your dev `:dependencies`: -```clojure -[cider/piggieback "0.3.2"] -[figwheel-sidecar "0.5.16"] ; use here whatever the current version of figwheel is -``` + ```clojure + [cider/piggieback "0.3.9"] ; not needed for cider-jack-in-cljs + [figwheel-sidecar "0.5.16"] ; use here whatever the current version of figwheel is + ``` Keep in mind that figwheel 0.5.16 is the first to support piggieback 0.3. If you're using an older figwheel you should stick to piggieback 0.2.2 (which uses the old `com.cemerick/piggieback` package coordinates). -3. Add this to your dev `:repl-options`: +3. Add this to your dev `:repl-options` (not needed for `cider-jack-in-cljs`): -```clojure -:nrepl-middleware [cider.piggieback/wrap-cljs-repl] -``` + ```clojure + :nrepl-middleware [cider.piggieback/wrap-cljs-repl] + ``` -4. Start the REPL with `cider-jack-in-clojurescript` (<kbd>C-c M-J</kbd>) +4. Start the REPL with `cider-jack-in-cljs` (<kbd>C-c C-x (C-)j (C-)s</kbd>). Select +`figwheel` when prompted about the ClojureScript REPL type. 5. Open a browser to the Figwheel URL so that it can connect to your application. -You now have two nREPL connections, one for Clojure and one for ClojureScript. -CIDER will determine which to use based on the type of file you're editing. - You should also check out [Figwheel's wiki](https://github.com/bhauman/lein-figwheel/wiki/Using-the-Figwheel-REPL-within-NRepl). +### Using Figwheel-main + +!!! Note + + The instructions here assume you're using Leiningen. Adapting them to your + favourite build tool is up to you. + +You can also use [Figwheel-main](https://github.com/bhauman/figwheel-main) with CIDER. + +1. Add this to your dev `:dependencies`: + + ```clojure + [cider/piggieback "0.3.9"] ; not needed for cider-jack-in-cljs + ``` + +2. Add this to your dev `:repl-options` (not needed for `cider-jack-in-cljs`): + + ```clojure + :nrepl-middleware [cider.piggieback/wrap-cljs-repl] + ``` + +3. Start the REPL with `cider-jack-in-cljs` (<kbd>C-c C-x (C-)j (C-)s</kbd>). Select +`figwheel-main` when prompted about the ClojureScript REPL type. + +4. Select the Figwheel build to run when prompted for it. (e.g. `:dev`). + ### Using shadow-cljs Provided you've configured your project correctly you can simply use -`cider-jack-in-clojurescript` to use `shadow-cljs`. +`cider-jack-in-cljs` to use `shadow-cljs`. This will automatically start the shadow-cljs server and connect to it. You'll also be prompted for the build to use. @@ -186,9 +254,13 @@ npx shadow-cljs server And connect to it with `cider-connect`. +Lastly, if you already have a running server watching a build, for instance you +have already run `npx shadow-cljs watch :dev`, you can use the `shadow-select` +CLJS REPL and specify `:dev` when prompted. + [leiningen]: http://leiningen.org/ [boot]: http://boot-clj.com/ -[piggieback]: https://github.com/clojure-emacs/piggieback +[piggieback]: https://github.com/nrepl/piggieback [shadow-cljs]: https://github.com/thheller/shadow-cljs ## Working with `.cljc` files diff --git a/doc/code_completion.md b/doc/code_completion.md index a42c08ef..243a8ac8 100644 --- a/doc/code_completion.md +++ b/doc/code_completion.md @@ -1,10 +1,12 @@ CIDER provides intelligent code completion for both source buffers (powered by `cider-mode`) and REPL buffers. -Internally CIDER leverages -[compliment](https://github.com/alexander-yakushev/compliment) for Clojure and -[cljs-tooling](https://github.com/clojure-emacs/cljs-tooling) for ClojureScript. -Improvements to the two libraries automatically translate to improvements in CIDER. +!!! Note + + Internally CIDER leverages + [compliment](https://github.com/alexander-yakushev/compliment) for Clojure and + [cljs-tooling](https://github.com/clojure-emacs/cljs-tooling) for ClojureScript. + Improvements to the two libraries automatically translate to improvements in CIDER. ## Standard completion @@ -80,11 +82,13 @@ used to format the annotation can be 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`. -  +!!! Tip + + Completion annotations can be disabled by setting + `cider-annotate-completion-candidates` to `nil`. + ### Updating stale classes and methods cache Sometimes, the completion fails to recognize new classes that came with diff --git a/doc/configuration.md b/doc/configuration.md index 4cad2a1d..62ffcacc 100644 --- a/doc/configuration.md +++ b/doc/configuration.md @@ -153,7 +153,7 @@ You can hide all nREPL middleware details from `cider-browse-ns*` and `cider-apr 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" "^clojure.tools.nrepl")`, +Its default value is `'("^cider.nrepl" "^refactor-nrepl" "^clojure.tools.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 diff --git a/doc/debugging.md b/doc/debugging.md index 964ea419..11c83109 100644 --- a/doc/debugging.md +++ b/doc/debugging.md @@ -3,6 +3,12 @@ CIDER ships with a powerful interactive Clojure debugger inspired by Emacs's own  +!!! Warning "ClojureScript Support" + + The debugger currently **does not** support ClojureScript. See + [this issue](https://github.com/clojure-emacs/cider/issues/1416) + for more details. + ## Debugging The debugger can be invoked in several ways, the simplest one is to type @@ -140,9 +146,11 @@ C-M-x` or `C-u C-u C-c C-c`. ## Internal Details -*This section explains a bit of the inner workings of the debugger. It is -intended mostly to help those who are interested in contributing, and doesn't -teach anything about the debugger's usage.* +!!! Note + + This section explains a bit of the inner workings of the debugger. It is + intended mostly to help those who are interested in contributing, and doesn't + teach anything about the debugger's usage. The CIDER debugger works in several steps: @@ -8,8 +8,12 @@ Yes. ## What are CIDER's installation prerequisites? -CIDER officially supports Emacs 24.4+, Java 7+ and Clojure(Script) 1.7+. -CIDER 0.10 was the final release which supported Java 6 and Clojure 1.5 and 1.6. +CIDER officially supports Emacs 25.1+, Java 8+ and Clojure(Script) 1.8+. + + +!!! note + + CIDER 0.17 was the final release which supported Java 7 and Clojure(Script) 1.7. ## What's the relationship between CIDER and nrepl.el? @@ -34,7 +38,7 @@ command to start a REPL process for you. ## Isn't IntelliJ's Cursive the best Clojure IDE? -Cursive is pretty awesome. Depending on your programming preferences (using an IDE vs +Cursive is pretty awesome! Depending on your programming preferences (using an IDE vs building a custom editing experience tailored to your needs) it might be a better option for you than CIDER. @@ -43,6 +47,12 @@ option for you than CIDER. The codenames are usually some of the favourite places of CIDER's head maintainer (Bozhidar). +!!! Tip + + Bozhidar really loves Spain and the West Coast of the US, so he tends + to name really special releases with codenames related to them (e.g. + Seattle, California, Andalucia, etc). + ## Is using CIDER a good idea if I'm new to both Emacs and Clojure? There's nothing particularly complex in CIDER itself, but getting to @@ -74,10 +84,21 @@ when the most important refactoring functionality from our sibling project [clj-refactor](https://github.com/clojure-emacs/clj-refactor.el) lands into CIDER. +!!! Note + + While there's no exact roadmap for the 1.0 release, we do have *a* + [roadmap](https://github.com/clojure-emacs/cider/blob/master/ROADMAP.md). + ## Is it true that stable CIDER releases often happen around major Clojure conferences? Yep. We want to give people a reason to talk about CIDER at such events. :-) +!!! Tip + + Inviting Bozhidar or any other core CIDER developers to present at Clojure + conferences is likely going to results in more CIDER releases, + so you should totally do this! + ## How unstable is the MELPA build of CIDER? It's pretty stable. Serious regression are introduced rather rarely and are @@ -96,11 +117,16 @@ for the socket REPL. That's extremely unlikely. Even if we eventually add support for the new socket REPL, we'll continue supporting nREPL as well. +!!! Note + + Recently nREPL was migrated out of `clojure-contrib` and its development + has once again picked up. Check out nREPL's new home [here](https://github.com/nrepl/nREPL). + ## Is CIDER's nREPL middleware Emacs specific? Not at all. The functionality in `cider-nrepl` is pretty editor-agnostic and is utilized by various editor plugins. Some prominent examples would be -`vim-fireplace` and Eclipse's CCW. +`vim-fireplace` and Visual Studio Code's `calva`. ## How can I see all the configuration options available in CIDER? @@ -112,7 +138,7 @@ Sure! See [additional packages](additional_packages.md) for details. ## Where can I get help regarding CIDER? -See the [Support](support.md) section of the manual. +See the [Support](about/support.md) section of the manual. ## What should I do if I run into some issues with CIDER? diff --git a/doc/hacking_on_cider.md b/doc/hacking_on_cider.md index 6e23fef4..f260f519 100644 --- a/doc/hacking_on_cider.md +++ b/doc/hacking_on_cider.md @@ -12,17 +12,28 @@ simply clone the code from GitHub and use it. In general - avoid editing the code of an installed package. Alternatively you can simply load CIDER in your Emacs straight from its source -repo: +repo (you'll have to manually install all the packages CIDER depends on +in advance). + +Additionally you will have to generate and require the +[autoloads](https://www.gnu.org/software/emacs/manual/html_node/elisp/Autoload.html), +otherwise you'll keep getting errors about missing commands. That's done +automatically when installing via `package.el` but you'll have to do it +manually in this case: + +```shell +make autoloads # generates cider-autoloads.el +``` + +Then: ```el ;; load CIDER from its source code (add-to-list 'load-path "~/projects/cider") (require 'cider) +(require 'cider-autoloads) ``` -Just keep in mind that you'll have to manually install all the packages CIDER -depends on in advance. - ### Changing the code It's perfectly fine to load CIDER from `package.el` and then to start making @@ -127,14 +138,14 @@ And then switch to Emacs 26.1 and test again: ``` (emacs-25.3-travis) ~/cider$ evm use Emacs-26-pretest-travis -(emacs-26-pretest-travis) ~/cider$ cask install -(emacs-26-pretest-travis) ~/cider$ make test +(emacs-26.1-travis) ~/cider$ cask install +(emacs-26.1-travis) ~/cider$ make test ``` You can test byte compilation too ``` -(emacs-26-pretest-travis) ~/cider$ make test-bytecomp +(emacs-26.1-travis) ~/cider$ make test-bytecomp ``` When you are done working in docker, just `exit` the bash prompt, and the docker diff --git a/doc/index.md b/doc/index.md index 752aceda..65df2445 100644 --- a/doc/index.md +++ b/doc/index.md @@ -8,8 +8,14 @@ features are centered around `cider-mode`, an Emacs minor-mode that complements 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. +!!! Note + + CIDER was originally inspired by the powerful Common Lisp interactive + development environment [SLIME][]. In the beginning we started by + adapting SLIME's core functionality to Clojure, but over the course of time + CIDER became pretty different from SLIME in many areas. Check out + [this presentation](https://www.youtube.com/watch?v=4X-1fJm25Ww&list=PLZdCLR02grLoc322bYirANEso3mmzvCiI&index=6) + if you'd like to know more about CIDER's early history. **Please consider [supporting financially its ongoing development](about/contributing.md#funding).** @@ -28,10 +34,8 @@ using CIDER - you're constantly interacting with it and changing it. You can find more details about the typical CIDER workflow in the [Interactive Programming](interactive_programming.md) section. While we're a bit short on video tutorials, you can check out this -[tutorial about SLIME](https://www.youtube.com/watch?v=_B_4vhsmRRI) 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). +[into to CIDER](https://www.youtube.com/watch?v=aYA4AAjLfT0) to get a +feel about what do we mean by an "Interactive Development Environment". CIDER's built on top of [nREPL][], the Clojure networked REPL server. @@ -44,9 +48,14 @@ 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 -development environments as well (e.g. [vim-fireplace][] & [CCW][]). +interactive development environment like CIDER. + + +!!! Note + + Much of the middleware we originally + developed for CIDER is editor-agnostic and is being used by other Clojure + development environments as well (e.g. [vim-fireplace][] & [calva][]). CIDER packs plenty of features. Here are some of them (in no particular order): @@ -75,21 +84,20 @@ CIDER packs plenty of features. Here are some of them (in no particular order): * [Scratchpad](miscellaneous_features.md#using-a-scratchpad) * [Minibuffer code evaluation](miscellaneous_features.md#evaluating-clojure-code-in-the-minibuffer) * Integration with [company-mode][] -* [Support for working with multiple simultaneous nREPL connections](managing_connections.md) +* [Support for working with multiple REPLs](managing_connections.md)  -[nREPL]: https://github.com/clojure/tools.nrepl +[nREPL]: https://github.com/nrepl/nrepl [SLIME]: https://github.com/slime/slime -[swank-clojure]: https://github.com/technomancy/swank-clojure [Sly]: https://github.com/capitaomorte/sly [Geiser]: https://github.com/jaor/geiser [company-mode]: http://company-mode.github.io/ [leiningen]: http://leiningen.org/ [boot]: http://boot-clj.com/ -[piggieback]: https://github.com/clojure-emacs/piggieback +[piggieback]: https://github.com/nrepl/piggieback [vim-fireplace]: https://github.com/tpope/vim-fireplace -[CCW]: https://github.com/laurentpetit/ccw +[calva]: https://github.com/BetterThanTomorrow/calva [cider-nrepl]: https://github.com/clojure-emacs/cider-nrepl [clojure-mode]: https://github.com/clojure-emacs/clojure-mode [inf-clojure]: https://github.com/clojure-emacs/inf-clojure diff --git a/doc/installation.md b/doc/installation.md index 79712459..69338553 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -1,9 +1,10 @@ ## CIDER's nREPL middleware -Much of CIDER's functionality depends on the presence of CIDER's -own [nREPL middleware](https://github.com/clojure-emacs/cider-nrepl). Starting -with version 0.11, When `cider-jack-in` (<kbd>C-c M-j</kbd>) is used, CIDER -takes care of injecting it and its other dependencies. +Much of CIDER's functionality depends on the presence of CIDER's own +[nREPL +middleware](https://github.com/clojure-emacs/cider-nrepl). Starting +with version 0.11, When `cider-jack-in` (<kbd>C-c C-x (C-)j (C-)j</kbd>) is used, +CIDER takes care of injecting it and its other dependencies. **`profiles.clj` or `profile.boot` don't need to be modified anymore for the above use case!** @@ -34,12 +35,14 @@ Use the convenient plugin for defaults, either in your project's A minimal `profiles.clj` for CIDER would be: ```clojure -{:repl {:plugins [[cider/cider-nrepl "0.17.0"]]}} +{:repl {:plugins [[cider/cider-nrepl "0.18.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.** +!!! warning + + 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. #### Using Boot @@ -50,7 +53,7 @@ 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.17.0"]]) + concat '[[cider/cider-nrepl "0.18.0"]]) (swap! boot.repl/*default-middleware* conj 'cider.nrepl/cider-middleware) @@ -65,7 +68,7 @@ server with CIDER's own nREPL handler. ```clojure (ns my-app - (:require [clojure.tools.nrepl.server :as nrepl-server] + (:require [nrepl.server :as nrepl-server] [cider.nrepl :refer (cider-nrepl-handler)])) (defn -main @@ -75,8 +78,10 @@ server with CIDER's own nREPL handler. It goes without saying that your project should depend on `cider-nrepl`. -*** +!!! note -`x.y.z` should match the version of CIDER you're currently using (say `0.17.0`). -For snapshot releases of CIDER you should use the snapshot of the plugin as well -(say `0.17.0-SNAPSHOT`). + `x.y.z` should be compatible with the version of CIDER you're currently using. + The required version can be checked in `cider-required-middleware-version`. + Prior to CIDER 0.18, CIDER and cider-nrepl were always released together + and their versions had to match for things to work, but as the prominence + of cider-nrepl grew and many other tools started using, this was changed. diff --git a/doc/interactive_programming.md b/doc/interactive_programming.md index ba5ce55c..92906d01 100644 --- a/doc/interactive_programming.md +++ b/doc/interactive_programming.md @@ -22,28 +22,27 @@ Here's a list of `cider-mode`'s keybindings: `cider-eval-last-sexp-and-replace` |<kbd>C-c C-v w</kbd> | Evaluate the form preceding point and replace it with its result. `cider-eval-last-sexp-to-repl` |<kbd>C-c M-e</kbd> | 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. `cider-insert-last-sexp-in-repl` |<kbd>C-c M-p</kbd> | Load the form preceding point in the REPL buffer. -`cider-pprint-eval-last-sexp` |<kbd>C-c C-p</kbd> | Evaluate the form preceding point and pretty-print the result in a popup buffer. If invoked with a prefix argument, insert the result into the current buffer as a comment. -`cider-pprint-eval-defun-at-point` |<kbd>C-c C-f</kbd> | Evaluate the top level form under point and pretty-print the result in a popup buffer. If invoked with a prefix argument, insert the result into the current buffer as a comment. +`cider-pprint-eval-last-sexp` |<kbd>C-c C-v C-f e</kbd> | Evaluate the form preceding point and pretty-print the result in a popup buffer. If invoked with a prefix argument, insert the result into the current buffer as a comment. +`cider-pprint-eval-defun-at-point` |<kbd>C-c C-v C-f d</kbd> | Evaluate the top level form under point and pretty-print the result in a popup buffer. If invoked with a prefix argument, insert the result into the current buffer as a comment. `cider-eval-defun-at-point` |<kbd>C-M-x</kbd> <br/> <kbd>C-c C-c</kbd> | Evaluate the top level form under point and display the result in the echo area. `cider-eval-sexp-at-point` |<kbd>C-c C-v v</kbd> | Evaluate the form around point. `cider-eval-defun-at-point` |<kbd>C-u C-M-x</kbd> <br/> <kbd>C-u C-c C-c</kbd> | Debug the top level form under point and walk through its evaluation -`cider-eval-defun-to-point` |<kbd>C-c C-v z</kbd> | Evaluate the preceding top-level form up to the point. +`cider-eval-defun-up-to-point` |<kbd>C-c C-v z</kbd> | Evaluate the preceding top-level form up to the point. `cider-eval-region` |<kbd>C-c C-v r</kbd> | Evaluate the region and display the result in the echo area. `cider-interrupt` |<kbd>C-c C-b</kbd> | Interrupt any pending evaluations. `cider-macroexpand-1` |<kbd>C-c C-m</kbd> | 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`. `cider-macroexpand-all` |<kbd>C-c M-m</kbd> | Invoke `clojure.walk/macroexpand-all` on the form at point and display the result in a macroexpansion buffer. `cider-eval-ns-form` |<kbd>C-c C-v n</kbd> | Eval the ns form. -`cider-repl-set-ns` |<kbd>C-c M-n</kbd> | Switch the namespace of the REPL buffer to the namespace of the current buffer. +`cider-repl-set-ns` |<kbd>C-c M-n (M-)n</kbd> | Switch the namespace of the REPL buffer to the namespace of the current buffer. `cider-switch-to-repl-buffer` |<kbd>C-c C-z</kbd> | 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. `cider-switch-to-repl-buffer` |<kbd>C-u C-u C-c C-z</kbd> | Switch to the REPL buffer based on a user prompt for a directory. `cider-load-buffer-and-switch-to-repl-buffer` |<kbd>C-c M-z</kbd> | Load (eval) the current buffer and 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. -`cider-display-connection-info` |<kbd>C-c M-d</kbd> | Display default REPL connection details, including project directory name, buffer namespace, host and port. -`cider-rotate-default-connection` |<kbd>C-c M-r</kbd> | Rotate and display the default nREPL connection. +`cider-describe-connection` |<kbd>C-c M-d</kbd> | Display default REPL connection details, including project directory name, buffer namespace, host and port. `cider-find-and-clear-repl-output` |<kbd>C-c C-o</kbd> | Clear the last output in the REPL buffer. With a prefix argument it will clear the entire REPL buffer, leaving only a prompt. Useful if you're running the REPL buffer in a side by side buffer. `cider-load-buffer` |<kbd>C-c C-k</kbd> | Load (eval) the current buffer. `cider-load-file` |<kbd>C-c C-l</kbd> | Load (eval) a Clojure file. `cider-load-all-files` |<kbd>C-c C-M-l</kbd> | Load (eval) all Clojure files below a directory. -`cider-refresh` |<kbd>C-c C-x</kbd> | Reload all modified files on the classpath. If invoked with a prefix argument, reload all files on the classpath. If invoked with a double prefix argument, clear the state of the namespace tracker before reloading. +`cider-ns-refresh` |<kbd>C-c M-n (M-)r</kbd> | Reload all modified files on the classpath. If invoked with a prefix argument, reload all files on the classpath. If invoked with a double prefix argument, clear the state of the namespace tracker before reloading. `cider-doc` |<kbd>C-c C-d d</kbd> <br/> <kbd>C-c C-d C-d</kbd> | 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. `cider-javadoc` |<kbd>C-c C-d j</kbd> <br/> <kbd>C-c C-d C-j</kbd> | 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. `cider-grimoire` |<kbd>C-c C-d r</kbd> <br/> <kbd>C-c C-d C-r</kbd> | Lookup symbol in Grimoire. @@ -63,24 +62,31 @@ Here's a list of `cider-mode`'s keybindings: `cider-test-rerun-failed-tests` |<kbd>C-c C-t r</kbd> <br/> <kbd>C-c C-t C-r</kbd> | Re-run test failures/errors. `cider-test-show-report` |<kbd>C-c C-t b</kbd> <br/> <kbd>C-c C-t C-b</kbd> | Show the test report buffer. `cider-find-var` |<kbd>M-.</kbd> | Jump to the definition of a symbol. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol. +`cider-find-dwim-at-mouse` |<kbd>mouse-5</kbd> or <kbd>mouse-9</kbd> | Jump to the definition of a symbol using mouse. +`xref-pop-marker-stack` |<kbd>mouse-4</kbd> or <kbd>mouse-8</kbd> | Jump back to where `cider-find-dwim-at-mouse` was invoked. `cider-find-resource` |<kbd>C-c M-.</kbd> | Jump to the resource referenced by the string at point. `cider-find-ns` |<kbd>C-c C-.</kbd> | Jump to some namespace on the classpath. `cider-pop-back` |<kbd>M-,</kbd> | Return to your pre-jump location. `complete-symbol` |<kbd>M-TAB</kbd> | Complete the symbol at point. -`cider-quit` |<kbd>C-c C-q</kbd> | Quit the current nREPL connection. With a prefix argument it will quit all connections. +`cider-quit` |<kbd>C-c C-q</kbd> | Quit the current nREPL connection. -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`. +!!! Tip + + 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`.  -An even better solution would be to install [which-key][], which will -automatically show you a list of available keybindings as you start typing some -keys. This will simplify your interactions with CIDER quite a lot (especially in -the beginning). Here's what you'd see if you typed <kbd>C-c C-d</kbd> in a -Clojure buffer: + +!!! Tip + + An even better solution would be to install [which-key][], which will + automatically show you a list of available keybindings as you start typing some + keys. This will simplify your interactions with CIDER quite a lot (especially in + the beginning). Here's what you'd see if you typed <kbd>C-c C-d</kbd> in a + Clojure buffer:  diff --git a/doc/managing_connections.md b/doc/managing_connections.md index d425ad27..1b01c581 100644 --- a/doc/managing_connections.md +++ b/doc/managing_connections.md @@ -1,60 +1,113 @@ -## Overview - -You can connect to multiple nREPL servers using <kbd>M-x</kbd> `cider-jack-in` -(or `cider-connect`) multiple times. To close the current nREPL connection, use -<kbd>C-c C-q</kbd> (`cider-quit`). You can close all connections with -<kbd>C-u C-c C-q</kbd>. - -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). - -There's a handy command called `cider-toggle-request-dispatch`. You can use it -to quickly switch between dynamic and static request dispatch. A common use-case -for it would be to force temporary all evaluation commands to be using a -particular (the default) connection. - -You can display the current nREPL connection using <kbd>C-c M-d</kbd> -and rotate the default connection using <kbd>C-c M-r</kbd>. Another -option for setting the default connection is to execute the command -<kbd>M-x</kbd> `cider-make-connection-default` in the appropriate -REPL buffer. - -## Connection browser - -You can obtain a list of all active connections using <kbd>M-x</kbd> -`cider-connection-browser`. This buffer provides a few extra keybindings: - -Command |Keyboard shortcut | Description --------------------------------------|--------------------------------|------------------------------- -`cider-connections-make-default` |<kbd>d</kbd> | Make connection at point default. -`cider-connections-close-connection` |<kbd>k</kbd> | Close connection at point. -`cider-connection-browser` |<kbd>g</kbd> | Refresh connection browser. -`cider-connections-goto-connection` |<kbd>RET</kbd> | Visit connection buffer. -`cider-popup-buffer-quit-function` |<kbd>q</kbd> | Close window. - -## Switch to connection buffer - -The REPL buffers double as connection buffers. - -To switch to the relevant REPL buffer based on the Clojure namespace -in the current Clojure buffer, use: <kbd>C-c C-z</kbd>. You can then -use the same key combination to switch back to the Clojure buffer you -came from. - -The single prefix <kbd>C-u C-c C-z</kbd>, will switch you to the -relevant REPL buffer and set the namespace in that buffer based on -namespace in the current Clojure buffer. - -## Renaming connections - -To change the designation used for CIDER buffers use <kbd>M-x</kbd> -`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*`. +!!! Note + + Because connections map one-to-one to REPL buffers, for the purpose of this + section we use "REPL" and "connection" interchangeably. + +## Sessions + +CIDER maintains a grouped view of opened connections through [Sesman] +sessions. Each session is a collection of connections which share the same nREPL +server. + +Start new sessions with + + - <kbd>C-c C-x j j</kbd> `cider-jack-in-clj` + - <kbd>C-c C-x j s</kbd> `cider-jack-in-cljs` + - <kbd>C-c C-x j m</kbd> `cider-jack-in-clj&cljs` + + - <kbd>C-c C-x c j</kbd> `cider-connect-clj` + - <kbd>C-c C-x c s</kbd> `cider-connect-cljs` + - <kbd>C-c C-x c m</kbd> `cider-connect-clj&cljs` + +Add new REPLs to the current session with + + - <kbd>C-c C-x s j</kbd> `cider-connect-sibling-clj` + - <kbd>C-c C-x s s</kbd> `cider-connect-sibling-cljs` + +Session life-cycle management commands live in the [Sesman] map (<kbd>C-c +C-s</kbd>) + + - <kbd>C-c C-s s</kbd> `sesman-start` + - <kbd>C-c C-s r</kbd> `sesman-restart` + - <kbd>C-c C-s q</kbd> `sesman-quit` + +The command `sesman-start` wraps around all of the aforementioned `jack-in` and +`connect` commands. You can also invoke same functionality with <kbd>M-x</kbd> +`cider` or <kbd>C-c M-x</kbd>. + +To quit or restart individual connections use cider commands + + - <kbd>C-c C-q</kbd> `cider-quit` + - <kbd>C-c M-r</kbd> `cider-restart` + + +## Context Links + +Sessions can be linked to contexts (projects, directories and buffers) + + - <kbd>C-c C-s b</kbd> `sesman-link-with-buffer` + - <kbd>C-c C-s d</kbd> `sesman-link-with-directory` + - <kbd>C-c C-s p</kbd> `sesman-link-with-project` + - <kbd>C-c C-s u</kbd> `sesman-unlink` + +## Displaying Session Info + +Retrieve info on all linked with the current context sessions with <kbd>C-c C-s +i</kbd> (`sesman-info`). On <kbd>C-u</kbd>, display info for all CIDER +sessions. For the connection specific information use CIDER's built-in +`cider-describe-connection` (<kbd>C-c M-d</kbd>). + +An interactive view of all CIDER sessions is available through the +`sesman-browser` (<kbd>C-c C-s w</kbd>). + +## Current Session + +All CIDER commands (evaluation, completion, switching to REPL etc.) operate on +the relevant REPL within the current session. The current session is the most +relevant session among all linked session. Session relevance is decided by the +specificity of the linked contexts and recency of the REPL buffers. + +If the current context is linked to a single session then that session is the +current one. If multiple sessions are linked to a context (say, a project) then +the current session is the one containing the most recently viewed REPL. + +Links to more specific contexts have precedence. For example, if you have two +sessions linked to the same project and another to a directory within that +project, then the session linked to the directory is the current session. Thus, +again, there is no ambiguity. + +By default [Sesman] allows multiple simultaneous links to projects and +directories, but only one link per buffer. See `sesman-single-link-contexts` if +you would like to change that. + +## Current REPL + +The current REPL is the most relevant REPL from the current session. REPL relevance +is determined by the type of the current buffer. For example if the current +buffer is a `clj` buffer then a `clj` REPL is selected. Ambiguous situations could +arise when, for instance, there are multiple `clj` REPLs within a session, or +the current buffer is a `cljc` buffer and both `clj` and `cljs` REPLs exist in +the session. In such cases the current REPL is the most recently viewed REPL of +the relevant type. + +Switch to the current REPL buffer with <kbd>C-c C-z</kbd>. You can then use the +same key combination to switch back to the Clojure(Script) buffer that you came +from. + +The single prefix <kbd>C-u C-c C-z</kbd>, will switch to the current REPL buffer +and set the namespace in that buffer based on namespace in the current +Clojure(Script) buffer. + +## Customizing Session and REPL Names + +By default session names consist of abbreviated project name, host and port +(e.g. `project/dir:localhost:1234`). REPL buffer name consist of the session +name and the REPL type specification post-fix +(e.g. `*project/dir:localhost:1234(cljs:node)*`). + +You can customize session names with `cider-session-name-template` and REPL +names with `nrepl-repl-buffer-name-template`. See also +`cider-format-connection-params` for available formats. + + +[Sesman]: https://github.com/vspinu/sesman diff --git a/doc/miscellaneous_features.md b/doc/miscellaneous_features.md index e9f90aa7..499aedcc 100644 --- a/doc/miscellaneous_features.md +++ b/doc/miscellaneous_features.md @@ -97,7 +97,7 @@ minor mode) by writing `#light` before the `(def` and reevaluating it. ## Code reloading -`cider-refresh` wraps +`cider-ns-refresh` wraps [clojure.tools.namespace](https://github.com/clojure/tools.namespace), and as such the same [benefits](https://github.com/clojure/tools.namespace#reloading-code-motivation) @@ -105,7 +105,7 @@ and [caveats](https://github.com/clojure/tools.namespace#reloading-code-preparing-your-application) regarding writing reloadable code also apply. -Calling `cider-refresh` will cause all modified Clojure files on the classpath +Calling `cider-ns-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. @@ -118,11 +118,11 @@ and (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`: + successful reload, when using `cider-ns-refresh`: ```el -(setq cider-refresh-before-fn "user/stop-system!" - cider-refresh-after-fn "user/start-system!") +(setq cider-ns-refresh-before-fn "user/stop-system!" + cider-ns-refresh-after-fn "user/start-system!") ``` * These must be set to the namespace-qualified names of vars bound to functions @@ -131,22 +131,27 @@ and 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`. + displayed in the echo area after you call `cider-ns-refresh`. The same + information will also be recorded in the `*cider-ns-refresh-log*` buffer, along + with anything printed to `*out*` or `*err*` by `cider-ns-refresh-before-fn` and + `cider-ns-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 +* You can make the `*cider-ns-refresh-log*` buffer display automatically after you + call `cider-ns-refresh` by setting the `cider-ns-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): ```el -(setq cider-refresh-show-log-buffer t) +(setq cider-ns-refresh-show-log-buffer t) ``` * By default, all modified Clojure buffers are prompted to be saved. This - behaviour can be customized using `cider-save-files-on-cider-refresh`. + behaviour can be customized using `cider-ns-save-files-on-refresh`. + +In case `cider-ns-refresh` does not work for you the +`cider-ns-reload`|`cider-ns-reload-all` commands can be used instead: they will +evaluate the Clojure's out of the box `(require ... :reload|:reload-all)` at +the REPL. ## Tracing function execution @@ -203,8 +208,8 @@ at the spec browser.  -You can also type the command <kbd>M-x</kbd> `cider-browse-spec-all`. This command will prompt you for -a regex you can use to filter out the specs you are interested in, and will also take you to the spec browser. +You can also type the command <kbd>M-x</kbd> `cider-browse-spec-all`. This command will prompt you for +a regex you can use to filter out the specs you are interested in, and will also take you to the spec browser.  @@ -218,7 +223,7 @@ Keyboard shortcut | Description <kbd>p</kbd> | Go to previous spec. <kbd>e</kbd> | Generate an example for the current browser spec. -If your project contains a version of `org.clojure/test.check`, you can type <kbd>e</kbd> when browsing +If your project contains a version of `org.clojure/test.check`, you can type <kbd>e</kbd> when browsing a spec to generate and print an example of it.  diff --git a/doc/navigating_stacktraces.md b/doc/navigating_stacktraces.md index 9e71f3fa..14c3ff64 100644 --- a/doc/navigating_stacktraces.md +++ b/doc/navigating_stacktraces.md @@ -47,8 +47,9 @@ more permanent, you can do so by customizing the provide a direct link to the bug reporting page to help facilitate its diagnosis and repair. -Independently of the value of `cider-show-error-buffer` or `cider-stacktrace-suppressed-errors`, -the error buffer is always generated in the background. Use `cider-visit-error-buffer` to visit +Independently of the value of `cider-show-error-buffer` or +`cider-stacktrace-suppressed-errors`, the error buffer is always +generated in the background. Use `cider-selector` (`C-c M-s`) to visit this buffer. There are two more selective strategies for the error buffer: @@ -64,12 +65,17 @@ There are two more selective strategies for the error buffer: (setq cider-auto-select-error-buffer nil) ``` -* 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. +* Error buffer stacktraces may be filtered by default. Valid filter +types include `java`, `clj`, `repl`, `tooling`, and `dup`. There are +also "positive" filtering types. The value `project` will cause only +project frames to be shown or `all` will force all stackframes to be +shown. Note that `project` and `all` are mutually exclusive. Whichever +one is first will determine the behavior if they are both present. ```el (setq cider-stacktrace-default-filters '(tooling dup)) +;; or +(setq cider-stacktrace-default-filters '(project)) ``` * Error messages may be wrapped for readability. If this value is nil, messages diff --git a/doc/troubleshooting.md b/doc/troubleshooting.md index e29aead2..bbb579f9 100644 --- a/doc/troubleshooting.md +++ b/doc/troubleshooting.md @@ -15,8 +15,10 @@ Emacs features a super powerful built-in [Emacs Lisp debugger](http://www.gnu.org/software/emacs/manual/html_node/elisp/Edebug.html) and using it is the best way to diagnose problems of any kind. -Here's a [great crash course](https://www.youtube.com/watch?v=odkYXXYOxpo) on -using the debugger. +!!! Tip + + Here's a [great crash course](https://www.youtube.com/watch?v=odkYXXYOxpo) on + using the debugger. To debug some command you need to do the following: @@ -40,8 +42,10 @@ it is pretty simple: 2. Invoke some commands. 3. Get the report with <kbd>M-x</kbd> `profiler-report`. -If you intend to share the profiling results with someone it's a good idea to -save the report buffer to a file with <kbd>C-x C-w</kbd>. +!!! Tip + + If you intend to share the profiling results with someone it's a good idea to + save the report buffer to a file with <kbd>C-x C-w</kbd>. ## Commonly encountered problems (and how to solve them) @@ -139,21 +143,21 @@ effect of changes you have to restart Emacs. This is a warning displayed on the REPL buffer when it starts, and usually looks like this: -> **WARNING:** CIDER's version (0.12.0) does not match cider-nrepl's version (...). Things will break! +> **WARNING:** CIDER 0.18.0 requires cider-nrepl x.y.z+, but you're currently using cider-nrepl a.b.c. Things will break! -where `...` might be an actual version, like `0.10.0`, or it might be `not installed` or `nil`. +where `a.b.c` might be an actual version, like `0.17.0`, or it might be `not installed` or `nil`. The solution to this depends on what you see and on what you're doing. #### You see a number like `X.X.X`, and you're starting the REPL with `cider-connect` Your project specifies the wrong version for the cider-nrepl middleware. See the -[instructions](http://cider.readthedocs.io/en/latest/installation/#ciders-nrepl-middleware) +[instructions](http://docs.cider.mx/en/latest/installation/#ciders-nrepl-middleware) on the Installation section. #### You see `not installed` or `nil`, and you're starting the REPL with `cider-connect` To use `cider-connect` you need to add the cider-nrepl middleware to your project. See the -[instructions](http://cider.readthedocs.io/en/latest/installation/#ciders-nrepl-middleware) +[instructions](http://docs.cider.mx/en/latest/installation/#ciders-nrepl-middleware) on the Installation section. #### You see `not installed` or `nil`, and you're starting the REPL with `cider-jack-in` @@ -165,7 +169,7 @@ on the Installation section. If the above doesn't work, you can try specifying the cider-nrepl middleware manually, as per the -[instructions](http://cider.readthedocs.io/en/latest/installation/#ciders-nrepl-middleware) +[instructions](http://docs.cider.mx/en/latest/installation/#ciders-nrepl-middleware) on the Installation section. #### You see a number like `X.X.X`, and you're starting the REPL with `cider-jack-in` diff --git a/doc/up_and_running.md b/doc/up_and_running.md index 8098b3b3..8d7861e6 100644 --- a/doc/up_and_running.md +++ b/doc/up_and_running.md @@ -1,23 +1,22 @@ The only requirement to use CIDER is to have an nREPL server to which it may connect. Many Clojurians favour the use of tools like Leiningen, Boot or Gradle to start an nREPL server, but the use of one of them is not a prerequisite to -use CIDER (however, it *is* required if you want to use the `cider-jack-in` -command). +use CIDER. -## 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). +## Setting up a Clojure project (optional) 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.5.2+ or Boot -2.7.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: +for a particular Clojure project and connect to it automatically. Most +popular Clojure project management tools are supported by default - namely +Leiningen, Boot, `clj` (`tools.deps`) and Gradle. + +!!! Note + + This functionality depends on Leiningen 2.5.2+ or Boot + 2.7.0+. Older versions are not supported. + +Let's create a simple Clojure project using Leiningen now. Provided you've installed +it already, all you need to do is: ``` $ lein new demo @@ -27,52 +26,88 @@ The two main ways to obtain an nREPL connection are discussed in the following s ## Launch an nREPL server and client from Emacs -Simply open in Emacs a file belonging to your `lein` or `boot` project (like -`foo.clj`) and type <kbd>M-x</kbd> `cider-jack-in` <kbd>RET</kbd>. This will -start an nREPL server with all the project dependencies loaded in and CIDER will -automatically connect to it. +Simply open in Emacs a file belonging to your project (like `foo.clj`) and type +<kbd>M-x</kbd> `cider-jack-in` <kbd>RET</kbd>. This will start an nREPL server +and CIDER will automatically connect to it. + +!!! Note + + If it is a `lein`, `boot` or `tools.deps (deps.edn)` project nREPL will be + started with all dependencies loaded. Dependency auto-injection is currently + not support for Gradle projects. Alternatively you can use <kbd>C-u M-x</kbd> `cider-jack-in` <kbd>RET</kbd> to -specify the name of a `lein` or `boot` project, without having to visit any file -in it. This option is also useful if your project contains both `project.clj` -and `build.boot` and you want to launch a repl for one or the other. +specify the name of a `lein`, `boot` or `tools.deps` project, without having to +visit any file in it. This option is also useful if your project contains some +combination of `project.clj`, `build.boot` and `deps.edn` and you want to launch +a REPL for one or the other. -In Clojure(Script) buffers the command `cider-jack-in` is bound to <kbd>C-c M-j</kbd>. +!!! Tip + + In Clojure(Script) buffers the command `cider-jack-in` is bound to <kbd>C-c C-x (C-)j (C-)j</kbd>. For further customizing the command line used for `cider-jack-in`, you can change the following (all string options): - * `cider-lein-global-options`, `cider-boot-global-options`, `cider-gradle-global-options`: these are passed to the command directly, in first position (e.g. `-o` to `lein` enables offline mode). - * `cider-lein-parameters`, `cider-boot-parameters`, `cider-gradle-parameters`: these are usually tasks names and their parameters (e.g.: `dev` for launching boot's dev task instead of the standard `repl -s wait`). + * `cider-lein-global-options`, `cider-boot-global-options`, + `cider-clojure-cli-global-options`, `cider-gradle-global-options`: + these are passed to the command directly, in first position + (e.g. `-o` to `lein` enables offline mode). + * `cider-lein-parameters`, `cider-boot-parameters`, + `cider-clojure-cli-parameters`, `cider-gradle-parameters`: these + are usually tasks names and their parameters (e.g.: `dev` for + launching boot's dev task instead of the standard `repl -s wait`). + +Note that if you try to run `cider-jack-in` outside a project +directory normally you'd get a warning to confirm you really want to +do this, as more often than not you'd probably do this +accidentally. If you decide to proceed, CIDER will invoke the command +configured in `cider-jack-in-default`. This used to be `lein` prior to +CIDER 0.17 and it was switched to Clojure's CLI (`clj`) afterwards. + +!!! Tip + + You can set `cider-allow-jack-in-without-project` to `t` if you'd like to + disable the warning displayed when jacking-in outside a project. ## Connect to a running nREPL server -You can go to your project's directory in a terminal and type there: +Go to your project's directory in a terminal and type there: ``` $ lein repl ``` -Or: +Or for `boot`: ``` $ boot repl -s wait (or whatever task launches a repl) ``` -Alternatively you can start nREPL either manually or by the facilities provided by your -project's build tool (Maven, etc). +It is also possible for plain `clj`, although the command is somewhat longer: + +``` +$ clj -Sdeps '{:deps {cider/cider-nrepl {:mvn/version "0.18.0-SNAPSHOT"} }}' -e '(require (quote cider-nrepl.main)) (cider-nrepl.main/init ["cider.nrepl/cider-middleware"])' +``` + +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 -<kbd>M-x</kbd> `cider-connect` <kbd>RET</kbd> will allow you to connect to the +After you get your nREPL server running, go back to Emacs. Type there +<kbd>M-x</kbd> `cider-connect` <kbd>RET</kbd> to connect to the running nREPL server. -In Clojure(Script) buffers the command `cider-connect` is bound to <kbd>C-c M-c</kbd>. +!!! Tip + + In Clojure(Script) buffers the command `cider-connect` is bound to <kbd>C-c M-c</kbd>. You can configure known endpoints used by the `cider-connect` 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. -```el -(setq cider-known-endpoints '(("host-a" "10.10.10.1" "7888") ("host-b" "7888"))) +``` +(setq cider-known-endpoints + '(("host-a" "10.10.10.1" "7888") + ("host-b" "7888"))) ``` diff --git a/doc/using_the_repl.md b/doc/using_the_repl.md index f240b06d..e9888cfd 100644 --- a/doc/using_the_repl.md +++ b/doc/using_the_repl.md @@ -24,8 +24,6 @@ Keyboard shortcut | Description <kbd>M-p</kbd> <br/> <kbd>M-n</kbd> | Search the previous/next item in history using the current input as search pattern. If <kbd>M-p/M-n</kbd> is typed two times in a row, the second invocation uses the same search pattern (even if the current input has changed). <kbd>M-s</kbd> <br/> <kbd>M-r</kbd> | Search forward/reverse through command history with regex. <kbd>C-c C-n</kbd> <br/> <kbd>C-c C-p</kbd> | Move between the current and previous prompts in the REPL buffer. Pressing <kbd>RET</kbd> on a line with old input copies that line to the newest prompt. -<kbd>C-c C-x</kbd> | Reload all modified files on the classpath. -<kbd>C-u C-c C-x</kbd> | Reload all files on the classpath. <kbd>TAB</kbd> | Complete symbol at point. <kbd>C-c C-d d</kbd> <br/> <kbd>C-c C-d C-d</kbd> | 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 <kbd>C-c C-d j</kbd> <br/> <kbd>C-c C-d C-j</kbd> | 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. |