Setup The Ultimate Development Environment: Emacs, Clojure, Leiningen and Git

Clojure is a wonderful language.  And Emacs is an unbelievably powerful editor beast which you can easily get addicted to after you have tamed it.

However it's not easy for a newbie to customise Emacs to her needs.  I'll show you how to setup a full development environment for Clojure in Emacs with Git integration, Javadoc lookup and Leiningen powerful build tool for Clojure.  My examples will be for Ubuntu family (Ubuntu, Xubuntu, Kubuntu, Lubuntu) but you can easily use the idea for the Linux distro you use.

  1.  Install Emacs

Piece of cake! Fire up the terminal and issue the following:

$ sudo apt-get install emacs23

  2.  Install Leiningen
For a complete guide please see Leiningen on Github.

Download Leiningen installer script and put it in a directory.  I personally, have a Programs directory in my home; so I put the script in /home/bahman/Programs/Leiningen.  Change the permissions of the script to be executable either using your favourite file manager or using command line as below:

$ chmod +x DIRECTORY_YOU_HAVE_PUT_THE_SCRIPT_IN/lein

 Now at the command line, cd to the directory you have put the script in and run

$ ./lein self-install

and wait a short while for Leiningen to download the needed JAR files.

   3.  Install Slime
Now it's time to download Slime.  Remember that you cannot use the version shipped with your distro.  Only a specific version of Slime works with Leiningen.

At a command prompt run

$ git clone https://github.com/technomancy/slime/

and then copy the slime directory which git just created to the desired place.  Again, I put it under /home/bahman/Programs .

Now open ~/.emacs in your favourite editor and add this at the end of the file:

(add-to-list 'load-path "PATH_TO_SLIME/")
(add-to-list 'load-path "PATH_TO_SLIME/contrib/")
(require 'slime)
(slime-setup '(slime-fancy))
(slime-setup '(slime-repl))

  4.  Install Elpa (Emacs package manager)
For a more complete guide see Elpa installation guide.
Run Emacs.  In the *scratch* buffer type this

  (let ((buffer (url-retrieve-synchronously
        "http://tromey.com/elpa/package-install.el")))
  (save-excursion
    (set-buffer buffer)
    (goto-char (point-min))
    (re-search-forward "^$" nil 'move)
    (eval-region (point) (point-max))
    (kill-buffer (current-buffer))))

then press ALT+x and type eval-buffer.

Close Emacs.  Open ~/.emacs.d/init.el in your favourite text editor (create the file if it doesn't exist yet) and  paste this in the file to add Marmalade package repository to Emacs.

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

Open ~/.emacs too and add this at the end and save it.

(when
    (load
     (expand-file-name "~/.emacs.d/elpa/package.el"))
 (package-initialize))

Run Emacs.  Press ALT+x and type package-list-packages and hit ENTER.  A list of packages that can be installed is shown.  Navigate to a package named clojure-mode and press i followed by x.  Voila!  It's done!

  5.  Test Your Installation
At a command prompt (assuming you have added ~/.lein to your $PATH and have cd'ed to the desired directory) run $ lein new myproject.  Run Emacs.  Press ALT+x followed by cd.  Now enter the directory of the project you just created with Leiningen and hit ENTER.  Now type ALT+x again followed by clojure-jack-in.  If you get a warning about Slime version (just ignore it), this means that you have setup everything correctly so far.

  6.  Git Integration
If you haven't installed Git yet, run this at the command prompt to do so

$ sudo apt-get install git

 We'll use Egg for integration of Emacs and Git.  Clone the Egg repository like this

$ git clone https://github.com/bogolisk/egg.git

and copy the egg directory to ~/.emacs.d


Open ~/.emacs in your favourite editor and add this to the end of it

(add-to-list 'load-path (expand-file-name "~/.emacs.d/egg"))
(require 'egg)

Restart Emacs and it's all done.

  7. Javadoc Lookup
This is a real handy and neat feature: browsing Javadocs inside Emacs!

Fire up Emacs, press ALT+x and type package-list-packages followed by ENTER.  In the packages list, navigate to the package named javadoc-help.  Type x followed by i.  After the package is installed.  Open ~/.emacs in your favourite text editor and add this to the end of it to enable javadoc-help.

(require 'javadoc-help)

By default, javadoc-help opens the documentation pages in the default desktop Browser which is probably the almighty Firefox.  But it's better to read and navigate the docs inside Emacs itself.  To do so, you need to install a console-based browser named w3m and its Emacs interface.

$ sudo apt-get install w3m w3m-el-snapshot

Now let's configure Emacs to use w3m for browsing.  In Emacs, press ALT+x and type customize-variable followed by ENTER.  Then type browse-url-browser-function followed by ENTER. In the customisation buffer that just opened change the value of the "Value Menu" drop-down to "Your own function".  Then in the box in front of it type w3m-browse-url.  Then press both "Set for current session" and "Set for future sessions" buttons (make sure they are pressed!) and then press "Exit".

By default javadoc-help loads documentations from the internet but if you're on a slow connection like me, that's not an option.  To tell javadoc-help to load them from your hard drive, in Emacs press ALT+x and type javadoc-help followed by ENTER.  In the javadoc-help buffer press f and type the path to the local javadocs "api" directory and then press CTRL+g.

That's it!  From now on, anytime you need to check the documentation for a class just press ALT+x and type javadoc-lookup.

  8.  Final Word

You just setup your Emacs to become a powerful Clojure development environment.  But that's not all.  Emacs has many many more features which you can start to get your hands on by reading its comprehensive help pages.  But first start by reading Emacs Tutorial from the Help menu :-)

  9.  Stay Tuned!

I will share some of my useful customisations of Emacs, in a different post soon.