This documentation is not a tutorial on Eclipse or on Java or on Clojure.
You may be a little bit familiar with eclipse, but we'll try not to use "eclipse jargon" just for fun. So please, if you find some explanations cryptic, tell us so that we can improve the docs!

Install Counterclockwise plugin

Pre-requisite: an Eclipse version including Java Support (e.g. with the JDT : Java Development Tools, as in Eclipse For Java Developers, Eclipse For RCP/RAP developers, Eclipse for JavaEE developers, etc.)

Update site : http://ccw.cgrand.net/updatesite/

There is a central place for installation procedure of all clojure IDEs.

You will find the counterclockwise's one here :

http://dev.clojure.org/display/doc/Getting+Started+with+Eclipse+and+Counterclockwise

As a bonus, you'll have the additional (optional) steps to install a clojure lab in counterclockwise (labrepl).

Having issues with the installer ?

Unsatisfied dependency ... org.antlr.runtime

Some people reported problems with the eclipse installer. The problem, as stated, is that eclipse can't manage to find the antlr required dependency.

One quick option you have is to manually install the missing antlr jar in your eclipse's plugin directory, restart eclipse (maybe with -clean option, but not absolutely necessary in a first try), and then try reinstalling Counterclockwise from the update site, as mentioned above.

For your convenience, we have placed the antlr plugin in the downloads section of Counterclockwise site : http://counterclockwise.googlecode.com/files/org.antlr.runtime_3.0.0.v200803061811.jar ( download page: http://code.google.com/p/counterclockwise/downloads/list )

Check that Counterclockwise is correctly installed

(optional step, do this if you have any doubt)

Go to menu Help > About Eclipse > Plugin details
Clic on plugin id column to sort by alphabetical ascending plugin id order. You should see plugins ccw.branding, ccw.clojure, ccw.clojurecontrib, ccw.core, ccw.debug, ccw.org.clojure.core.incubator, clojure.osgi, net.cgrand.parsley, net.cgrand.regex, org.clojure.tools.nrepl, paredit.clj in the list.

Enable Counterclockwise clojure's support

On a new project

Enable the java perspective via menu Window > Open Perspective > Other > Java
menu File > New > New Clojure Project
Enter a project name
Clic finish ... that's it !

On an existing java project

Display the context menu of the java project node in the project explorer
Select action "Enable/disable clojure language support"
You should have a popup feedback on the correct enabling/disabling of clojure for this project

What does it do

A clojure project is just a java project, with an added builder for clojure code.

By default, creating/enabling a clojure project will also check if you have clojure in your classpath, and if not, will add a dependency on Counterclockwise plugin's own embedded clojure version.

What can I customize ?

Everything you want as if you were in a classical java project. But you must of course always have clojure as a dependency of your project, but it can come in as many flavors as eclipse allows :

clojure source code directly embedded in your project (not recommended)
as another project in your eclipse. You then make the clojure project a dependency of you own project (recommanded if you want to keep in sync)

how to ?

First create a classic java project for the source code of clojure. You will have to change the default java source folder : you must have 2 of them, one will be src/jvm, the other will be src/clj
In a second project where you enabled clojure's support, do Project > Properties > Java build path > Projects > Add and add clojure's project

