What is Counterclockwise ?

Counterclockwise is best described as an Integrated Development Environment for the Clojure language.
It is an extension of the popular Eclipse IDE.

Goals of Counterclockwise:

  • be as easy as possible for Clojure beginners

  • integrate nicely into the Eclipse IDE

Counterclockwise bundles everything for hacking Clojure Code:

  • Wizards for creating / importing existing Clojure projects from scratch or from Leiningen project definitions

  • Clojure Editor with advanced editing features

  • Starting Clojure REPLs, interacting between Clojure Editors and Clojure REPLs

  • Tight integration with Leiningen (Leiningen is the most popular build tool used for clojure projects)

Install Counterclockwise

Install as a Standalone Product

Current Version is 0.35.1.STABLE001

Pre-requisites

  • Java Virtual Machine (JVM) 8 installed and setup in the Operating System’s PATH

1. Download

Windows 32 Bits / Windows 64 Bits
Linux 32 Bits / Linux 64 Bits
OS X 64 Bits

2. Unzip

This will create a Counterclockwise-0.35.1.STABLE001 directory (application directory for OS X)

3. Start

Launch the Counterclockwise executable for your platform, located inside the Counterclockwise-0.35.1.STABLE001 directory

You may now want to create your first project or open an existing project.
Having a problem? Check the Configure Counterclockwise Section or the Troubleshooting page.

Install as an Eclipse Plugin

Pre-requisites

any Eclipse packaging which includes JDT (Java Development Tools) will work: "Eclipse SDK" package, "Eclipse for Java Developers" package, "Eclipse for Java EE Developers" package, etc.

Eclipse 3 (Indigo, Eclipse 3.8.x) is no longer supported, but you can still install a version < 0.30 of Counterclockwise

Counterclockwise is available via the Eclipse Marketplace Client: search for Counterclockwise or Clojure

You may now want to create your first project or open an existing project.
Having a problem? Check the Configure Counterclockwise Section or the Troubleshooting page.

Configure Counterclockwise

Proxy Settings (optional)

Currently Counterclockwise does not use the Window ▸ Preferences ▸ General ▸ Network Connections Proxy Preference for use with the embedded Leiningen.

So to make it use a proxy, you’ll have to create the appropriate environment variable(s) and make them available when you start the Counterclockwise / Eclipse executable.

  • http_proxy: URL of an HTTP proxy.
    e.g. http_proxy=http://username:[email protected]:port

  • https_proxy: URL of an HTTPS proxy.
    e.g. https_proxy=https://username:[email protected]:port

  • http_no_proxy: list of hosts for which the proxy just declared should be bypassed.
    e.g. http_no_proxy=".example1.com|.example2.com|*.example3.com"

See the Leiningen HTTP Proxies page for more detail.

Create your first project

  • Open the Java perspective (unnecessary step for Counterclockwise Standalone product users)

    • Window ▸ Open Perspective ▸ Java '''(a perspective is a predefined layout of views, suitable for a particular type of development)'''

  • Create a Clojure project

    • Menu File ▸ New ▸ Clojure Project, name it myproject

    • The project is created using the default Leiningen Template, which creates a Clojure project with a predefined myproject.core namespace in src/myproject/core.clj

  • Run the project:

    • Click on the editor pane containing the code in core.clj and then select Load file in REPL from the Clojure menu. This sends the whole file’s code to the REPL (and also takes care of starting a REPL for the project if none is currently started).

  • Switch to the REPL in the namespace of your file:

    • Click on the bottom of the REPL inside the "text input area"

  • Call your function (Hit Enter to send the expression if the cursor is at the end, or hit Ctrl+Enter / Cmd+Enter if the cursor is not at the end of the text):

;; Clojure 1.5.1
#<Namespace myproject.core>
#'myproject.core/foo
=> (foo "Hey")
Hey Hello, World!
nil

Create a new project

Use the wizard named Clojure Project.

  • Open File ▸ New ▸ Clojure Project (*)*

    • In the wizard, choose a project name (the project folder will be named after the project name), and a location for where to create the project folder (if you don’t like the default one)

  • "Leiningen template" field:

    • Leiningen is the de-facto build tool for clojure projects

    • By default it uses the "default" template

    • You can change it to use another lein-newnew template released somewhere in a maven repository (generally in clojars) ()*

Press the Finish button, that’s all. You have a fully working Leiningen project with its Java Build path (aka class path) managed by Counterclockwise.

