Following are instructions for 1) one particular setup for beginning to work in Clojure, and 2) one particular sequence of learning materials. They may not be the best for everyone! But this is what I am currently recommending for my students, many of whom are undergraduates who have taken a few computer science courses but aren’t (yet) experienced software developers or Lisp/Clojure programmers. A somewhat more comprehensive, somewhat less opinionated (but still pretty opinionated) list of Clojure resources is available here.
Setup
Install Java if it’s not already installed.
Install Visual Studio Code (VSCode).
Launch VSCode, and within it click the extensions icon (which is made of four little squares, and is probably on the left side of the window) and install the Calva extension.
Most things that you’ll want to do in Calva can be done through the “Command Palette,” which you can access through View
> Command Palette
, and/or through the REPL
icon in the status bar at the bottom of the window. If you type “calva” in the Command Palette search field then you’ll see all of the Calva-related commands, of which there are a lot! You’ll probably only need a few, which you’ll be able to find more directly by typing more of the command name, and VSCode will also suggest commands that you use a lot.
When using VSCode, you always want to be working within a project, which consists minimally of a few folders and files, to which you will add your own code.
There are many ways to create a project, but here I will describe only the way to use Calva’s Create a mini Clojure project
command. This creates a project folder with the recommended structure, a single Clojure file (src/mini.clj
) and a VSCode/Calva settings file (.vscode/settings.json
).
To make a “Mini” project, first create an empty folder in your operating system with whatever name you want. Then, in the VSCode Command Palette choose Calva: Create a mini Clojure project
, click OK
, find and select the folder you made, and click Open
.
When you’re working on Clojure code in Calva you will almost always want to have a “REPL” (Read Eval Print Loop) running and “jacked in” to your project. This allows you to evaluate expressions and see their results, supporting an interactive mode of experimentation and development that most people find to be super helpful. One of the pre-set settings in a “Mini” project will cause the REPL to start up and jack in automatically when you create the project and also when you re-open it later. So you may never have to manually start it or jack in. But if you do, you can do it via REPL
, selecting deps.edn
when asked for the project type.
To begin editing and evaluating expressions, first find and open the Clojure file that the Create a mini Clojure project
command will have created in your project. To do this, first click on the Explorer
icon at the top of the icon bar on the left side of your VSCode window – this looks sort of like a stack of documents. You should then see all of the folders and files in your project. All Clojure files should be in the src
folder, and since your new mini project contains just one folder within src
, called mini
, this will be shown as src/mini
. Click on that to see playground.clj
, which is the Clojure file that was created for you. Double-click on playground.clj
to open it in the editor pane.
To evaluate any top-level expression in the editor panel place the cursor in or just after the expression, hold down the option
(or Alt
) key, and hit return
(or Enter
). Results will appear inline in the editor (but they’re not really in the file!) and also in the Terminal pane. Clear the inline results from the editor pane by hitting the esc
key.
Before you evaluate any other expressions in the editor pane you should evaluate the ns
expression at the top of the file. This creates the namespace within which all definitions in the file will be defined and all of the expressions in the file will be evaluated. Alternatively, if you want to evaluate the ns
expression and everything else in the file, use the Calva: Load/Evaluate Current File and its Requires/Dependencies
command.
Code within (comment ...)
expressions in your file will be ignored when you Load/Evaluate
the file, and also when the file is required by another file. However, this code will be evaluated if you put the cursor within it and hit option
/Alt
+ return
/Enter
. Because of this, many people put example function calls, experiments, etc. inside of (comment ...)
expressions. This allows them to load the whole file to evaluate their function and constant definitions and then to evaluate individual examples manually, one by one.
If you are in the “strict” editing mode (which prevents you from deleting some brackets, among other things) then you may want to get out of it by clicking on the lambda near the bottom right corner of the window until it is surrounded by ()
rather than []
. Some people love strict editing mode, and there is a lot of support for it in Calva. I don’t like it myself, and always turn it off.
You can fix the indentation in an expression by clicking in it and hitting the tab
key. However, this only works reliably if all of the brackets in the expression match, so if you’re not in strict mode then you might have to add or delete some brackets to do this; Calva uses color and highlighting to help you match brackets. Alternatively, you can usually fix the indentation in an incomplete expression by selecting it, cutting, and then pasting. However you do it, it’s a good idea to re-indent frequently, and also to avoid putting too much code on a single line. This makes the structure of your expressions clear from their shapes.
You can interrupt long-running computations with the Calva: Interrupt Running Evaluations
command, which you can call from the Command Palette or by clicking REPL
. This stops the ongoing computation but leaves the REPL running so you can keep working. If you’ve messed up your environment and want to start over, you can kill and restart the REPL by selecting Restart the Project REPL
from REPL
When you want to create your own new folders and files within your project you might want to stick initially to names made only of lower-case letters. Other characters are allowed, but the rules for using them are in some cases a bit peculiar. For example, folder and file names within your project can also include underscores, but references to them within your program have to use hyphens in place of the underscores. This doesn’t apply to the top-level folder that contains your whole project, but it applies to everything within it.
Two changes that you might want to consider making to the settings in .vscode/settings.json
concern the automatic typing of closing brackets/quotes and the abbreviation of long sequences in printed results:
- By default, Calva will automatically type closing brackets/quotes when you type the opening brackets/quotes, which many people like but I don’t. If you don’t either, then you can turn this off by adding this to your settings, separated from other settings with a comma:
"editor.autoClosingBrackets": "never"
- By default, Calva will abbreviate the printing of long sequences with
...
. This can be useful if you accidentally try to print something huge or even infinite (in which case you would otherwise have to restart your REPL to regain control). However, the abbreviation can be a problem if you really want to print long sequences and see them in their full glory. I always turn this feature off. You can do this by adding the following (the key part of which is thenull
on the last line) to your settings, separated from other settings with a comma:
"calva.prettyPrintingOptions": {
"printEngine": "pprint",
"enabled": true,
"width": 120,
"maxLength": null
}
Later you may want to install the CLI tools, and run your program from your operating system command line. One way to do this is to define a function that takes a single argument, which will be called with a map of key/value pairs from the command line. For example, we could include this in our playground.clj
file:
(defn joke [args]
(println "Called with:" args))
If we do that, then this command at the operating system command line:
clj -X mini.playground/joke :funny 1000 :style "knock-knock"
would print:
Called with: {:funny 1000, :style knock-knock}
Learning Materials
Start by watching Clojure in a nutshell by James Trunk, but don’t worry that it mostly uses a different setup than recommended here.
Then read the Learn Clojure guide from clojure.org.
Try and experiment with the following exercises (in any order):
- 4Clojure, interactive Clojure problems, gamified
- Clojinc, a saved REPL session intended to support semi-independent learning of Clojure
- Clojestions, suggested exercises for learning Clojure
You may also want to check out the introduction to Clojure that’s embedded in Calva’s Getting Started REPL, which you can start with the Calva: Fire up the Getting Started REPL
command.
Another good introduction is Chapter 3 (“Do Things: A Clojure Crash Course”) of Clojure for the Brave and True by Daniel Higginbotham. The whole book is also available, but note that some of the rest focuses on tools that I am not recommending here (e.g. leiningen and emacs).
At some point, check out the Clojure Style Guide.
You’ll probably find the Clojure cheatsheet to be helpful too, along with ClojureDocs.
Note that many of the comments below were written in response to an earlier version of this post, which you can still find in the history, but which may no longer be relevant.