as a jarred library. use the classical java mechanism offered by eclipse to add this jar to you project ( Project > Properties > Java build path > Libraries ...

Launch Clojure code

From a specific clojure file

Select the file
in the contextual menu : Run as clojure

Note: a REPL will also be installed. By default, if the selected file contains a (ns) call, the name of its namespace will be used. A preference can controller whether this feature is active or not.

Launch a REPL for the project

Select your project's node
in the contextual menu : Run as ... > Run configurations > Clojure > New (in Clojure node's contextual menu)
Clic run

A console for the java process is started, and a REPL View is opened where you can type expressions for evaluation.

YOU MUST HIT Ctrl+ENTER (CMD+ENTER ON A MAC) to send the expression for evaluation.

Notes:

It is possible to configure the REPL launcher for loading a selection of clojure files on startup.
the REPL "flavor" you see is clojure-contrib's repl-ln

Use the namespace browser

The namespace browser will show you all symbols of all namespaces of the REPL you have launched, and allow you to jump to the source code defining them, if available (double clic on the symbol).

It also allows you to search the symbol you want by typing regexps in the "Find :" text zone, and choosing to do the search only on symbols names, or also on symbols documentation.

If you let the mouse hover a node in the browser, you will have the documentation, if available.

To see the namespace browser, you must

either select it via menu Window > Show View > Other > Counterclockwise Views > Namespace Browser
either open the java perspective. The namespace browser should be located behind the outline view by default (if you are in the java perspective and don't see the namespace browser, you may reset the java perspective to its default value via menu Window > Reset Perspective ...., or find it manually via menu Window > Show View > Namespace Browser

How does it work ?

When you have launched the REPL, Counterclockwise has embedded "server code" in the launched clojure environment. This server code is contacted by Counterclockwise to give information on the running clojure environment. The namespace browser uses this server to provide you with the most possible up to date info on the symbols.

Debug clojure code

Just use the out-of-the-box Eclipse debugger possibilities to launch your launch configurations (Debug instead of Run, the bug icon instead of the running man icon).

What you can currently do is being able to place breakpoints in clojure code edited either via the standard text editor either via the Counterclockwise clojure source code editor.

Edit clojure source code

By creating a new clojure file

Clojure files must be located in normal java source directories. If you place files with the .clj extension outside of a java source directory, then Eclipse will not see it on the classpath of the project, and you will not be able to load it via the REPL, select it as an automatically loaded file in the launcher customization wizard ...

You can use File > New > New Clojure file to create a clojure file

Inside the java source directory, follow the classical clojure conventions to place your file, according to the namespace it belongs to. (e.g. you want to create namespace 'tests.clojure.first , then create java package "tests.clojure", and create clojure file first.clj in it.

By importing existing code

Do as you would in a classic java project. Just remember to place all clojure files in a java source directory.

What features does the editor offer ?

Syntax higlighting

Rainbow parenthesis (different colors for different nesting levels)
Higlights in error closing parens that have no matching opening parens

Explanations on the default syntax coloring (currently not changeable by the user, but this will come soon):

the colors used are mostly the ones you will find in emacs clojure mode
only special symbols, and clojure.jar functions and macros are colorized.
java related symbols (Classes names, dot prefixed method call names) are in italic (to denote some sort of "exogene" parts in the code)
macros and special symbols, which most of the time denote special syntax constructs, are of the same color
functions have their own color
global vars intended to be rebound have their own color (e.g. all symbols starting and ending with a star '*')
explicit symbol type hint have their own color (e.g. #^String)
clojure literals (Strings, numbers, chars, etc.) have their own color
clojure keywords have their own color

Code completion

code completion is triggered using the out-of-the-box behaviour of Eclipse on your platform (Ctrl+Space on Windows/Linux/Mac)

clojure symbols (with or without prefixed namespace). You can use omni-completions on the symbol part. Examples:

defm -> defmacro ...
clojure.core/defm -> clojure.core/defmacro ...
w-o -> with-out ...

java calls via dot prefixed notation. Examples:

.toSt -> hundreds of .toString candidate
limits to the search (to prevent the IDE from hanging too long)

prefix must not be less than 3 characters
java search halts if more than 200 results are matched (only those

200 results are proposed, with a warning message at the bottom of the

BE AWARE it is still a bit slow for java completion (due to the fact that there is no type to narrow the search, it is done for any class type in the classpath !) This will be enhanced in a future release by allowing gradually more time consuming code completions (first try completion only for those classes imported in the namespace as symbols, and then, on user demand - by pressing space a second time - broaden the search to the entire set of classpath visible class types)

Errors reporting

In conjunction with auto-compile functionality, compilation problems are reported as problem markers : you see a summary of the problems in the problems view, you see the files that have problems in the package explorer, you see the problems at the correct line in the corresponding editor, you can jump to the editor at the correct line by double clicking on the problem in the problems view.

Lots of productivity enabling keyboard shortcuts

See this page: EditorKeyBindingsFeatures

Interaction with a launched REPL

See this page: EditorKeyBindingsFeatures

Running Tests

Hit Ctrl + T for automatic all of (run-tests) for namespace declared by editor, or namespace with same prefix as namespae declared by editor and ending with -test
REPL background color is changed to red, green or yellow (doesn't compile), based on the results

Auto-build feature

Once you have started a REPL for your project, eclipse will use a backdoor connection to this REPL to automatically compile and load the files you edit (if the eclipse Project > Build automatically option is selected, of course).

Package your work

Distribute as a jar

Use the classic Eclipse export as Jar wizard

Create a "fat" executable jar with all dependencies packaged into

It appears that someone created a useful Eclipse plugin to build executable jars from a java project.

Once installed, it also works from a Counterclockwise project out of the box!

Install the Fat Jar plugin

updatesite: http://kurucz-grafika.de/fatjar/
homepage: http://fjep.sourceforge.net) and it worked well

To create the executable jar, open the contextual menu of the project, and select the Fat jar menu entry.

The only trick is that if the class you want as Main is one generated in the classes folder, then Fat Jar fails to present it via the list activated by the button, but you can still type it fully qualified manually (e.g. my.package.MyMainClass), and it creates the jar correctly.

If you also save the configuration via the corresponding button, it is then easy to quickly repackage the app after the first time.

Please refer to the Fat Jar plugin homepage for more detail

N.B. : there is also out-of-the-box executable jar support in Eclipse, but we encountered problems with it when the main class is not located in the source folders of the project, as is the case when you generate the main class from a clojure namespace.