Quick Emacs / Clojure Windows Setup

Note: this is a snapshot in time - please check the official Getting Started with Emacs documentation on the Clojure wiki for the latest and greatest installation instructions. This informal guide may help you if you get stuck, but you're probably better off getting on the #clojure channel on Freenode IRC and asking for help there!

Last weekend I decided to try going back to Emacs for my Clojure development. By which I really mean, try going back to Emacs for all of my development, after a break of about twenty years. If you're new to Emacs, see the footnote at the end of this post.

I installed Emacs on my iMac first (which did not go well, for a variety of reasons, although I now have it working beautifully!), then I installed it on my Ubuntu netbook (which, apart from the pain of finding a way to get a build of Emacs 24, went pretty smoothly but then I got bogged down trying to get it connected to Leiningen - until the wonderful folks on #clojure helped me out!). So I figured I'd go for the trifecta and install it on Windows XP.

My feelings about Windows are pretty well known but I figured if I could get this running on Windows, so could anyone. This post outlines how I did it.

You're ultimately going to need a handful of downloads:

Technically you don't need wget or curl. They make installing Leiningen easier (via the self-install option) but they are useful command line utilities so it doesn't hurt to have them around.

Download Emacs, unzip it to c:\emacs and then run c:\emacs\bin\addpm.exe to add shortcuts to your Start Menu (optional but convenient). Go to your Start Menu and you should see a GNU Emacs folder (under All Programs probably) containing Emacs. Fire it up. Go thru the tutorial if you're not familiar with Emacs: ctl-h t

Download lein.bat and put it somewhere on your path. It is safest to right-click and "Save link as...". I put it in my home folder and edited my Path variable (Windows XP: Control Panel > System > Advanced > Environment Variables; Windows 7: Control Panel > System & Security > Advanced system settings > Advanced > Environment Variables) to add my home folder to the end.

Download wget or curl and put it somewhere on your path. I cheated a bit here and simply navigated into the curl folder before I did the next step so I didn't need it on my path (the current folder "." is searched for executables).

Install Leiningen's libraries. Open up a cmd console window and type: lein self-install

Note: It's possible you might get a message about MSCVCR100.DLL being missing. If so, the easiest solution will be to install the "Microsoft Visual C++ 2010 Redistributable Package" and try again. I don't have a link to that, but it was reported by one of the folks who reviewed this blog post before I published it!

Now you can try creating a new Clojure project and running some tests:

lein new myproject
cd myproject
lein test

Leiningen will automatically download the Clojure libraries the first time it needs them and put them in the lib folder in myproject. The tests will show a failure (in myproject.test.core, FAIL in (replace-me)) which is expected because we haven't changed the example generated test!

Now you can install swank-clojure for Leiningen. In your cmd console window, type: lein plugin install swank-clojure 1.3.3

Last step of installation is to tell Emacs about the marmalade repository, so it can find lots of new packages to install, and install clojure-mode. I actually did this in Emacs by way of getting used to editing with it. This is a bit tricky because the location Emacs uses for it's configuration is going to depend on your version of Windows. For me, on Windows XP, Emacs considers c:\Documents and Settings\Sean Corfield\Application Data to be my home folder. On Windows 7, that will be C:\Users\{username}\AppData\Roaming. If Emacs has not already created a folder called .emacs.d there, you can create it manually using the md command in your cmd console window, e.g.,:

cd "c:\Documents and Settings\Sean Corfield\Application Data"
md .emacs.d

Now, in Emacs, visit the file init.el in that folder. ctl-x ctl-f pulls up the Find file: dialog in the "minibuffer" at the bottom of the screen. If you're new to Emacs, this is a good opportunity to experiment with typing to perform incremental searches and pressing delete (or backspace) to navigate back up the file tree. You can also press tab to do autocompletion. When you try to visit a file that doesn't exist, Emacs will ask you to confirm creation of it (after typing the new filename, press return to get the confirmation and return again to confirm and create the file. Now you need to tell Emacs about the marmalade repository. Type the following text:

(require 'package)
(add-to-list 'package-archives
	     '("marmalade" . "http://marmalade-repo.org/packages/") t)
(package-initialize)

Press ctl-x ctl-s to save the file. Now you can either quit and restart Emacs or, if you're feeling adventurous, you can tell Emacs to execute each form. Navigate to the end of each form and press ctl-x ctl-e (that's lines 1, 3 and 4).

Now you can install clojure-mode! Press alt-x and start typing package-list-packages until it autocompletes, then press return. You'll see messages about contacting elpa and marmalade and then a long list of packages will appear in a buffer. Search for clojure-mode - press ctl-s and start typing clojure-mode until it is highlighted. Press ctl-a which will drop you out of search mode and move the cursor to the start of the line. Press i to mark clojure-mode for installation and then press x to execute. You'll get a bunch of warnings as it compiles clojure-mode.el which can be ignored.

That's the long way to install a package. I provided that so you can see just how many packages there and so you'd know how to browse them. If you know the name of a package, you can install it directly by pressing alt-x and typing package-install, press return, enter the name of the package to install and press return again.

Finally, we should be able to open a Clojure REPL! Open the project.clj file in the example Leiningen project you created earlier (use ctl-x ctl-f to find and visit the file). Now press alt-x and start typing clojure-jack-in until it autocompletes and press return. You'll see a message about starting a swank server and you should get a new buffer called *slime-repl with a user> prompt in it. You can type Clojure code into the REPL and evaluate it. See the README on the swank-clojure project for keyboard shortcuts that let you move between Clojure code in a file buffer and the REPL. Happy hacking!

Emacs? Srsly? Yes, Emacs has been around forever and is still being actively maintained. Emacs existed before we had point'n'click GUIs and it still carries that legacy: everything is keyboard based, including copy'n'paste, so it's a very different beast than most developers are used to. The lack of a mouse-driven GUI means a couple of benefits that you might not have considered: Emacs runs identically on every platform - including the control- / alt- keyboard shortcuts - so muscle memory can let you switch between machines without tripping over O/S-level differences in key conventions. In addition, since everything is keyboard based, you don't have to take your hand off the keyboard to click or scroll or otherwise interact with the mouse. That's all assuming you make the effort to learn the keyboard shortcuts. Emacs predates our modern copy / cut / paste conventions so have to get used to alt-w (copy) / ctl-w (cut) / ctl-y (paste, aka "yank") and of course you highlight text via the keyboard so you navigate to one end of your selection, mark it (ctl-space), navigate to the other end and copy or cut. There are shortcuts to make navigating around your code faster but, again, you need to invest time in learning a lot of keyboard shortcuts! Fortunately, Emacs also has a built-in help system that lets you look things up by command name, key binding and "apropos" - showing help related to a topic - all without taking your fingers off the keyboard or switching to another application!

Why bother? Emacs is truly the Swiss Army Knife of editors. As I'm writing this blog post in one buffer, my other buffers on screen contain: active tail of a Tomcat log file, a shell session where I've been running builds, a CFC I was editing, an IRC session (#clojure on irc.freenode.net) and two buffers show my git status and my git command results. Nearly 800 packages / extensions are available on two common repositories that address almost everything you can imagine - including using Emacs as an email client (and news client) and because of this extensibility, it supports nearly every programming language you can imagine. If you still want to extend or customize Emacs beyond that (which almost every regular Emacs user seems to do), you can do so using a dialect of Lisp. Yes, Emacs is programmed in Lisp! And that, ultimately, is why a lot of Clojure developers use Emacs...