()* Lein2’s Lein-newnew plugin allows you to create new leiningen projects from "project templates".
To find the list of currently available project templates, you can ask clojars for "lein-template" artifacts : https://clojars.org/search?q=lein-template

() If you don’t see the File ▸ New ▸ Clojure Project menu entry: check that you’re in the "Java" or "Plugin Development" Perspective ( Window ▸ Open Perspective ▸ …​ ) ** If you still don’t see the command, then Reset your Perspective ( Window ▸ Reset Perspective …​)

Open a project

Drag a folder from your OS filesystem browser (Windows Explorer, Nautilus, Finder, etc.) and drop it over Counterclockwise’s Window.

If the folder is a root folder containing many Leiningen-based projects, as many projects as found on the filesystem will be created in Counterclockwise.

This feature will only work correctly if Preference ▸ Clojure ▸ General ▸ Automatic detection of Clojure / Leiningen projects is enabled (which it is by default).
If the preference is disabled, it is possible to manually trigger leiningen detection via the contextual menu Configure ▸ Convert to Leiningen project.

Leiningen Support

Leiningen is the de-facto standard build tool used for Clojure projects.

Counterclockwise automatically detects Leiningen projects.

Project classpath management

Eclipse has its own way of managing the Classpath, and so does Leiningen. Counterclockwise reconciles the two:

  • A new node named "Leiningen dependencies" inside your project in the Package Explorer View

    • This is an addition to the classpath containing all dependencies (including transitive ones) declared in project.clj (a Classpath Container in Eclipse terminology):

    • It is automatically updated when changes in project.clj are detected (your changes, or changes you get by refreshing the project, merging from Git, etc.)

    • New dependencies are automatically downloaded from remote repositories (no need to call lein deps)

  • The source paths for the project’s class path have been adjusted, taking into account the contents of project.clj’s `:source-paths, :java-source-paths, :resources-paths, etc.

  • A new menu:Leiningen entry in the contextual menu of your project, with commands:

    • menu:Reset the project configuration : recreates from scratch the class path (Java build path in Eclipse terminology) of your project from `project.clj’s content. Useful if you’ve messed up with the class path manually.

    • menu:[Update dependencies] : Forces the "Leiningen dependencies" Classpath container to refresh itself (only, the other Classpath entries are not reset)

Of course, when you have an active REPL, and once a namespace from a dependency’s jar has been loaded in the REPL, you can open vars from this namespace as usual, via F3, Ctrl+Click / Cmd+Click in the REPL or from the editor, and also by double-clicking on the var from the Namespace Browser.

Native deps are also correctly supported. Meaning you can start hacking with Overtone or Quil and their Sound / OpenGL supports right now!!!

Generic Command launcher

It is possible to invoke arbitrary leiningen command, as if done from the command line, via the Alt+L L keyboard shortcut.

If called from a place in Eclipse where it’s possible to infer a current project (e.g. if called from the context of a clojure editor), the command will be issued from the project folder, and the popup will show the project name at the start of the line, before the $.

my-project $ lein <task>

If called from a place in Eclipse where no project has been inferred from the current context, then the command is initialized to work outside any project folder.

<noproject> $ lein <task>

The text <task> is already selected in the text input, ready to be replaced by the real command you want to invoke. Replace the text with the command, uberjar or do clean, uberjar for instance, then hit Enter.

Wait for a second, and see the Console View show the progress of the process' output. You can also interact with the process input stream by typing inside the Console View.

Keyboard Shortcuts for Leiningen Commands

Starting a Headless Leiningen REPL

Alt+L H is a shortcut for launching a headless leiningen REPL. It is similar to doing Alt+L L + typing your-project $ lein repl :headless.

Resetting the Project Classpath

Alt+L R resets the project classpath, using Leiningen to compute the classpath.

Updating the Project Dependencies

Alt+L U is a shortcut for updating the project dependencies in the classpath, using Leiningen

Clojure Support

Clojure Support (aka Clojure Nature in Eclipse terminology) is automatic.
It is triggered by the presence of the clojure.core namespace in the classpath.

It is possible, though, to fall back to a manual mode if this automatic feature does not work well in your configuration:

  • you can disable it from the Clojure ▸ General ▸ Automatic detection of Clojure project command in Eclipse Preferences.[1]

  • you can then enable Clojure support manually for a particular project via the Configure ▸ Convert to Clojure project command in project contextual menu.

  • once Clojure Support is added, a new menu:Clojure submenu appears in the project’s contextual menu.

  • to manually remove Clojure support, please use the Clojure ▸ Remove Clojure Support command in the project’s contextual menu.

