Counterclockwise User Documentation

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:

Counterclockwise bundles everything for hacking Clojure Code:

Install Counterclockwise

Install as a Standalone Product

Current Version is 0.28.1.STABLE001

Pre-requisites

  • Java Virtual Machine (JVM) 7 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.28.1.STABLE001 directory (application directory for OS X)

3. Start

Launch the Counterclockwise executable for your platform, located inside the Counterclockwise-0.28.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

  • Java Virtual Machine (JVM) 7 running Eclipse

  • Eclipse 4.3 (Kepler) highly recommanded. Eclipse 3.7 (Indigo) still supported.

    • any packaging including JDT (Java Development Tools) will do: "Eclipse SDK" package, "Eclipse for Java Developers" package, "Eclipse for Java EE Developers" package, etc.

TL;DR

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:password@proxy:port

  • https_proxy: URL of an HTTPS proxy.
    e.g. http://username:password@proxy: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

;; 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.

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 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

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:

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

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)

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

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 Flat 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

This feature only works with Counterclockwise Standalone or Counterclockwise installed as a plugin on an Eclipse 4 installation.

It is possible to extend Counterclockwise / Eclipse yourself using the Clojure programming language.

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

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

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: a User Plugin is dynamic. To remove it, just delete its folder inside ~/.ccw/.

Examples

Example 1: Hello World - single script file

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

(def msg
  "This popup provided to you from a user script")

(defn greet [context]                                ; 1
  (e/info-dialog "Hello world" msg))

(defcommand greeter "Hello from CCW")                ; 2
(defhandler greeter greet)
(defkeybinding greeter "Ctrl+Alt+Y")
1 greet is the function that implements the command behavior, it 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.)
2 defcommand, defhandler and defkeybinding are macros from namespace ccw.e4.dsl. They 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/hello-world/hello_world.clj
(ns hello-world
  (:require [ccw.e4.dsl :refer :all]
            [user.greet :as g]))

(defn greet [context] (g/greet-popup))

(defcommand greeter "Hello from CCW")
(defhandler greeter greet)
(defkeybinding greeter "Ctrl+Alt+Y")
~/.ccw/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/hello-world/user/util.clj
(ns user.util)

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

Example 3: Dynamic Reload of User Plugins

A somewhat meta example, which shows that User plugins have access to Counterclockwise Internals.
This plugin adds a command that calls Counterclockwise’s start-user-plugins function to dynamically reload user plugins without the necessity to restart the IDE.

~/.ccw/plugin-additions/reload.clj
(ns reload
  (:require [ccw.e4.dsl :refer :all]
            [ccw.eclipse :as e]
            [ccw.core.user-plugins :as p]))

(defn reload [context]
  (try
    (p/start-user-plugins)
    (e/error-dialog "User plugins"
      "User plugins have been restarted successfully!")
    (catch Exception e
      (e/error-dialog"User plugins" (str
        "An error occured while starting User plugins: \n"
        (.getMessage e))))))

(defcommand start-user-plugins "Start/restart user plugins")
(defhandler start-user-plugins reload)
(defkeybinding start-user-plugins "Alt+U S")

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