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
-
No Eclipse? Install as a Standalone Product
-
or Install as an Eclipse Plugin into an existing Eclipse
Install as a Standalone Product
Current Version is 0.35.1.STABLE001
Pre-requisites
|
1. Download |
Windows 32 Bits / Windows 64 Bits |
2. Unzip |
This will create a |
3. Start |
Launch the |
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
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)-
'''(a perspective is a predefined layout of views, suitable for a particular type of development)'''
-
-
Create a Clojure project
-
Menu
, name itmyproject
-
The project is created using the
default
Leiningen Template, which creates a Clojure project with a predefinedmyproject.core
namespace insrc/myproject/core.clj
-
-
Run the project:
-
Click on the editor pane containing the code in
core.clj
and then selectLoad file in REPL
from theClojure
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
(*)*
-
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.
( |
( |
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 |
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
(aClasspath 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
.
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 [1]
command in Eclipse Preferences. -
you can then enable Clojure support manually for a particular project via the
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
command in the project’s contextual menu.
Evaluate Clojure code
From a specific clojure file
-
Select the file
-
Select
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 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 :
-
Press Run
-
|
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
.
|
-
To see the
Namespace Browser View
, you either-
select it via the
menu -
open the java perspective.
The
Namespace Browser View
should be stacked behind theOutline View
(if you are in theJava Perspective
.[3] and don’t see theNamespace Browser View
, you may reset theJava Perspective
.footnoteref[perspective] to its default value via the menu, or find it manually via the 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 therunning 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
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 | 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 |
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
that is turned on by default. -
This Preference automatically creates a
cider-nrepl
enabled REPL when you use the Clojure launchers viaRun 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
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
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
-
updatesite: http://kurucz-grafika.de/fatjar/
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:
-
Hello World - https://github.com/ccw-ide/ccw-plugin-hello-world. Try Alt+U H, you should see a welcome popup in the pure Hello World style.
-
Zoom - https://github.com/ccw-ide/ccw-plugin-zoom. Try Cmd+] or kbd:[Cmd -, you should see the fonts sizes change accordingly.
-
User Plugins Manager - https://github.com/ccw-ide/ccw-plugin-manager. Try Alt+U, you should see several commands listed to restart user plugins, import them in the workspace, and even create a new user plugin from scratch.
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
(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.
(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))
(ns user.greet
(:require [ccw.eclipse :as e]
[user.util :refer (text)]))
(defn greet-popup []
(e/info-dialog "Hello world" (text)))
(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
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.