From 88f4fcf1d39a13ff336657b2cc4161ebb9d955d6 Mon Sep 17 00:00:00 2001 From: Bozhidar Batsov Date: Sat, 24 Feb 2018 19:07:27 +0700 Subject: Extend a bit the Troubleshooting section of the manual --- doc/troubleshooting.md | 43 +++++++++++++++++++++++++++++-------------- 1 file changed, 29 insertions(+), 14 deletions(-) (limited to 'doc') diff --git a/doc/troubleshooting.md b/doc/troubleshooting.md index ba924e88..3c5ddb9e 100644 --- a/doc/troubleshooting.md +++ b/doc/troubleshooting.md @@ -30,7 +30,22 @@ to see which command is associated with some keybinding) At this point you'll be dropped in the debugger and you can step forward until you find the problem. -## REPL not starting +## Profiling CIDER commands + +Emacs comes with a [built-in +profiler](https://www.gnu.org/software/emacs/manual/html_node/elisp/Profiling.html). Using +it is pretty simple: + +1. Start it with M-x `profiler-start`. +2. Invoke some commands. +3. Get the report with M-x `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 C-x C-w. + +## Commonly encountered problems (and how to solve them) + +### REPL not starting Make sure that your CIDER version matches your `cider-nrepl` version. Check the contents of the `*Messages*` buffer for CIDER-related errors. You should @@ -38,20 +53,20 @@ 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. -### Debugging the REPL init +#### Debugging the REPL init 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. -## Missing `*nrepl-messages*` buffer +### Missing `*nrepl-messages*` buffer nREPL message logging is not enabled by default. Set `nrepl-log-messages` to `t` to activate it. Alternatively you can use M-x `nrepl-toggle-message-logging` to enable/disable logging temporary within your current Emacs session. -## `cider-debug` complains that it “failed to instrument ...” +### `cider-debug` complains that it “failed to instrument ...” In the REPL buffer, issue the following. @@ -63,7 +78,7 @@ try to debug an expression (e.g., with C-u C-M-x). [File an issue](https://github.com/clojure-emacs/cider-nrepl/issues/new) and copy this information. -## Debugging freezes & lock-ups +### Debugging freezes & lock-ups Sometimes a CIDER command might hang for a while (e.g. due to a bug or a configuration issue). Such problems are super annoying, but are relatively easy @@ -77,7 +92,7 @@ This will bring up a backtrace with the entire function stack, including function arguments. So you should be able to figure out what's going on (or at least what's being required). -## Warning saying you have to use nREPL 0.2.12+ +### Warning saying you have to use nREPL 0.2.12+ CIDER currently requires at least nREPL 0.2.12 to work properly (there were some nasty bugs in older version and no support for tracking where some var was @@ -99,7 +114,7 @@ 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. -## Missing clojure-... function after CIDER update +### Missing clojure-... function after CIDER update Most likely you've updated CIDER, without updating `clojure-mode` as well. @@ -107,7 +122,7 @@ 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. -## I upgraded CIDER using `package.el` and it broke +### I upgraded CIDER using `package.el` and it broke 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 @@ -115,12 +130,12 @@ 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. -## I upgraded CIDER using `package.el` and nothing changed +### I upgraded CIDER using `package.el` and nothing changed Emacs doesn't load the new files, it only installs them on disk. To see the effect of changes you have to restart Emacs. -## CIDER complains of the `cider-nrepl` version +### CIDER complains of the `cider-nrepl` version This is a warning displayed on the REPL buffer when it starts, and usually looks like this: @@ -129,19 +144,19 @@ This is a warning displayed on the REPL buffer when it starts, and usually looks where `...` might be an actual version, like `0.10.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` +#### 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) on the Installation section. -### You see `not installed` or `nil`, and you're starting the REPL with `cider-connect` +#### 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) on the Installation section. -### You see `not installed` or `nil`, and you're starting the REPL with `cider-jack-in` +#### You see `not installed` or `nil`, and you're starting the REPL with `cider-jack-in` - Do `C-h v cider-inject-dependencies-at-jack-in`, and check that this variable is non-nil. - Make sure your project depends on at least Clojure `1.7.0`. @@ -153,7 +168,7 @@ manually, as per the [instructions](http://cider.readthedocs.io/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` +#### You see a number like `X.X.X`, and you're starting the REPL with `cider-jack-in` This means you're manually adding the cider-nrepl middleware in your project, but you shouldn't do that because `cider-jack-in` already does that for -- cgit v1.2.3