Clojure Quickstart with Sublime Text 2

The 2012 State of Clojure Survey shows that there is a general issue with barriers to entry for new Clojure developers, and that amongst them Emacs (venerable and revered though it is) is one of them. While it's experience with eLISP undoubtedly makes it a superior LISP IDE, the main complaint is (as always) that it's just finicky and difficult to learn, and that learning Clojure is bad enough but having to learn Clojure and a finicky editor is just too much.

Having used Emacs and Eclipse Counterclockwise for Clojure development, I've now settled on Sublime Text 2 as my editor-of-choice. So, for all you Clojure noobs out there, here's my quickstart for Clojure that keeps it simple. It goes without saying that you need a Java VM installed - preferably 1.6 or 1.7. These instructions are for most Linux flavors; Windows will be slightly different but not much with variations mostly in the location of files or folders.

Get Sublime Text 2

First, download Sublime Text 2. You'll get a full version with no time or feature limits - just pay the $60 (CAD) if you find you like it as we really need to keep this fantastic editor going.

Once installed, there are a few plugins that make life easier. Install Package Control first, then follow the instructions for Package Control to install the following:

• Alignment
• BracketHighlighter
• Git
• SidebarEnhancements
• SublimeCodeIntel
• SublimeRepl

There are more recommendations for plugins online, but these will do for now. Take some time to play around with Sublime Text and learn how to use it effectively. The NetTuts+ tutorials are excellent - watch the videos & play around a bit ... or just keep going:

Get Leiningen

The Clojure survey also shows that Leiningen was everyone's favorite Clojure tool by a mile, and with good reason: version 2 is way easier to use and slicker than version 1, and automates so many Clojure-related tasks you won't do well without it.

To install, download the lein script (or batch file if you're on Windows) from the Github site, put it on your executable path and, if necessary, change the permissions to make it executable. Job done. The first time you run Leiningen (try lein help) it will download any additional code or plugins necessary automatically.

The clunkiest part of setting up Leiningen is specifying your default plugins. For that, you create a profiles.clj file in the .lein folder under your home directory. Read the docs for the full spec of the projects file, but here's mine for starters:

{:user {:plugins [[lein-difftest "1.3.8"]
                  [lein-marginalia "0.7.1"]
                  [codox "0.6.3"]
                  [lein-pprint "1.1.1"]]}}

Alternatively, you can add these later as dev dependencies in the project.clj file when you create the project ... more on that right now.

Make A Project

In whatever workspace you use, create a sample application with lein new app <name>.

Start up Sublime Text 2, and add the app to the (as yet unsaved, default) project by clicking Project/Add Folder to Project. You should see the code tree created by Leiningen in the navigator on the left. Save out the project to the app folder and you will see *.sublime-project and *.sublime-workspace files appear in the navigator.

Change to the new app folder and run the app with lein run. You should see compilation messages, followed by the "Hello World!" message from the app.

Check The Project In To Source Control

Assuming you're using Git for source control - and if not, why not!? - you can create your Git repository and import the project without leaving Sublime.

Bring up the command palette (ctrl+shift+P) and type init. The highlighted command at the top of the list should be Git: Init. Hit enter, confirm the folder to create the repo in at the bottom of the screen (it should be the project folder) and you're done, you have a git repo for your project. Note that Leiningen automatically created an appropriate .gitignore file when it created the project.

Command palette again, this time type add. The highlighted command should be Git: Add.... Select "All files including untracked files" from the pop-up menu, then hit enter and all your files are now staged.

Command palette, type commit and check that Git: Commit is highlighted, hit enter. The Git COMMIT_EDITMSG window will open with the cursor set at the top. Just type in your commit message, then hit ctrl+w (close window) - Sublime will automatically commit once the window is closed. The results of the commit are shown in the console at the bottom of the screen.

You can check your commits from the command palette by typing either log (Git: Log All) or graph (Git: Graph All).

In future, if you've cloned the project from a remote repository, you can use the command palette with the command push to push changes to that repo, or pull to pull & merge remote changes.

There, wasn't that easy.

Customization

So that I minimize the times I have to switch from Sublime to a command line, I put together a simple Build System for Sublime to drive Leiningen. Copy the following and place it in a file called Leiningen.sublime-build in the Sublime user packages folder (~/.config/sublime-text-2/Packages/User on Linux).

{
  "cmd": ["lein", "compile", ":all"],
  "working_dir": "$project_path",
  "selector": "source.clojure",
  "variants": [
    { "cmd": ["lein", "marg", "-m", "-d", "doc"],
      "name": "Lein: Marginalia"
    },
    { "cmd": ["lein", "doc"],
      "name": "Lein: Codox"
    },
    { "cmd": ["lein", "clean"],
      "name": "Clean"
    },
    { "cmd": ["lein", "run"],
      "name": "Run"
    },
    { "cmd": ["lein", "test"],
      "name": "Test"
    },
    { "cmd": ["lein", "retest"],
      "name": "Re-test"
    },
    { "cmd": ["lein", "uberjar"],
      "name": "Uberjar"
    },
    { "cmd": ["lein", "jar"],
      "name": "Jar"
    },
    { "cmd": ["lein", "check"],
      "name": "Check"
    }
  ]
}

Select this as the build system for the project using Tools/Build System/Leiningen.

You can then bring up the command palette (ctrl+shift+P on Windows/Linux) and issue any of the commands (build, documentation, clean, run, test, etc). By default, build is bound to ctrl+b and run to ctrl+shift+b.

Build The Documentation

Assuming you've configured Leiningen as above, and added the build system to Sublime, you can go to the command palette and type marginalia. This will use Leiningen & Marginalia to generate project docs from the code in a new doc folder - you should see it pop up in the navigator when the build is complete.

Open the doc folder, right-click on toc.html and select Open in Browser (you did install the SidebarEnhancements plugin, right?).

Bingo. There's your project's documentation. If you prefer, you can also use the command Codox to produce Codox-formatted API documents. Your preference.

Conclusions

And that's it. From nothing to a working Clojure environment in around 20-30 mins. Now you have a whole lot of reading to do around Clojure, Leiningen, Sublime, and so on, but you also have a simple, stable and very fast development environment. Enjoy!