Configuring Eclipse for Clojure

27.05.2014 Permalink

In preparation of the upcoming Eclipse Demo Camp in Bonn, I recently played around with Counterclockwise (CCW) and Eclipse Luna settings to enable a workflow within Eclipse that is similar to what I'm used to in Emacs.

It's really not too complicated if you have an idea what you want to have at the end, because CCW already provides almost everything out-of-the-box. This is my wishlist:

Tight integration with a REPL: I want to quickly copy code between source files and the REPL, switch current REPL namespace from within the editor, recompile selected s-expressions, toplevel sexps or the whole editor contents.
Structural editing a.k.a Paredit, which means my edit commands target s-expressions surrounded by parentheses or other types of brackets, not lines of code. I want to slurp, barf, split, join and raise based on s-expressions.
Switch between REPL and editor with one shortcut, and copy code between them.
Auto-completion on demand.
Quick execution of unit tests.
I like to have the source on the left and the REPL on right. But I need to change this to a top-bottom layout in case where I need to see a web browser or other window simultaneously.
Use a dark color theme to give my eyes a rest.

To summarize, I was able to get everything on this list, only unit test execution is more cumbersome in Eclipse. Here's a screenshot:

Looks pretty cool compared to standard Eclipse, eh?

Follow the instructions

To get the software in place,

Download Eclipse Luna as developer build, or after June 2014 as regular download.
Unzip it and start Eclipse. Go to Help / Install new software.
Install CCW from the update site.
Install the dark theme Moonrise from its update site.
Get the nice Eclipse Color Themes via plugin from their update site.

Now after installation and Eclipse restart, you need to change some preferences. Go to Eclipse Preferences:

In General / Appearance: Select the theme "Moonrise (standalone)".
Under Appearance go to Color Theme and select Oblivion, or any other dark theme you like.
Within the preferences Clojure tree, select brighter REPL colors under Colors and Fonts.
In Clojure / Editor switch Start editors in strict/paredit mode ON, and Auto-activate Code Completion OFF.
In Clojure / REPL View switch Show Hints OFF.
In General / Editors / Text editors set the Selection background color to a brighter value.

That's it. You're ready to play.

Starting a project and getting into the flow

You can simply type Ctrl-N, enter "Clojure" and select the "Clojure Project" option. Enter the project name, for example "helloworld". The dialog also allows you to select a Leiningen template, but you can ignore that. Open the source file in src/helloworld/core.clj. Type Alt-Shift-X C to start the REPL. (If you're Mac user please see shortcuts below.) Drag the REPL view to the top-right and make the right side wide enough.

Type in the REPL input area (foo "Clojure") and press Ctrl-ENTER. You should see the output appearing in the upper part of the REPL view. Switch to the editor with Ctrl-F7, change the println expression, and hit right there Ctrl-ENTER to recompile the foo function. You should see #'helloworld.core/foo appearing in the REPL output area.

Now, switch back to the REPL with Ctrl-F7 and recall the last expression with Ctrl-Up. Press Ctrl-ENTER to evaluate the expression. The REPL output should reflect your change.

Continue.

Keep your hands on the keyboard, please!

I know, programming is about thinking, not typing, but fast feedback using the REPL is a crucial part of the Clojure workflow. You'll have to learn to control your tools solely by keyboard, otherwise exploration of ideas will get so time-consuming that you tend to give up too early instead of finding the best way.

Here are the shortcuts you should really train yourself:

PC	Mac	Function
Movement between views / tabs
`Ctrl-F7`	`Cmd-F7`	Change active view
`Ctrl-PageUp`	`Ctrl-PageUp`	Previous Tab
`Ctrl-PageDown`	`Ctrl-PageDown`	Next Tab
REPL interaction from editor
`Alt-Shift-X C`	`Alt-Cmd-C`	Start REPL
`Ctrl-Alt-S`	`Alt-Cmd-S`	Load whole editor contents
`Ctrl-Alt-N`	`Alt-Cmd-N`	Switch REPL to files namespace
`Ctrl-Enter`	`Cmd-Enter`	Eval (toplevel or selected) sexp
In the REPL
`Ctrl-Enter`	`Cmd-Enter`	Eval sexp
`Ctrl-Up`	`Ctrl-P`	Recall previous command in REPL history
`Ctrl-Down`	`Ctrl-N`	Recall next command in REPL history
Selecting expressions
`Alt-Shift-Right`	`Shift-Cmd-Right`	Expand selection to next sexp
`Alt-Shift-Left`	`Shift-Cmd-Left`	Expand selection to previous sexp
`Alt-Shift-Up`	`Shift-Cmd-Up`	Expand selection to enclosing sexp
`Alt-Shift-Down`	`Shift-Cmd-Down`	Narrow selection
Structural editing
`Ctrl-0 S`	`Cmd-0 S`	Forward slurp
`Ctrl-0 B`	`Cmd-0 B`	Forward barf
`Ctrl-9 S`	`Cmd-9 S`	Backward slurp
`Ctrl-9 B`	`Cmd-9 B`	Backward barf
`Alt-R`	`Alt-R`	Raise selected sexp
`Alt-S`	`Alt-S`	Split sexp
`Alt-J`	`Alt-J`	Join sexps
`Ctrl-I`	`Cmd-I`	Reindent selected sexp
Cursor movement
`F3`	`F3`	Goto declaration
`Ctrl-J`	`Cmd-J`	Incremental search
`Ctrl-L`	`Cmd-L`	Goto line
`Ctrl-Alt-A`	`Alt-Cmd-A`	Jump before toplevel sexp
`Ctrl-Alt-E`	`Alt-Cmd-E`	Jump after toplevel sexp
`Ctrl-Shift-P`	`Shift-Cmd-P`	Jump to matching bracket
Leiningen
`Alt-L L`	`Alt-L L`	Mini lein command line

To learn more about existing shortcuts go to Eclipse Preferences / General / Keys and type in "Clojure" as filter text. This should give you a list of all Clojure relevant shortcuts.

Unit test execution

I wasn't able to find any clojure.test integration in Eclipse. Which brings us back to the REPL. If you're about to create new tests then you can certainly use (run-tests) in the test namespace. In order to execute tests as a regression for a specific namespace, e.g. helloworld.core-test from wherever you are, you could issue a command like this:

(do (require 'clojure.test 'helloworld.core-test)
    (clojure.test/run-tests 'helloworld.core-test))

Since this is a little awkward to type in, you can help yourself with an injection in your ~/.lein/profiles.clj file as demonstrated in this Gist. This allows you to use

(user/test-ns 'helloworld.core-test)

instead, and through the REPL command history you can quickly re-execute it anytime. Or you put a similar injection into your project.clj that already "knows" all test namespaces.

Recap

Eclipse is originally a Java IDE, which brings its plethora of tools, views and stuff that tends to distract you from the code. Therefore you need to rearrange the perspective a bit to bring the REPL and your code into the focus again. Emacs with the right setup allows for an almost clutter-free look, which I prefer over Eclipse. Emacs also excels when it comes to keyboard control (basically it offers no other reasonable option). But after all: if you trained yourself to use the keyboard in Eclipse as much as possible then you will experience the same flow with Eclipse that I have with Emacs.