Evaluate Clojure code

From a specific clojure file

  • Select the file

  • Select Run as clojure in its contextual menu

Note: a REPL will also be created. By default, if the selected file contains a (ns) call, the name of its namespace will be used. You can disable this behavior via the Clojure ▸ General ▸ Automatic namespace load on start and on save checkbox in the Eclipse Preference.[1]

Launch a REPL for the project

  • Select your project in the Package Explorer View

    • in the project’s contextual menu : Run as …​ ▸ Run configurations ▸ Clojure ▸ New

    • Press Run

  • A java process is started in the background, and a Console View is created in Eclipse for you to interact with it (view input/output, terminate the process, etc.)

  • A nRepl server is automatically launched is the java process, and a REPL View is created in Eclipse for you to interact with the nRepl server.
YOU MUST HIT Ctrl+Enter (Cmd+Enter on OS X) to send the expression for evaluation.
It is possible to configure which files should be automatically loaded on project java process startup.

Namespace Browser View

The Namespace Browser View displays all symbols of all namespaces of the active REPL.[2].
It allows you to jump to the definition of symbols in the relevant files (including inside jars): just double-click on the symbol name in the Namespace Browser View.

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

  • You can filter the Namespace Browser View’s tree to more easily find a symbol.
    Just type a regexp in the menu:[Find :] text zone at the top of the `Namespace Browser View    . It will filter the tree for those symbols matching the regex (also when the symbol documentation matches the regex).

  • To see the Namespace Browser View, you either

    • select it via the Window ▸ Show View ▸ Other ▸ Counterclockwise Views ▸ Namespace Browser menu

    • open the java perspective.

      The Namespace Browser View should be stacked behind the Outline View (if you are in the Java Perspective.[3] and don’t see the Namespace Browser View, you may reset the Java Perspective.footnoteref[perspective] to its default value via the Window ▸ Reset Perspective …​ menu, or find it manually via the Window ▸ Show View ▸ Namespace Browser menu)

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 feature uses this server to provide you with the most possible up to date information on Clojure Namespaces and their contents.

Debug Clojure code

  • Use the Eclipse Debugger Runner instead of the standard Runner (menu:[Debug as…​] menu instead of menu:[Run as…​] menu (the bug icon instead of the running man icon).

  • You place Breakpoints in Clojure Editors by double-clicking on the column located to the left of the text.

Edit Clojure code

Create a new Clojure file

Clojure files must be located in java source directories.

The Clojure Editor is automatically launched when double-clickin on .clj (Clojure), .cljs (ClojureScript) and .edn (EDN) files.

If you place Clojure files outside of a java source directory, you will not be able to load it via the REPL, select it as an automatically loaded file in the launcher customization wizard …​

  • To create a Clojure file/namespace, invoke the File ▸ New ▸ New Clojure file menu entry.

  • Inside a java source directory, follow the classical Clojure conventions to place your files, 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.

Clojure Editor Features

Syntax higlighting

  • Rainbow parenthesis (different colors for different nesting levels)

  • Higlights as an error closing parens/brackets which have no corresponding opening ones

You can customize Syntax Highlighting via the Clojure ▸ Colors and Fonts Eclipse Preferences.footnoteref[preferences]

Code Completion

Code Completion is automatically suggested as you type.

Counterclockwise does suggestions for Clojure namespaces and symbols.

Code Completion is really powerful, because it features "fuzzy completion".
Examples: - if you type defm, then defmacro will match - if you type dmcro, defmacro will also match - if you type c.c/dmcro, defmacro will match, and chances are you’ll get a shortest liste of suggestions as well

You can prevent automatic suggestion of completions via the Clojure ▸ Editor ▸ Auto Activate code Completion Eclipse Preference.footnoteref[preferences]
You would then activate Code Completion suggestions by typing Ctrl+Space (Windows / Linux) / Cmd+Space (OS X)

Macro Expansion

You can both get macroexpand-1 (Ctrl+hover over selection) like and macroexpand-all (Ctrl+Shift+hover over selection) like behaviours (but much prettier), via Hovers, by selecting the macro-call and typing

This works only if you have an active REPL connection where macroexpansion will be evaluated

Errors reporting

to be confirmed

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.

Keyboard Shortcuts

The Editor is really keyboard commands friendly. See the list of Keyboard Bindings: List of Keyboard Shortcuts

Interaction with a launched REPL

You’ll find the commands for interacting with a REPL from an Editor in the Keyboard Shortcuts page

cider-nrepl support

cider-nrepl and Clojure projects

cider-nrepl ( https://github.com/clojure-emacs/cider-nrepl ) is a community effort to provide editor-agnostic nREPL middlewares.
CounterClockWise is now able to use cider-nrepl middlewares for providing the same features available in the ccw.server lib, though not all features of cider-nrepl are exposed by CCW yet.

  • There is a Clojure Preference Preferences ▸ Clojure ▸ General ▸ Launch REPLs with cider-nrepl that is turned on by default.

  • This Preference automatically creates a cider-nrepl enabled REPL when you use the Clojure launchers via Run as …​ menus or contextual menus or keyboard shortcuts (e.g. Ctrl+Alt+S)

  • Note that if CCW detects cider-nrepl in the project classpath, then the project version will be used.

  • This works both for Leiningen projects or any Java project having the Clojure jar in their classpath.

CCW only works with cider-nrepl > 0.9.1

cider-nrepl and Clojurescript projects

More manual work is required if your project also has ClojureScript.

First add cider-nrepl and piggieback support for your project:

(defproject ...
  ;; cider-nrepl support
  :plugins [[cider/cider-nrepl "0.9.1"]]
  ; piggieback support for clojurescript nrepls
  :profiles {:dev {:dependencies [[com.cemerick/piggieback "0.2.0"]
                                  [org.clojure/tools.nrepl "0.2.10"]]
                   :repl-options {:nrepl-middleware
                                  [cemerick.piggieback/wrap-cljs-repl]}}})

Then you can a REPL in Counterclockwise as usual, e.g. from the project’s node or some clojure file.

Then invoke piggieback to start a Clojurescript REPL. Here’s an example with a Rhino REPL:

(cemerick.piggieback/cljs-repl (cljs.repl.rhino/repl-env))

The REPL is now a Clojurescript REPL. You now get code completion and documentation from the Clojurescript environment.

Auto-build feature

Once you have started a REPL for your project, and when the Project ▸ Build automatically menu entry is selected, Eclipse will use a background connection to this REPL to automatically compile and evaluate the files you edit.

Package your work

Distribute as a jar

  • Use the Eclipse File ▸ Export as Jar Wizard

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

There’s a community contributed Eclipse Plugin for this task, called Fat Jar.

Install the Fat Jar plugin

Once installed, to create an 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 the Main class is generated in the classes folder (e.g. a gen-class), then Fat Jar will not suggest it in the list of candidates, but you can still type its fully qualified named instead of triggering the candidates list.

If you also save the configuration via the corresponding button, it wil then be easy to invoke the same jar build later again.

Please refer to the Fat Jar plugin homepage for more detail

There is also an out-of-the-box "create Executable Jar" feature 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.

User Plugins

User Plugins allow you to customize Counterclockwise / Eclipse with Clojure!!

User Plugins are…​

  • Safe: plug / unplug user plugins by adding / deleting repos clones from ~/.ccw/

  • Dynamic: with the help of the ccw-plugin-manager user plugin, you can open your user plugins as regular Eclipse projects, use the Eclipse embedded REPL to interact with your current environment live, as usual with Clojure!

  • Powerful: user plugins are added to Counterclockwise’s classpath and can access the same Eclipse services Counterclockwise has access to.

  • Agile: updating a user plugin is as simple as 1. git checkout 2. Alt+U S (re[S]tart plugins)

Counterclockwise provided User Plugins

Counterclockwise ships with some User Plugins included:

In case you have already checked out a User Plugin in you ~/.ccw/ folder, yours will always take precedence over the one embeded in Counterclockwise (as long as you’ve kept the same directory name).

How User Plugins work

User Plugins must be placed in .clj files inside your ~/.ccw/ folder.

Content in ~/.ccw/ folder is processed as such:

  • Folder and subfolders are scanned breadth-first for the presence of .clj files

  • Everytime a folder contains a .clj file, it is considered a 'plugin' folder.

    • a plugin folder cannot contain nested plugin folders, only top-level scripts and non-top-level namespaces.

  • Plugin folders are processed in no specific order (plugins must be independent)

  • Processing a plugin folder consists of

    • placing the folder inside Counterclockwise’s classpath (so that you can use/require namespaces provided by the plugin)

    • launching all the .clj files located at the root of the plugin, one after the other, in no particular order

  • If a plugin has several scripts, one script failing does not prevent other scripts to execute

  • A plugin failing to load does not prevent other plugins to load

  • All contributions made by plugins to Eclipse (e.g. new commands) are managed by Counterclockwise: should the user plugin be removed, the contributions would be cleaned up automatically the next time the plugins folder is scanned.

The idea behind this layout is that users will share plugins via git repositories, and each plugin can directly be cloned into its own directory inside ~/.ccw/.

INFO: It is strongly suggested that User Plugins be available as git repositories. It then is natural to follow e.g. github organization for your user plugins inside ~/.ccw/: create a subfolder per github user/organization and clone respective repositories in respective folders. E.G. clone https://github.com/laurentpetit/ccw-plugin-manager.git inside ~/.ccw/laurentpetit/ccw-plugin-manager/.

INFO: a User Plugin is dynamic. To remove it, just delete its folder inside ~/.ccw/.

User Plugins List

Counterclockwise offers a number of User Plugins available as Github projects. Each one comes with a README file explaining its intent, status, installation and usage.

The User Plugins are repositories whose names start with ccw-plugin-. They are available on the ccw-ide github organization: https:/github.com/ccw-ide/.

HISP - Hello (world) In Small Pieces

Example 1: Hello World - single script file

~/.ccw/hello_world.clj
(ns ccw-plugin.hello-world
  (:require [ccw.eclipse :as e]
            [ccw.e4.dsl :refer :all]))

(defcommand greeter "Hello World from Counterclockwise" "Alt+U H"                          ; (1)
  [context]                                                                                ; (2)
  (e/info-dialog                                                                           ; (3)
    "Hello world from Counterclockwise" "This popup provided to you from a user script!"))
1 Give the command a name, a description, and a keybinding
2 A command implementation takes a context argument which in real-world situations can be used to gather contextualized information concerning the execution (what’s the current editor/view, the current selection, gather a preference value by key, etc.)
3 Body of the command implementation. Can do whatever you want.
defcommand is a macro from namespace ccw.e4.dsl. It dynamically contribute to the Eclipse Application Model. Those contributions are tagged specifically so that it is easy to manage them from CCW (automatic removal, for instance, should you remove the plugin, or update the command name, etc.)
The script is placed directly inside ~/.ccw/ to demonstrate how easy it is to start contributing. In real world situations you will probably create one folder per plugin.

Example 2: Hello World - script file and companion namespaces

Here the Hello World user plugin is placed in its own subdirectory.
This also demonstrates how to split a plugin into script + companion namespaces.

~/.ccw/ccw-ide/ccw-plugin-hello-world/hello-world.clj
(ns ccw-plugin.hello-world
  (:require [ccw.e4.dsl :refer :all]
            [user.greet :as g]))

(defcommand greeter "Hello World from Counterclockwise" "Alt+U H"
  [context]
  (g/greet-popup))
~/.ccw/ccw-ide/ccw-plugin-hello-world/user/greet.clj
(ns user.greet
  (:require [ccw.eclipse :as e]
            [user.util :refer (text)]))

(defn greet-popup []
  (e/info-dialog "Hello world" (text)))
~/.ccw/ccw-ide/ccw-plugin-hello-world/user/util.clj
(ns user.util)

(defn text [] "This popup provided to you from a user script")
the ccw-plugin-hello-world subdirectory will only be recognized as a plugin if there is no .clj file inside ~/.ccw/ and ~/.ccw/ccw-ide/

Report a problem with Counterclockwise

Mailing List

Cannot find answer to your problem in the documentation?

Feel free to ask the dedicated User' Google Group: http://groups.google.com/group/clojuredev-users

Activate Tracing

Counterclockwise can be more verbose on what’s going on if you active Tracing.

To activate Traces, follow this good Lars Vogel’s Tutorial

Test Menu

The Test Menu has the following use-cases in mind: help qualifying an issue and aid contributing some test to Counterclockwise. From Clojure ▸ Test ▸ Generator…​ you can launch what will allow you to record the UI steps needed to reproduce the problem and that most importantly will generate the necessary code for a ready-to-paste test case. This kind of contributions are very welcome as not only they provide feedback but also they consolidate the test code base.

1. Windows > Preferences on Linux and Windows, Eclipse > Preferences…​ on OS X
2. active-repl,The active REPL is the last REPL you interacted with
3. In Eclipse a Perspective is a named layout of Views. You can switch Perspectives while working, depending on the task at hand. Eclipse offers a Java Perspective and a Java Debugging Perspective among others