Emacs and Spacemacs for Clojure - Cheatsheet

A gateway drug to the wonderful world of Emacs and Spacemacs for Clojure users.

None of the following config is meant to be permanent, although it could be used as the basis of a personal emacs configuration. It’s meant as a basic setup so non-emacs users can try out emacs as simply and quickly as possible.

First some terminology

`M-`	the meta key. Usually defaults to alt/option
`C-`	control key
`S-`	shift key
`(....)`	Anything in parentheses is lisp code, run it with `M-S-;`
`nnn-nnn`	Kebab-case-names are emacs commands. Run them with `C-x`

Installing Clojure Specific Plugins

Clojure mode comes by default, but there are some other things that help. Most importantly, Cider. This is available from the melpa archive and the first step is to add that. There are several ways, but as emacs lisp is very closely related to Clojure and we can run lisp commands directly from emacs, the easiest way is to use that method. To do this call up the lisp interpreter by either of these:

M-x eval-expression M-S-;

Then enter the command you want to run. Ie:

(require 'package)
 (add-to-list 'package-archives'("melpa" . "http://melpa.org/packages/") t)
 (package-install 'cider)

Fetching the list of packages can take a while depending on network connection. Best to check it, if the last command fails, with:

M-x package-list-packages

You can now start a repl by navigating to a Clojure project root directory and running the following command:

M-x cider-jack-in

A Minimal Set of Commands. Just enough to get going…

Window Controls

Emacs by default will split windows so you can see multiple buffers at once. This behaviour can be changed, but to start with learning these basics:

`C-x o`	(the letter o) Switch to other window
`C-x 1`	close all other windows
`C-x 0`	(digit 0) close this window
`C-x 2`	split window horizontally
`C-x 3`	split window vertically

Opening Files

C-x C-d show directory listing

Note that sometimes this is bound to C-x d. The one you need is the one that DOESN’T say (brief) in the minibuffer. Try them both. The (brief) version is not useful.

<return> open file at point

Navigation

`C-e`	end of line
`C-a`	start of line
`C-n`	next line
`C-p`	previous line
`C-f`	forward
`C-b`	back
`C-v`	scroll screen down
`M-v`	scroll screen up

(arrow keys also work as expected. Ctrl-arrow gives bigger movements)

Cut and Paste

The emacs model for cut and paste predates the generally used C-c C-v convention. It is possible to modify this, but better to understand the emacs default behaviour first. A region is the text between the cursor and the “mark”. This can be cut and stored in the cut buffer and “yanked” back again.

`C-x`	space sets “mark”
`C-w`	cut region to cut buffer
`M-w`	copy region to buffer
`C-y`	yank from buffer (everyone else calls this paste)
`M-y`	cycle yanked region (ie paste earlier cuts)

Help

Emacs can provide all sorts of help, even straight out of the box. Here are some shortcuts:

`C-h f`	function-name Describe what function name does.
`C-h v`	variable-name Describe what a variable contains and what it controls.
`C-h k`	key-sequence Describe the function bound to key sequence.
`C-h b`	List the bindings for the current buffer.
`C-k i`	Emacs info. n,p,u,d to navigate here.
`C-k t`	Run the emacs tutorial

Other Essentials

`C-x C-s`	save
`C-x C-c`	quit emacs
`C-s`	search in file
`C-g`	cancel
`C-/`	Undo
`TAB`	show or make completions
`M-S-;`	execute lisp function.
`M-x <cmd>`	run cmd ie:
`(not bound)`	M-x rgrep – search in many files

That should be enough to actually get around and edit files and run Clojure functions either in the repl or directly from the files. Before continuing it’s worth adding a few helpful packages. These often have ready made keybindings, but not always. Most people will keep the bindings we have seen so far, but this is not possible for every combination of all possible packages. Commands can always be run using M-x and the command name though. Emacs will tell you if the command is already bound to a key and you can use that binding or re-bind it as you see fit.

Cider

Cider had a wealth of commands, none of which are bound to keys by default. At the very least it would be good to bind cider-jack-in to something. I would recommend C-c C-j but for now, just run them from M-x.

`cider-jack-in`	starts nrepl in the current directory and connects to it.
`cider-jack-in-cljs`	same but starts a clojurescript repl.
`cider-connect`	connects to a running repl instance.
`cider-eval-defn-at-point`	Evaluate the Clojure form around the point.
`cider-eval-last-sexp`	Evaluate the Clojure form preceding the point
`cider-repl-set-ns`	Switch the repl to the namespace of the current file.

Non-essential, but useful, additions

Paredit Mode

Makes life easier by strictly matching paren pairs. Not the only option, there are other similar packages worth investigating too. Install it with package-install and enable it for all Clojure files with these lisp commands:

(package-install ‘paredit) (add-hook 'clojure-mode-hook 'enable-paredit-mode)

Useful paredit commands:

`paredit-mode`	toggle paredit mode
`paredit-forward-slurp-sexp C-right`	(a\|)b -> (a b)\|
`paredit-forward-barf-sexp C-left`	(a \|b) -> (a\|) b
`Paredit-split M-S-s`	(a\|b)-> (a)\|(b)

Which-key

Makes finding half-remembered commands a whole lot easier

(package-install ‘which-key)
 (which-key-mode 1)

Now if you start to type a keybinding, all the options will appear in the mini-buffer. Try it by typing C-x. There are many useful commands starting with C-x.

Ivy

Improves searching for M-x commands.

(package-install ‘ivy) (setq ivy-use-selectable-prompt t) (ivy-mode 1)

Swiper

Makes searching in a file much easier

(package-install ‘swiper) (global-set-key "\C-s" 'swiper)

Smex and Counsel

Smex in counsel-mode gives a nice command history for M-x commands. Also, counsel provides many more overlays to built-in functions that are well worth exploring.

(package-install ‘smex) (smex-install) (package-install ‘counsel) (counsel-mode 1)

Problems

Lein not found?

You may need to add an entry to exec-path, which is what emacs uses to find executables for external commands. Some versions of emacs set this from $PATH, others don’t so if you have lein installed in your home directory you may need to add that to emacs’ exec-path.

(add-to-list 'exec-path "/Users/<me>/bin")

Stop the bell ringing

(setq ring-bell-function 'ignore)

Broken config file

Sometimes problems occur when editing emacs init files that stop it from booting properly. Moving/renaming it and starting with bare emacs again to fix the problem is one way to do it. I prefer this:

vi ~/emacs.d/init.el

`h`	cursor left
`j`	cursor up
`k`	cursor down
`l`	cursor right
`i`	insert text
`a`	append text
`esc`	exit insert mode
`:wq`	save and quit
`:q!`	exit without saving

What next?

All the preceding info is arranged to help try out emacs. Although emacs will remember certain things like the packages installed, it won’t automatically remember all the settings applied. Any lisp code that has been run using M-S-; can also be added to a startup file so it gets applied every time. The best starting place is ~/.emacs.d/init.el. This is the whole of the above setup in one place. This can be pasted into your init.el file:

(require 'package) (package-initialize) (add-to-list 'package-archives '("melpa" . "http://melpa.org/packages/") t) (package-install 'cider) (package-install 'paredit) (paredit-mode) (add-hook 'clojure-mode-hook 'enable-paredit-mode) (package-install 'which-key) (which-key-mode 1) (package-install 'ivy) (setq ivy-use-selectable-prompt t) (ivy-mode 1) (package-install 'swiper) (global-set-key "\C-s" 'swiper) (package-install 'smex) (smex-initialize) (package-install 'counsel) (counsel-mode 1)

You may prefer to only keep certain parts. There are also many good emacs starter packs, although there is a lot to be said for starting from scratch and only adding things you will actually use. Browse the available packages with this command:

C-x package-list-packages

Some other useful ones worth trying are:

magit
git-gutter
paradox
rainbow-parens
aggressive-indent-mode
evil
flycheck
google-translate
tetris
…

Spacemacs

Spacemacs is a self contained emacs setup. It has a curated set of packages and bindings and some might prefer this to setting up and tweaking their own system. It is also tailored to be easy for vi users to use, although this can also be done in regular emacs by installing evil-mode. Underneath it’s still just emacs so the basics are the same either way. Emacs must be installed and run as normal. Spacemacs is not a separate application.

A lot of the niceties detailed above are already included in spacemacs but installing cider is slightly different.

To setup spacemacs from scratch first remove all traces of emacs config files then install the spacemacs config to ~/.emacs.d:

cd ~ mv .emacs.d .emacs.d.bak mv .emacs .emacs.bak git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d

Try running emacs and let it install all the necessary packages. This may take a while and may also require exiting emacs and restarting. When it comes up clean, then cider can be added. Do this by editing ~/.spacemacs and adding clojure to the existing dotspacemacs-configuration-layers list and restarting. At this point most of the above information will apply.